Agent Experience

Every demo on this page runs live against the same endpoints an external agent uses — nothing is mocked. Demo calls count as real external MCP traffic in the admin telemetry.

Four Surfaces

AGENTS.md

One universal contract at the repo root — the standard that 28+ coding tools read.

Raw-markdown docs

Every published doc also serves raw markdown at its URL + .md, and the clean URL honors Accept: text/markdown.

/llms.txt

A curated URL map built from the docs manifest on every request — it cannot drift and cannot leak an unpublished doc.

MCP tools

Six read-only tools over HTTP and stdio; every error carries concrete recovery steps.

Markdown for Machines

A fetch of a clean docs URL with Accept: text/markdown is redirected (303 + Vary: Accept) to the .md variant; a browser navigating the same URL keeps getting HTML.

llms.txt

Built per request from the published docs manifest, with a Stripe-style instruction block that corrects stale model priors at fetch time.

Self-Correcting Errors

Registry errors end with a machine-parsable “## Next actions” trailer — a named next call recovers an agent far better than prose. Transport-level failures stay bare on purpose.

The validate_snippet Loop

The loopable convention checker: submit a snippet, apply the fixes, resubmit until it reports clean. Findings are a successful result — only empty or oversize input is an error.

Language

The exact request an agent sends

POST /api/mcp/public

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_snippet",
    "arguments": {
      "snippet": "<your snippet>",
      "language": "svelte"
    }
  }
}

AGENTS.md

The universal contract for non-Claude agents, served straight from the repo root at build time. Deliberately minimal — stack truth lives in /docs, not here.

AGENTS.md

# Repository Guidelines

Velociraptor (v10r) is a SvelteKit pattern library for adaptation. Claude Code follows
[CLAUDE.md](CLAUDE.md).

## Project Structure

- `src/routes/`: localized pages under `[[locale=locale]]/`; REST/SSE under `api/`.
- `src/lib/components/`: reusable UI; `src/lib/state/`: shared rune state.
- `src/lib/server/`: domains, database schemas/access, and integrations.
- `static/`: assets; `content/`: authored content; `messages/`: translations.
- `pattern-library/`: canonical registry; `mcp/`: stdio transport; `scripts/`: tooling.

## Development and Validation

Claude Code cloud sessions are the default place to develop: no container, no secrets,
commands run directly (`bun run validate`). Local sessions run tooling inside the `v10r`
Podman container. What runs where, and what to report as not run:
[development-environment.md](docs/foundation/development-environment.md).
Never run package managers on the host; keep `package.json` and `bun.lock` synchronized.

```bash
bun run validate                     # authoritative gate (cloud)
bun run validate:build               # + production build and perf ratchet
podman compose up -d                 # local: start development on :5173
podman exec v10r bun run validate    # local: the same gate in the container
```

The gate includes typechecking, Biome, tests, registry/excerpts, i18n/content, and quality
checks. No CI pipeline exists. Report failures accurately.

## Architecture and Coding Style

Keep domains framework-free; adapters own HTTP responses, redirects, and date
serialization. Never import `#lib/server/` into `.svelte` or universal `+page.ts`.
Change code directly: no compatibility layers, migration shims, or deprecation paths.

Follow `biome.json`: tabs, LF, 120-column width, single JS quotes, semicolons, trailing
commas. Use PascalCase components, kebab-case modules, and `.svelte.ts` for runes.
Consult [docs/naming.md](docs/naming.md) before introducing names; comments explain why —
the principle behind both is [docs/foundation/self-expressive-project.md](docs/foundation/self-expressive-project.md).
Never name a prop `state`.

Use existing components instead of raw buttons, inputs, selects, or textareas.
Exceptions: hidden inputs, table-row checkboxes, numeric selects, and specially styled
interactive regions. Colors use `src/app.css` tokens.

## Testing

Co-locate Vitest `*.test.ts`; database tests use `*.pglite.test.ts` and PGlite.
Run one file with `bunx vitest run <path>` (locally: `podman exec v10r bunx vitest run <path>`).
MCP uses `bun:test` (`test:mcp`). Test invariants, security, and regressions; verify UI
through browser showcases. No coverage threshold is configured.

## Documentation and Generated Files

Start at [docs/README.md](docs/README.md); navigate directory READMEs before topics.
Never grep blindly through `docs/`. Read `docs/codebase-organization.md` and
`docs/system-abstraction.md` for architecture. Reference canonical sources; avoid duplicate
stack documentation.

Never hand-edit generated pattern pages, Paraglide output, MCP excerpts, or retrieval
indexes. Use `package.json` generators; `refresh` also ingests docs into
the database. See [mcp/README.md](mcp/README.md) for machine-readable access.

## Commits and Branches

History mixes informal subjects with `feat(scope):` and `refactor(scope):`; prefer
descriptive subjects that explain behavior.

Work on a feature branch: commit and push it, hand off the branch and its HEAD SHA, and stop.
No PR is needed; a PR is only the fallback vehicle of a ship. GitHub `main` moves only when
Stas explicitly says to ship in the conversation — then follow
[shipping.md](docs/stack/ops/shipping.md) (squash into `main` → GitLab sync → Vercel). Never push
`main` or GitLab, never force-push, stash, or reset. Run a `vr` command only when
specifically requested.

Name every branch you create `<agent>/<env>/<feature>`: `<agent>` is `claude` or `codex`; `<env>` is `cloud` in a cloud environment (Claude: `CLAUDE_CODE_REMOTE=true`; Codex: no `~/.codex/` directory), otherwise `local`; `<feature>` is short kebab-case. Example: `claude/local/add-login-page`. Rename an auto-named branch (`claude/brave-bohr-9jw2fq`) to this form before its first push.

← Back to Showcases

Think this pattern could be better? Tell us how.

Leave feedback