Skip to main content

Agent Experience

The four agent-facing surfaces proven live — AGENTS.md, raw-markdown docs with content negotiation, /llms.txt, and MCP errors that tell agents how to recover.

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 
# AGENTS.md

Instructions for AI coding agents working in this repository. Claude Code reads
`CLAUDE.md` instead, which supersedes this file for Claude.

This file carries only the universal contract. Anything stack-specific lives in
`/docs`; anything Claude-specific lives in `CLAUDE.md`. Do not add a stack table
here — a second hand-maintained corpus is the failure mode this file avoids.

## What this project is

Velociraptor (v10r) is a full-stack reference and test-sandbox: proven,
high-performance SvelteKit patterns that an AI agent reads and adapts to a new
project. Emulation, not cloning. Full goals: `docs/foundation/PRD.md`.

## Non-negotiables

1. **Container-first.** Never run a package manager on the host machine. All
   tooling, dependencies and the runtime live in the `v10r` Podman container;
   add dependencies to `package.json` and install inside the container.
2. **Component-first.** Never use a raw `<button>`, `<input>`, `<select>` or
   `<textarea>` when a `$lib/components/` component exists. Exceptions:
   `<input type="hidden">`, `<input type="checkbox">` inside table rows,
   `<select>` binding numeric values, and custom interactive regions that need
   specialized styling.
3. **No backward compatibility.** Active development, no production users. No
   migration shims, no compat layers, no deprecation paths — change the code
   directly.
4. **Never run a `vr` command on your own initiative.** `vr` is the host-side
   dev CLI; `vr ship` deploys to production. Run one only when the user
   explicitly asks for that specific command.

## The gate

```
bun run validate
```

One command (typecheck + biome + tests + registry/i18n/content/quality checks),
run inside the container. There is no CI pipeline — this gate is the authority.

## Finding documentation

Every documentation directory has a `README.md` navigation hub with a topic
table. Read the directory README first, use its table to pick the file, then
read the file. Never grep blindly through `docs/`.

Architecture entry points: `docs/system-abstraction.md` (how the system runs)
and `docs/codebase-organization.md` (where code lives).

## Machine-readable surfaces

- `/llms.txt` — curated URL map of the published documentation (absolute URLs).
- Every published `/docs/**` page also serves raw markdown at the same URL with
  `.md` appended, and honors `Accept: text/markdown` on the clean URL.
- `POST https://www.v10r.dev/api/mcp/public` — hosted read-only MCP server
  (JSON-RPC 2.0 over HTTP): pattern search, curated pattern cards, file
  excerpts, emulation plans, and a loopable `validate_snippet` checker.
- `mcp/server.ts` — the same tools as a local stdio MCP server, spawned as an
  ephemeral Podman container (`.mcp.json` has the invocation).

## For Claude Code

Read `CLAUDE.md` — it carries the agent delegation policy, model selection, and
the skills policy. This file deliberately does not.
← Back to Showcases

Think this pattern could be better? Tell us how.

Leave feedback