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

Run tooling inside the `v10r` Podman container.
Never run package managers on the host; keep `package.json` and `bun.lock` synchronized.

```bash
podman compose up -d                 # start local development on :5173
podman exec v10r bun run build       # production build
podman exec v10r bun run test        # Vitest suites
podman exec v10r bun run lint        # Biome checks
podman exec v10r bun run validate    # authoritative gate
```

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 `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 Pull Requests

History mixes informal subjects with `feat(scope):` and `refactor(scope):`; prefer
descriptive subjects. PRs should explain behavior, link relevant issues,
report validation, and include screenshots for UI changes.

Preserve uncommitted work. Never stage, commit, push, stash, or reset without explicit
instruction. Run a `vr` command only when specifically requested; `vr ship` deploys.

← Back to Showcases

Think this pattern could be better? Tell us how.

Leave feedback