create-pracht 0.6.0 → 0.6.2

package/skills/add-capabilities/SKILL.md

@@ -0,0 +1,409 @@
+---
+name: add-capabilities
+version: 1.0.2
+description: |
+  Expose an app operation as a typed pracht capability — one contract projected
+  into direct server calls, an HTTP endpoint, a WebMCP page tool, and a remote MCP
+  tool — plus `defineApp({ agents })` trust config, typed clients,
+  `<Form capability>`, and `pracht eval` scenarios.
+  Use for "add a capability", "expose this to agents", "add an MCP tool", "add
+  WebMCP", "serve remote MCP", "make my app agent-callable".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Add Capabilities
+
+A capability is a protocol-neutral operation (`docs/CAPABILITIES.md`). Every
+projection runs the identical pipeline, so rules never diverge per transport:
+
+```text
+input validation → named middleware chain → run() → output validation
+```
+
+Registration is opt-in and private by default: no loader or API route is ever
+inferred as a capability, and an app that registers none ships no capability
+dispatch surface (the build drops ~15 KB gzip of dispatch and verifier code).
+Other agent-facing surfaces such as `llms.txt` remain independent.
+
+## Step 1: Decide the contract before writing code
+
+Settle these with `AskUserQuestion` when the request is vague:
+
+- **Name** — dot-separated segments (`notes.search`); this is the agent-visible
+  identity and the MCP tool name (dots become underscores).
+- **Effect** — `read`, `write`, or `destructive`. This drives confirmation
+  gating, client revalidation, and MCP annotations. Classify honestly.
+- **Exposure** — private (omit `expose`), `http`, `webmcp` (requires `http`),
+  `mcp`. Capabilities are manifest-router only; the pages router has no
+  manifest to register them in.
+- **Authorization** — which named middleware runs, and whether the endpoint
+  requires a verified agent (`agentPolicy: "require"`).
+
+Exposure matrix the runtime, `defineCapability()`, and `pracht verify` all
+enforce:
+
+| Effect | `http` | `webmcp` | `mcp` |
+| ------ | ------ | -------- | ----- |
+| `read` / `write` | yes | yes (needs `http`) | yes (needs `agents.mcp`) |
+| `destructive` | yes — always confirmation-gated | rejected | yes — needs `agents.mcp.destructive` **and** a registered approval store |
+
+## Step 2: Install and scaffold
+
+`create-pracht` does not add the package, because an app without capabilities
+should not carry it:
+
+```bash
+npm install @pracht/capabilities
+pracht generate capability --name notes.search --effect read --expose http,webmcp \
+  --description "Find notes whose title or body matches the query."
+```
+
+The generator writes `src/capabilities/notes-search.ts` with `expose`,
+`effect`, and `input` as inline literals and registers the name in the
+manifest. `--description` is required whenever `--expose` is set — that text is
+the contract an agent reads. It refuses the combinations the runtime rejects
+anyway. The MCP `generate_capability` tool does the same thing.
+
+If dispatch answers `500 internal_error` and `pracht inspect capabilities`
+prints capabilities as `unreadable`, the package is missing — that is the
+symptom.
+
+## Step 3: Write the capability
+
+```ts
+// src/capabilities/notes-search.ts
+import { defineCapability, type CapabilityRunArgs } from "@pracht/capabilities";
+import { searchNotes } from "../server/notes-store.ts";
+
+interface SearchInput {
+  query: string;
+  limit: number;
+}
+
+export default defineCapability({
+  title: "Search notes",
+  description: "Find notes whose title or body matches the query.",
+  input: {
+    type: "object",
+    properties: {
+      query: { type: "string", minLength: 1 },
+      limit: { type: "integer", minimum: 1, maximum: 20, default: 10 },
+    },
+    required: ["query"],
+    additionalProperties: false,
+  },
+  output: {
+    type: "object",
+    properties: { notes: { type: "array", items: { type: "object" } } },
+    required: ["notes"],
+  },
+  effect: "read",
+  middleware: ["auth"],            // names from the app manifest
+  expose: { http: true, webmcp: true },
+  // webmcp: { untrustedContent: true } advertises untrustedContentHint for
+  // page tools whose results carry user-generated content.
+  // agentPolicy: "require",       // verified Web Bot Auth agents only —
+  //                               // never combine with webmcp: page-tool
+  //                               // calls are unsigned and would always 401
+  async run({ input, context, request, signal }: CapabilityRunArgs<SearchInput>) {
+    return { notes: searchNotes(input.query, input.limit) };
+  },
+});
+```
+
+Schema rules that bite:
+
+- Only a **subset** of JSON Schema is accepted: `type`, `properties`,
+  `required`, `additionalProperties`, `items` (single schema), `enum`, `const`,
+  `minimum`, `maximum`, `minLength`, `maxLength`, `default`, plus `title` and
+  `description`. `oneOf`, `anyOf`, `allOf`, `$ref`, `pattern`, `format`, and
+  tuple `items` throw at definition time — a keyword the validator would ignore
+  could widen what an exposed capability accepts.
+- Inputs and outputs are JSON data only. `File`, `Blob`, `Date`, `Map`,
+  `undefined`, and cycles are rejected — keep uploads in API routes.
+- `expose`, `effect`, and (for webmcp) `input` must be **inline literals**: the
+  browser projection is built by static analysis, and an imported constant or
+  spread fails the build.
+- MCP exposure additionally requires both schemas rooted at `type: "object"`.
+- Annotate `run()` with `CapabilityRunArgs<Input>` so TypeScript still infers
+  the output; `defineCapability<Input>` alone leaves the output `unknown`.
+
+## Step 4: Register it, and configure `agents` only if needed
+
+```ts
+// src/routes.ts
+export const app = defineApp({
+  capabilities: {
+    "notes.search": () => import("./capabilities/notes-search.ts"),
+  },
+  agents: {
+    // Verified agent identity (public keys — safe in the manifest).
+    webBotAuth: { policy: "observe", directories: ["https://signature-agent.cloudflare.com"] },
+    // Destructive prepare/commit tuning.
+    confirmation: { ttlSeconds: 120 },
+    // Remote MCP endpoint; without this, `expose.mcp` serves nothing.
+    mcp: { serverInfo: { name: "notes", version: "1.0.0" }, instructions: "…" },
+  },
+  routes: [/* … */],
+});
+```
+
+Each `agents` sub-option is independent — add only what the app uses. Web Bot
+Auth `policy: "require"` gates capability HTTP endpoints (not pages or API
+routes) with `401 agent_required`; `agentPolicy: "require"` on a capability
+fails closed even when `webBotAuth` is unconfigured.
+
+### Authenticating the MCP endpoint (`agents.mcp.auth`)
+
+`agents: { mcp: {} }` alone serves an **open** endpoint — anyone who can reach
+the URL can call every `expose.mcp` tool, and authentication is whatever the
+capability's named middleware does with the forwarded `Authorization` header.
+That is fine for a public read surface and wrong for anything scoped to a user.
+
+Add `auth` and `/mcp` becomes an OAuth 2.0 protected resource: pracht publishes
+RFC 9728 metadata at `/.well-known/oauth-protected-resource`, answers
+unauthenticated calls with the `WWW-Authenticate` challenge MCP hosts follow,
+and calls your `verify` module. This is what makes a real host (Claude, a
+ChatGPT connector) able to connect at all.
+
+```ts
+mcp: {
+  serverInfo: { name: "notes", version: "1.0.0" },
+  auth: {
+    resource: "https://app.example.com/mcp",       // absolute; token audience
+    authorizationServers: ["https://auth.example.com"],
+    scopesSupported: ["notes.read", "notes.write"],
+    requiredScopes: ["notes.read"],                // optional per-request gate
+    verify: () => import("./server/mcp-token.ts"), // server-only module
+  },
+},
+```
+
+Rules to hold the user to:
+
+- **`verify` is a module reference, never an inline function.** The manifest is
+  bundled into the client; a JWKS client in it would ship to every visitor.
+  Put the module in `src/server/` and default-export the verifier function. It
+  must live under `src/server/`, `src/middleware/`, or `src/capabilities/` —
+  those are the only directories the build globs into the module registry, and
+  a verifier anywhere else is never loadable, so every `/mcp` request 401s
+  forever. `pracht verify` errors on that, but do not create the file elsewhere.
+  If the same suffix exists in more than one registry directory, lookup rejects
+  it as ambiguous; use a root-relative reference such as
+  `() => import("/src/server/mcp-token.ts")`.
+- **Security option names are exact.** Unknown keys under `agents.mcp` and
+  `agents.mcp.auth` are rejected instead of ignored; do not work around the
+  error with casts. The MCP path must also differ from every explicit API route
+  path, or `pracht verify` rejects the graph and the runtime fails closed with
+  500 before the API handler can bypass MCP's gates.
+- **Pracht is not an authorization server.** Do not offer to implement token
+  issuance, refresh, or dynamic client registration — those belong to the
+  user's identity provider. Write `verify` with their library (`jose` works on
+  Workers and Vercel Edge) and **bind `audience` to the `resource` value**, or a
+  token minted for another service on the same issuer is accepted.
+- **It fails closed.** `null`, a throw, or a malformed principal all give
+  `401 invalid_token`; a missing required scope gives `403 insufficient_scope`.
+  When `requiredScopes` is set, every challenge advertises it so hosts request
+  the right grant on the first authorization attempt. The verifier receives an
+  independent request clone, so reading its JSON-RPC body does not consume the
+  body that MCP dispatch reads next.
+- **The principal is `context.tokenAuth`** — a frozen `{ subject, scopes?,
+  clientId?, claims? }`, alongside `context.agent`. Use it in named middleware
+  and `run()` for per-user authorization; the framework only authenticates. It
+  lives on a fresh request-local overlay, leaving an adapter's reused base
+  context unchanged. Frozen and sealed ordinary contexts work; native built-ins
+  such as `Map` and `Date` must be wrapped in an ordinary context. `claims` is
+  frozen shallowly, but the complete principal is request-local so nested
+  mutations cannot become stale auth on a later request. The capability audit
+  event does not carry it yet, so capture it in named middleware or capability
+  code and send it to the same audit sink if MCP calls must be attributable to
+  an account. Nested capability calls rebind this field to the transport-verified
+  principal, so caller-supplied composition context cannot replace it.
+- `resource` must be the endpoint's **real deployed URL**: absolute, free of
+  query/fragment, free of a non-root trailing slash, and exactly matching the
+  served endpoint's public path — deploy base included, e.g.
+  `https://app.example.com/app/mcp` for an app mounted at `/app/`.
+  `resolveApp()` and `pracht verify` reject otherwise. The metadata document
+  then lands at the origin root with the base inside the suffix
+  (`/.well-known/oauth-protected-resource/app/mcp`); pracht derives it. Require
+  HTTPS outside loopback development, and reject authorization-server issuers
+  with query strings or fragments. For `mcp.path: "/"`, the resource is the
+  deployed app root, including its base; at the origin root use slashless
+  `https://app.example.com`. Authenticated requests whose URL is not
+  exactly this identifier are redirected to it with `308` before token
+  verification. Scope values must use OAuth's printable ASCII grammar (no
+  spaces, controls, non-ASCII, quotes, or backslashes).
+- The bare `/.well-known/oauth-protected-resource` path is reserved for
+  discovery and cannot be used as `mcp.path`. Production adapters route both
+  metadata forms ahead of copied static files.
+- `pracht plan` snapshots the OAuth policy separately from the endpoint path.
+  Removing `auth` or a required scope, or trusting another authorization server,
+  is a guard weakening even when `/mcp` itself did not move.
+
+See `docs/REMOTE_MCP.md` for the metadata document and the full `verify` recipe.
+
+## Step 5: Destructive capabilities
+
+`destructive` (delete, publish, pay, send, change access) may be exposed over
+`http` and `mcp`, never `webmcp`, and every dispatch is gated:
+
+1. Set `PRACHT_CONFIRMATION_SECRET` in the server environment (or call
+   `setCapabilityConfirmationSecret()` from `@pracht/core/server`). Without it,
+   calls fail closed with `403 confirmation_unavailable` and `pracht verify`
+   fails — verify reads the environment, so the variable must be set even when
+   the app registers the secret programmatically.
+2. A call without a token answers `409 confirmation_required` with a token
+   bound to principal + capability + canonical input + expiry.
+3. The commit repeats the call with byte-identical input plus the confirmation
+   header.
+
+Be honest about what this buys, and say so to the user
+(`docs/AGENT_TRUST.md`): stateless HMAC cannot prevent replay inside the TTL,
+the calling agent can hand the token straight back to itself, and without Web
+Bot Auth or `setCapabilityApprovalPrincipalResolver()` both phases run as
+`"anonymous"`. Register a `CapabilityApprovalStore` for exactly-once commits,
+and `confirmation: { mode: "human" }` for a real human decision — that mode
+fails closed without both a store and an authenticated principal.
+
+`createSqlApprovalStore({ execute })` from `@pracht/core/server` is the
+first-party durable store — no driver dependency, one implementation for
+Postgres, Cloudflare D1, and SQLite/Turso. Pass a parameterized-query function
+and run the migration from `docs/AGENT_TRUST.md`; use `dialect: "postgres"` for
+`$1` placeholders. `createMemoryApprovalStore()` is for tests and development
+only. A non-SQL backend needs atomic conditional writes (Durable Objects,
+Redis — not Cloudflare KV).
+
+### Destructive over remote MCP
+
+Off by default. To serve one:
+
+1. `agents: { mcp: { destructive: true } }` in `defineApp()`.
+2. Register an approval store from a server entry or a capability module, so it
+   exists before the graph is served. This is not optional — a token handed to
+   the committing agent must be consumable exactly once. The endpoint refuses
+   to serve at all when the store, `PRACHT_CONFIRMATION_SECRET`, or (in human
+   mode) any resolvable principal is missing; `pracht verify` warns when it
+   cannot find the registration in the configured source directories.
+3. The flow is unchanged; only the channel differs. Prepare answers
+   `isError: true` with the token in `_meta["io.pracht/error"]`, and the commit
+   repeats `tools/call` with identical `arguments` plus
+   `_meta["io.pracht/confirmation"]`.
+
+Nested `invokeCapability()` under an MCP tool still refuses destructive callees
+unless the tool being served is a destructive capability that already cleared
+prepare/commit.
+
+## Step 6: Call it
+
+```ts
+// Server: loaders, API routes, middleware — works for private capabilities too.
+import { invokeCapability } from "@pracht/core/server";
+const result = await invokeCapability("notes.search", { query: "roadmap" }, { request, context, signal });
+```
+
+```ts
+// Browser: generated, typed, http-exposed names only.
+import { capabilities, useCapability } from "virtual:pracht/capabilities";
+const result = await capabilities.notes.search({ query: "roadmap" });
+```
+
+```tsx
+// One contract for the human form and the agent tool.
+<Form capability="notes.create" onCapabilityResult={(result) => { /* … */ }}>
+  <input name="title" />
+  <button type="submit">Create</button>
+</Form>
+```
+
+- Prefer a loader + `invokeCapability()` for data a page needs on load;
+  `useCapability()` dispatches on interaction, never during render.
+- After a successful non-`read` call the route's data revalidates
+  automatically (`revalidate: false` opts out).
+- Capability modules are server-only: importing one from client code is a build
+  error, because nothing would strip `run()` and its database client out of the
+  browser bundle.
+
+## Step 7: Types, inspection, and proof
+
+```bash
+pracht typegen                 # emits src/pracht-capabilities.d.ts
+pracht inspect capabilities --json
+pracht verify --json           # contract, exposure, and projection checks
+pracht eval --start "pracht preview"
+```
+
+Once the declaration exists the compiler rejects unknown names, bad input,
+browser calls to private capabilities, destructive calls without
+`prepare`/`confirm`, and runtime-computed names (assert
+`as HttpCapabilityName`). Re-run `pracht typegen --check` in CI.
+
+`pracht eval` runs JSON scenarios against the live app and exits 1 on a failed
+expectation — the repeatable answer to "can an agent actually finish this
+task?". Steps can reference earlier results
+(`$steps[0].error.confirmationToken`) and a scenario-level `signAs` block signs
+every step as a verified agent.
+
+A scenario targets the HTTP projection by default; set scenario-level
+`"transport": "mcp"` to run the same steps over the app's remote MCP endpoint
+(`initialize` handshake, then one `tools/call` per step, tool names mapped
+`notes.search` → `notes_search`). Write one of each for any capability with
+`expose.mcp` — passing over HTTP does not prove an MCP host can reach it.
+If `agents.mcp.auth` protects the endpoint, add scenario-level
+`"mcpHeaders": { "authorization": "Bearer …" }`; it applies to `initialize`
+and every later request. Inject test tokens in CI instead of committing real
+credentials. Step-level `headers.authorization` overrides it for one call.
+Expectations are portable: `expect.status` is the capability dispatch status on
+both transports, so the same `{ "ok": false, "status": 400, "errorCode":
+"invalid_input" }` holds either way.
+
+Three MCP limits fail loudly rather than silently: a step for a capability
+without `expose.mcp`, a step header other than `authorization` (the projection
+forwards nothing else), and a destructive step whose app has not enabled
+`agents.mcp.destructive` with an approval store. For an exposed destructive MCP
+tool, `confirm` completes the same prepare/commit round trip as HTTP; the token
+travels in the call's `_meta["io.pracht/confirmation"]` field.
+
+`createCapabilityTestHost()` from `@pracht/core` covers the same pipeline in
+unit tests without a server.
+
+WebMCP specifics `pracht verify` checks for you: tool names must fit the
+spec's grammar (1–128 ASCII `[a-zA-Z0-9_.-]`); an effective
+`agentPolicy: "require"` makes a page tool dead (unsigned browser fetches
+always 401 — warned); descriptions have advisory budgets (~500 chars per
+tool, ~150 per schema parameter). Hosts: the ChatGPT desktop browser enables
+the API itself, but stable Chrome/Edge visitors only get
+`document.modelContext` if the page head carries an origin-trial token — the
+capabilities page on the docs site shows the shell `head()` recipe.
+
+For an audit of what the whole agent surface currently exposes, run
+`/audit-agent-surface`.
+
+## Rules
+
+1. Never expose a `destructive` capability over `webmcp`; expose it over `mcp`
+   only with `agents.mcp.destructive` and a durable approval store, and say so
+   to the user. Never reclassify a destructive operation as `write` to escape
+   the confirmation gate.
+2. Never widen a schema (drop `required`, open `additionalProperties`, raise a
+   `maximum`) without saying so — `pracht plan` reports it as a widening of the
+   agent-reachable surface for a reason.
+3. Keep `expose`, `effect`, and `input` as inline literals.
+4. Put authentication, authorization, and rate limiting in named middleware —
+   the framework ships no rate limiting, no write-idempotency helper, and no
+   result-size budget. Bound outputs with a `limit` input and a schema
+   `maximum`.
+5. Design `write` inputs to be safely repeatable; agents retry, and only
+   `destructive` calls are token-gated.
+6. Never register an app-wide approval endpoint or UI without your own
+   authorization — who may approve is an application decision.
+7. Re-run `pracht typegen` after changing a schema, name, or exposure, and
+   `pracht verify` before committing.
+
+$ARGUMENTS

package/skills/add-content/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: add-content
+version: 1.0.1
+description: |
+  Wire `@pracht/content` and `@pracht/markdown`: a collection registry owning
+  source discovery, routes, locales, compilation, and static artifacts
+  (`llms.txt`, raw source), plus Markdown/MDX route modules and snapshot loaders.
+  Use for "add a blog", "set up docs", "render markdown pages", "add MDX",
+  "content collections", "why is my markdown route 404ing".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Add Content Collections
+
+`@pracht/content` is the optional, **server-only** content layer
+(`docs/CONTENT.md`). It exists so a content-heavy app has *one* registry
+instead of two readers that drift — route modules reading source through Vite,
+and sitemap/`llms.txt`/search plugins scanning the filesystem again.
+`@pracht/markdown` is the opinionated Markdown route-module compiler on top of
+it (`packages/markdown/README.md`).
+
+Nothing here is on by default: adding a collection publishes no source and
+creates no agent surface until you add artifacts or capabilities.
+
+## Step 1: Pick the shape
+
+Ask with `AskUserQuestion` when it is not obvious from the repo:
+
+| Situation | Wiring |
+| --------- | ------ |
+| Markdown/MDX files that should *be* pages | `@pracht/markdown` → `defineMarkdownCollection()` |
+| Content that feeds loaders, search, or an API — never a page | `@pracht/content` → `defineCollection()` with `unroutedDocuments: "ignore"` |
+| An app-specific compiler (custom AST, page model, search record) | `defineCollection({ compile, module })` |
+
+Also settle: collection root directory, `routeBase`, whether documents are
+localized, and whether relative images appear in the Markdown.
+
+## Step 2: Install
+
+```bash
+pnpm add @pracht/content
+pnpm add @pracht/markdown @pracht/image   # Markdown route modules
+pnpm add -D sharp                          # only when documents embed local images
+```
+
+`sharp` runs at build/dev time only and never ships to a runtime bundle.
+
+## Step 3: Define the collection outside the vite config
+
+Put the collection in its own module (`content.ts`) so the vite config, build
+plugins, and tests import the same object:
+
+```ts
+// content.ts
+import { llmsTxtArtifacts, rawContentArtifacts } from "@pracht/content";
+import { defineMarkdownCollection } from "@pracht/markdown";
+
+export const docs = defineMarkdownCollection({
+  name: "docs",
+  root: new URL("./src/routes/docs", import.meta.url),
+  routeBase: "/docs",
+  // locales: { default: "en", supported: ["en", "fr"] },
+  // images: { placeholder: "blur" },      // default "empty" — keeps CSP unchanged
+  // snapshot: { raw: false },             // drop a representation you never read
+  artifacts: [
+    rawContentArtifacts({ path: (document) => `${document.path}.md` }),
+    llmsTxtArtifacts({
+      title: "Product docs",
+      origin: "https://example.com",
+      sections: [{ heading: "Docs", match: "/docs" }],
+    }),
+  ],
+});
+```
+
+Without `sources`, the registry scans `root` recursively for `.md`/`.mdx`;
+`index` files collapse to their directory. Pass explicit
+`{ id, path, source, locale }` entries when routes must not be inferred.
+Duplicate ids, routes, sources, or artifact paths throw at definition time
+rather than letting file order pick a winner.
+
+## Step 4: Register the plugins (order matters)
+
+```ts
+// vite.config.ts
+import { prachtContent } from "@pracht/content/vite";
+import { prachtImage } from "@pracht/image/vite";
+import { pracht } from "@pracht/vite-plugin";
+import { defineConfig } from "vite";
+import { docs } from "./content";
+
+export default defineConfig({
+  plugins: [
+    prachtContent({ collections: [docs] }), // one call, every collection
+    prachtImage(),                          // relative Markdown images
+    pracht(),
+  ],
+});
+```
+
+Register **all** collections through a single `prachtContent()` call — the
+plugin owns one internal build manifest and rejects a second registration.
+
+## Step 5: Point routes at the documents
+
+Markdown modules are ordinary route modules (they export `Component`, `head()`,
+and the raw `markdown` string for `Accept: text/markdown` negotiation):
+
+```ts
+route("/docs/routing", () => import("./routes/docs/routing.md"), {
+  id: "routing",
+  render: "ssg",
+});
+```
+
+Sources and routes are still two readers, so `pracht build` reconciles them and
+names every document (and generated locale alias) that no route serves — a
+document without a route still reaches `llms.txt` and `rawContentArtifacts()`
+while the page answers 404. The default policy is `"warn"`:
+
+```ts
+prachtContent({ collections: [docs], unroutedDocuments: "error" });
+```
+
+Use `"error"` for a docs site, `"ignore"` for a data-only collection. On a
+static export a dynamic SSG route only covers the concrete paths
+`getStaticPaths()` returns, and a dynamic SPA route only covers deep links when
+`staticAdapter({ fallback })` emits one. `pracht verify` cannot do this check —
+it reads the vite config as text — so run a build before believing the routing
+is complete.
+
+## Step 6: Read the collection at request time
+
+Loaders, middleware, API routes, and capabilities must import the **generated
+snapshot**, not the filesystem-backed authoring object:
+
+```ts
+import { contentLoader } from "@pracht/content/runtime";
+import docs from "virtual:pracht/content/docs";
+
+export const loader = contentLoader(docs, {
+  select: (document) => ({ html: document.compiled, title: document.frontmatter.title }),
+});
+```
+
+- The virtual module is **server-only**; a retained client import fails the
+  build instead of shipping source, frontmatter, and compiled values to the
+  browser.
+- Every accessor is async: each document's `raw`/`body`/`compiled` lives in its
+  own deferred chunk, so the first content-backed request does not parse the
+  whole collection. `iterate()` streams one document at a time; `all()` loads
+  everything.
+- `contentLoader()` uses the matched, base-free `pathname`, and answers
+  unmatchable pathnames (`/docs/%2e%2e`) with its not-found path instead of
+  failing the request.
+- `markdownRepresentation(document, "raw" | "body")` produces the server-only
+  `markdown` export for content negotiation — it throws when `snapshot` dropped
+  the field you selected.
+- Frontmatter and compiled values must be JSON-serializable; the build names
+  the offending value path otherwise.
+
+Add types once: `"types": ["@pracht/markdown/client", "@pracht/content/virtual"]`
+in tsconfig (or triple-slash references in any `.d.ts`).
+
+## Step 7: Artifacts and the two llms.txt files
+
+`llmsTxtArtifacts()` (collection-driven, curated, can emit an `llms-full.txt`)
+is **not** the same as the core `llmsTxt` plugin option (app-graph driven,
+`docs/LLMS_TXT.md`). Both default to `/llms.txt`, and enabling both fails the
+build rather than silently overwriting — pick one, or give the collection a
+distinct `summaryPath`. A third, unrelated file is `pracht llms`, which prints
+the *authoring guide* for coding agents; `pracht llms --write` drops it in the
+app root, which is exactly the confusing filename collision to avoid in an app
+that publishes its own index.
+
+Localization trap: a string `section.match` is compared against the
+**locale-neutral** route, so `match: "/docs"` indexes only the default locale
+while `rawContentArtifacts()` publishes every translation. Pass a `match`
+function to index one locale deliberately.
+
+Artifact paths are preflighted: canonical ASCII segments only, no overlap with
+`publicDir`, bundle output, prerendered pages, request-time page/API paths,
+concrete ISG paths, the `/_pracht` namespace, or Netlify's `/_headers` and
+`/_redirects`.
+
+## Step 8: Deployment notes
+
+- **Cloudflare** — deferred content chunks require `"no_bundle": true` and an
+  `ESModule` rule covering `"**/*.js"` in `wrangler.jsonc`; `pracht verify`
+  warns when either is missing. New `create-pracht` projects have both.
+- **Content type headers** — explicit artifact `contentType` values flow into
+  the production headers manifest and are applied by the Node, Cloudflare,
+  Netlify, and Vercel adapters.
+- **Bundle cost** — payload chunks carry roughly two to three times the source
+  bytes. `snapshot: { raw: false }` or `{ body: false }` drops a representation
+  the app never reads; `compiled` and frontmatter cannot be dropped.
+
+## Step 9: Optional agent surface
+
+`@pracht/content/capabilities` exports `createContentPageCapability()` and
+`createContentSearchCapability()`, which return `input`/`output`/`run` fields.
+Keep the literal `defineCapability({ ... })` in the app so `pracht verify` can
+audit exposure and policy statically — see `/add-capabilities`. Both helpers
+read `document.body` and refuse a body-free snapshot when constructed.
+
+## Step 10: Verify
+
+```bash
+pracht build          # reconciliation warnings + artifact preflight
+pracht verify --json
+pracht typegen        # after route ids or paths change
+```
+
+Then load a content route in `pracht dev`, edit a source file, and confirm the
+watcher invalidates it (collection roots outside Vite's project root are added
+to the watcher explicitly).
+
+## Rules
+
+1. **Compiled Markdown is executed as HTML, unsanitized.** The generated route
+   module renders through `dangerouslySetInnerHTML`. Only compile
+   repo-authored, reviewed content; sanitize in `parse` or `render` (e.g.
+   `sanitize-html`) before compiling anything from a CMS, a database, or a
+   user.
+2. Never import a capability-facing or loader-facing collection from client
+   code — import `virtual:pracht/content/<name>` inside server code only.
+3. One `prachtContent()` call, with every collection in it.
+4. Do not enable the core `llmsTxt` option and a collection `/llms.txt`
+   artifact at the same time.
+5. Adding a collection must not publish raw source implicitly — add
+   `rawContentArtifacts()` only when publishing sources is intended.
+6. Never overwrite an existing `vite.config.ts`, `wrangler.jsonc`, or content
+   module — diff first and confirm collisions with `AskUserQuestion`.
+
+$ARGUMENTS