create-pracht 0.6.0 → 0.6.2

package/skills/add-images/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: add-images
+version: 1.0.1
+description: |
+  Wire `@pracht/image`: the CLS-safe zero-runtime `<Image>`, the loader for your
+  target (sharp endpoint, Cloudflare, Vercel, passthrough), `?pracht` build-time
+  imports with blur placeholders, prebuilt WebP variants, and the optimization
+  endpoint's security settings.
+  Use for "add images", "optimize images", "responsive images", "next/image
+  equivalent", "blur placeholders", "my images cause layout shift".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Add Images
+
+`@pracht/image` splits the problem the way next/image does: the `<Image>`
+component decides *which widths* to render, a loader decides *what URL* serves
+each width (`docs/IMAGES.md`). The component renders a plain `<img>` — SSR-safe,
+zero hydration, works with `hydration: "none"`.
+
+## Step 1: Choose the backend for the deployment target
+
+MCP: when the pracht MCP server is registered (docs/MCP.md), prefer its
+`inspect_routes`/`inspect_build`/`doctor`/`verify` tools over shelling out.
+
+```bash
+pracht inspect build --json   # adapterTarget (requires a prior `pracht build`)
+```
+
+| Target | Loader | Notes |
+| ------ | ------ | ----- |
+| Node | `defaultLoader` + the built-in endpoint | needs `sharp`; put a CDN in front |
+| Cloudflare | `cloudflareLoader` | Image Resizing must be enabled on the zone; sharp does not run on Workers |
+| Vercel | `vercelLoader` | needs an `images` section in the project config; Vercel only serves widths listed in `images.sizes` |
+| Static host | `passthroughLoader` | no image service — srcset is omitted |
+| Any target, no runtime service | `?pracht&pracht-static` imports | prebuilt WebP variants, no loader involved |
+
+Confirm the choice with `AskUserQuestion` when the app deploys to more than one
+target — a per-target `configureImage()` behind an env flag is the usual answer
+(`examples/basic` does exactly this).
+
+## Step 2: Install
+
+```bash
+pnpm add @pracht/image
+pnpm add sharp              # only for the built-in Node endpoint
+pnpm add -D sharp           # only for `?pracht` imports / static variants
+```
+
+sharp stays an optional peer dependency; the vite plugin fails with an install
+hint when a `?pracht` import needs it, and the endpoint answers 500 with the
+same hint at runtime.
+
+## Step 3: Configure the loader once
+
+Put `configureImage()` where both the server and the browser evaluate it — the
+top of `src/routes.ts` is the canonical spot:
+
+```ts
+import { cloudflareLoader, configureImage } from "@pracht/image";
+
+configureImage({
+  loader: cloudflareLoader,
+  // deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
+  // imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
+  // quality: 75,
+});
+```
+
+`createDefaultLoader("/my/endpoint")` builds a default-style loader for a custom
+endpoint path. Root-absolute endpoints pick up Vite's deploy `base`
+automatically; provider loaders (`cloudflareLoader`, `vercelLoader`)
+deliberately stay at the origin root.
+
+## Step 4: Render images
+
+```tsx
+import { Image } from "@pracht/image";
+
+<Image
+  src="/banner.jpg"
+  alt="Product banner"
+  width={1200}
+  height={280}
+  sizes="(max-width: 1200px) 100vw, 1200px"
+  priority
+/>;
+```
+
+- `alt` is required — use `alt=""` for decorative images.
+- `width`/`height` are required unless `fill`; they reserve space and prevent
+  layout shift. Missing dimensions log a `console.error` in dev.
+- `sizes` (or `fill`) switches the srcset to `w` descriptors across
+  `deviceSizes`; a fixed image gets `1x`/`2x` candidates snapped to the
+  breakpoint list so caches stay small.
+- `priority` on above-the-fold images swaps `loading="lazy"` +
+  `decoding="async"` for `loading="eager"` + `fetchpriority="high"`. Use it for
+  the LCP image only.
+- `fill` positions the image absolutely inside the nearest positioned ancestor
+  and defaults `sizes` to `100vw`; pair with `style={{ objectFit: "cover" }}`.
+
+## Step 5: Build-time imports and static variants
+
+Register the plugin — the main `pracht()` plugin does **not** include it:
+
+```ts
+// vite.config.ts
+import { prachtImage } from "@pracht/image/vite";
+
+export default { plugins: [prachtImage(), pracht({ /* … */ })] };
+```
+
+```tsx
+import hero from "./hero.jpg?pracht";                 // { src, width, height, blurDataURL }
+import banner from "./banner.jpg?pracht&pracht-static"; // + prebuilt WebP variants
+
+<Image src={hero} alt="Hero" placeholder="blur" />;
+<Image src={banner} alt="Banner" sizes="(max-width: 960px) 100vw, 960px" />;
+```
+
+- Dimensions come from sharp metadata with EXIF orientation applied, so a
+  rotated portrait reports its *display* size.
+- `blurDataURL` is an 8px WebP data URI generated at build time. SVGs skip it,
+  animated GIFs blur their first frame.
+- `pracht-static` emits content-hashed WebP files at `staticWidths`, takes
+  precedence over the global loader, and is cached in Vite's `cacheDir` keyed by
+  source bytes. It requires an **absolute** Vite `base`; SVG and animated
+  sources pass through unchanged.
+- Root-relative `publicDir` imports keep stable public URLs and bypass the
+  runtime loader.
+- Types: `"types": ["@pracht/image/client"]` in tsconfig, or a triple-slash
+  reference in any `.d.ts`.
+
+`@pracht/markdown` uses `?pracht&pracht-static` automatically for relative
+Markdown images and renders them with `getImageProps()` — see `/add-content`.
+
+## Step 6: Mount the optimization endpoint (Node-compatible runtimes only)
+
+```ts
+// src/api/_pracht/image.ts
+import { createImageHandler } from "@pracht/image/node";
+
+const imageHandler = createImageHandler({
+  // Required in every environment, including dev. Your own env var, not a
+  // framework one — set it to the app's public origin and use the same value
+  // as nodeAdapter({ canonicalOrigin }).
+  localOrigin: process.env.PRACHT_ORIGIN,
+  // remotePatterns: [{ protocol: "https", hostname: "*.example.com", pathname: "/uploads" }],
+  // allowedWidths: [640, 1280],   // required when configureImage() customizes the breakpoints
+});
+
+export const GET = imageHandler;
+export const HEAD = imageHandler;
+```
+
+That file maps to `/api/_pracht/image`, exactly what `defaultLoader` targets —
+no further configuration. The endpoint negotiates WebP via `Accept` (pass
+`formats: ["image/avif", "image/webp"]` for AVIF), never enlarges beyond the
+source, passes SVG/GIF through, and answers
+`Cache-Control: public, max-age=14400, must-revalidate` with `Vary: Accept`.
+
+## Step 7: Verify
+
+```bash
+pracht dev            # set PRACHT_ORIGIN to the exact origin it prints
+pracht build
+pracht verify --json
+```
+
+Check in the browser: the `<img>` carries `srcset`/`sizes`, the LCP image is
+`fetchpriority="high"`, and no layout shift occurs on reload. Then run
+`/audit-bundles` and `/audit-seo` if image work was part of a performance pass.
+
+## Rules
+
+1. Never leave `localOrigin` unset — relative sources are resolved only against
+   it, so a forged `Host` cannot turn the endpoint into an open proxy. The
+   handler answers 500 until it is configured, including in dev.
+2. Always allowlist remote hosts with `remotePatterns`; never proxy arbitrary
+   URLs.
+3. When `configureImage()` customizes `deviceSizes`/`imageSizes`, pass the
+   matching `allowedWidths` — the endpoint rejects widths outside its allowlist
+   by design, and skipping this silently breaks the srcset.
+4. Do not use `priority` on more than the one above-the-fold image per route.
+5. `placeholder="blur"` writes an inline `style` attribute: a CSP without
+   `style-src-attr 'unsafe-inline'` silently drops it (and `fill` positioning),
+   and `img-src` must include `data:`. See `docs/CSP.md`.
+6. Platform loaders generate URLs that only resolve on the deployed platform —
+   fall back to `passthroughLoader` behind `import.meta.env.DEV` for local
+   previews.
+7. Use an immutable one-year `cacheControl` only when every source URL is
+   content-addressed.
+8. Never overwrite an existing `vite.config.ts`, image API route, or
+   `configureImage()` call — diff first and confirm with `AskUserQuestion`.
+
+$ARGUMENTS

package/skills/add-observability/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: add-observability
-version: 1.1.0
+version: 1.1.3
 description: |
-  Wire error tracking, request tracing, and Web Vitals into a pracht app.
-  Supports Sentry or OpenTelemetry on the server side (loader/middleware
-  boundaries, API routes), and client-side Web Vitals reporting via the
-  `web-vitals` package.
-  Use when asked to "add observability", "wire Sentry", "set up tracing",
-  "add OpenTelemetry", "monitor Web Vitals", or "track errors".
+  Wire Sentry or OpenTelemetry into pracht server boundaries (loaders, middleware,
+  API routes), client-side Web Vitals reporting, and a capability audit sink that
+  records every capability dispatch with transport, outcome, latency, and verified
+  identity.
+  Use for "add observability", "wire Sentry", "set up tracing", "add
+  OpenTelemetry", "monitor Web Vitals", "track errors", "log capability calls",
+  or "are agents calling my app".
 allowed-tools:
   - Bash
   - Read
@@ -20,17 +21,19 @@ allowed-tools:
 
 # Pracht Add Observability
 
-Three layers, each opt-in:
+Four layers, each opt-in:
 
 1. **Server error tracking** — capture loader/middleware/API exceptions.
 2. **Request tracing** — span per request with child spans per loader/db call.
 3. **Web Vitals (LCP/CLS/INP/FCP/TTFB)** — client-side, posted to a beacon
    endpoint.
+4. **Agent traffic** — one structured audit event per capability dispatch.
+   Only relevant when the app registers capabilities; skip it otherwise.
 
-If the pracht MCP server is registered (see docs/MCP.md), prefer its tools
-(`inspect_routes`, `inspect_api`, `inspect_build`, `doctor`, `verify`,
-`generate_*`) over shelling out. Prerequisite: `pracht inspect` needs a vite
-config with the pracht plugin registered.
+MCP: when the pracht MCP server is registered (docs/MCP.md), prefer its
+`inspect_agents`/`inspect_routes`/`inspect_api`/`inspect_build`/`doctor`/
+`verify`/`generate_*` tools over shelling out. `pracht inspect` needs the pracht
+plugin in the vite config.
 
 ## Step 1: Pick the stack
 
@@ -232,7 +235,98 @@ export async function POST({ request }: ApiRouteArgs) {
 For Sentry users, Sentry's browser SDK can capture Web Vitals natively —
 prefer that over a custom beacon if you've gone the Sentry route.
 
-## Step 6: Sampling and PII
+## Step 6: Agent traffic (capability apps only)
+
+Skip when `pracht inspect agents --json` reports an empty `capabilities` list.
+That only means there are no capability operations to audit; `llms.txt`, MCP,
+or Web Bot Auth may still expose other agent-facing surfaces. When capabilities
+do exist, every dispatch already emits a structured `CapabilityAuditEvent` —
+nothing is instrumented per capability, a sink just has to be registered.
+
+```ts [src/server/audit.ts]
+import { addCapabilityAuditListener } from "@pracht/core/server";
+
+const stopAuditLog = addCapabilityAuditListener("audit-log", (event) => {
+  console.log(
+    JSON.stringify({
+      msg: "capability",
+      at: new Date().toISOString(),
+      capability: event.capability,
+      effect: event.effect,
+      transport: event.transport, // "http" | "webmcp" | "mcp" | "server"
+      via: event.via, // causal transport for nested invokeCapability()
+      outcome: event.outcome, // "ok" or the envelope error code
+      status: event.status,
+      durationMs: Math.round(event.durationMs),
+      agent: event.agent?.agentDomain ?? event.agent?.keyId ?? null,
+    }),
+  );
+});
+
+if (import.meta.hot) {
+  import.meta.hot.dispose(stopAuditLog);
+}
+```
+
+The OTel version records a counter and a histogram keyed on
+capability/transport/outcome, and backdates a span with
+`startTime: Date.now() - event.durationMs` (the dispatch has already
+finished when the sink runs). The full snippet is on the agent-trust docs page.
+
+Import the module from an eagerly loaded server module. The adapter's configured
+`createContextFrom` module is one portable option: add `import "./audit.ts"`
+there so the generated entry registers the sink before request handling. A
+custom server entry can import it directly. Do not rely on an unrelated route,
+API route, middleware, or `src/server/` registry module; those modules are lazy
+and can miss earlier capability calls.
+
+Key properties to state when scaffolding this:
+
+- Sinks are invoked synchronously, so keep work before the callback returns or
+  reaches its first `await` cheap. A returned promise is never awaited, and a
+  synchronous throw is swallowed (first failure per sink reported via
+  `console.warn`, naming it), so a broken exporter cannot fail the call.
+- **Always pass a stable name** as the first argument. Registering the same
+  name again replaces that sink, which is what keeps a module-scope call safe
+  under dev HMR: Vite re-executes importers on every save, so an unkeyed
+  registration would add a fresh closure per keystroke and deliver every event
+  N times. Never compute the name. Register the returned unsubscribe with
+  `import.meta.hot.dispose()` too, so removing the module or renaming the sink
+  cannot leave the old name active until the dev server restarts.
+- `setCapabilityAuditHook()` is a **single slot** — a second call replaces the
+  first. Use `addCapabilityAuditListener()` whenever more than one sink exists;
+  it returns an unsubscribe handle that removes only its own registration.
+- Warning suppression is per named registration, so differently named sinks
+  still report independently when they reuse one callback.
+- Delivery snapshots the registered sinks before callbacks run. Adding or
+  replacing a sink from inside a callback takes effect on the next dispatch,
+  so the current event is never delivered twice to one name.
+- On Cloudflare Workers, a batching exporter must flush within the request or
+  be handed the execution context by app code
+  (`context.executionContext.waitUntil(exporter.flush())`). Pracht does not
+  call `ctx.waitUntil()` for a sink.
+- Audit events cover *dispatch* only. A cross-origin 403, an unknown-capability
+  404, and an unknown MCP tool name all return before dispatch and emit
+  nothing, so do not build a reconnaissance alert on these events — use the
+  HTTP access log for that.
+
+In dev the same events are already collected: the **Agents** section of
+`/_pracht` shows recent dispatches with transport, `via`, verified identity,
+outcome, and duration, and `/_pracht.json` exposes all of them under
+`agentTraffic`. The page counts verified identities, MCP, and MCP-caused
+composition as agent-attributed; shows top-level unsigned HTTP, HTTP-caused
+composition, and client-declared WebMCP markers separately as unverified client
+dispatches; and hides only `invokeCapability()` work with no served-request
+provenance behind a first-party toggle, so the panel's visible count can be
+lower than the sink's.
+Counts and empty-state conclusions only cover the retained window when older
+events have been dropped. Use it to confirm the sink sees what the panel sees
+before wiring a paid backend. Adapter-owned dev servers do not register this
+middleware: on Cloudflare `workerd`, `/_pracht` and `/_pracht.json` return 404.
+Validate the sink from its own output there; a missing panel is not a failed
+audit hook.
+
+## Step 7: Sampling and PII
 
 - Set `SENTRY_TRACES_SAMPLE_RATE` to a small number (0.05–0.10) in
   production.
@@ -242,10 +336,14 @@ prefer that over a custom beacon if you've gone the Sentry route.
   ```
 - Never send loader return values verbatim — they often contain user data.
 
-## Step 7: Verify
+## Step 8: Verify
 
 - Trigger a deliberate error in dev and confirm it lands in Sentry/OTel.
 - Open a route, check the Web Vitals beacon fires (Network tab).
+- If an audit sink was added: call a capability in dev and confirm the event
+  reaches both the sink and, when the adapter exposes it, the Agents panel at
+  `/_pracht`. On Cloudflare's adapter-owned dev server, validate the sink output
+  directly because the panel does not exist.
 - Confirm `pnpm test` and `pnpm e2e` still pass.
 - Run `pracht typegen` if any routes were added (the beacon API route does
   not affect page-route types, but re-run when in doubt).
@@ -265,6 +363,11 @@ prefer that over a custom beacon if you've gone the Sentry route.
    routes still benefit but the values reflect the post-bootstrap state.
 4. Sample traces (≤ 10%) in production; full sampling in dev.
 5. Never send raw cookies, auth headers, or full loader payloads to a
-   third-party SaaS.
+   third-party SaaS. The same applies to audit events: log the capability
+   name, effect, transport, outcome, and agent domain — not the capability's
+   input, which is application data.
+6. Keep the synchronous part of an audit sink cheap: no CPU-heavy work or
+   synchronous network call. Returned promises are fire-and-forget; the runtime
+   does not await them or catch their rejections.
 
 $ARGUMENTS

package/skills/add-openapi/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: add-openapi
+version: 1.0.1
+description: |
+  Wire `@pracht/openapi`: generate an OpenAPI 3.1 document from `defineApi()`
+  routes, attach response contracts with `defineOpenApi()`, serve an optional
+  Scalar or Swagger UI, handle deploy-base and CSP, and gate completeness in CI.
+  Use for "add OpenAPI", "generate an API spec", "add Swagger", "publish API
+  docs", "document my API routes".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Add OpenAPI
+
+`@pracht/openapi` is an opt-in companion package (`docs/OPENAPI.md`). Ordinary
+`defineApi()` routes keep their authoring, runtime behavior, and `apiFetch()`
+type inference — the package only reads the resolved server graph and owns its
+own descriptor.
+
+## Step 1: Inventory the API first
+
+MCP: when the pracht MCP server is registered (docs/MCP.md), prefer its
+`inspect_api`/`inspect_routes`/`doctor`/`verify` tools over shelling out.
+
+```bash
+pracht inspect api --json   # endpoint paths, methods, hasDefaultHandler
+```
+
+Note two things before generating anything:
+
+- **Default-export handlers** are not expanded — their supported methods cannot
+  be inferred honestly. Split them into named method exports if they belong in
+  the document.
+- **Catch-all paths** become a single `{path}` parameter and emit a warning
+  about slash encoding.
+
+Ask the user whether the document should be public, and whether they want a
+reference UI at all (`ui: false` is the default).
+
+## Step 2: Install and register the plugin
+
+```bash
+pnpm add @pracht/openapi
+```
+
+```ts
+// vite.config.ts — the companion plugin goes after pracht()
+import { prachtOpenApi } from "@pracht/openapi/vite";
+import { pracht } from "@pracht/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    pracht(),
+    prachtOpenApi({
+      info: {
+        title: "Acme API",
+        version: "1.0.0",
+        description: "Public HTTP API for Acme.",
+      },
+      ui: "scalar", // or "swagger", an object, or omit for no UI
+    }),
+  ],
+});
+```
+
+This reserves `/openapi.json` and (with a UI) `/docs`. Both are live in the
+Vite dev server; `pracht build` writes `dist/client/openapi.json` and
+`dist/client/docs/index.html`, which Node, Cloudflare, Netlify, and Vercel serve
+through their existing static-asset paths. Paths are configurable via
+`documentPath` and `ui.path`; the document path **must** end in `.json` so
+static hosts assign the right media type.
+
+Reserved paths shadow app routes: development logs a warning on a collision and
+production generation replaces the colliding public/build file and reports the
+replacement. Grep the manifest and `public/` for `/docs` before enabling the UI
+on an app that already documents itself there.
+
+## Step 3: Attach the metadata that cannot be inferred
+
+Paths, methods, path params, and convertible request validators come from the
+routes. Status codes and payload shapes cannot be recovered from an arbitrary
+`Response` or an erased TypeScript type — declare them:
+
+```ts
+import { defineApi, json } from "@pracht/core";
+import { defineOpenApi } from "@pracht/openapi";
+
+export const POST = defineOpenApi(
+  defineApi({
+    body: createItemSchema,
+    handler: ({ body }) => json({ id: createItem(body) }, { status: 201 }),
+  }),
+  {
+    operationId: "createItem",
+    summary: "Create an item",
+    tags: ["items"],
+    responses: {
+      201: { description: "Item created", body: itemSchema },
+    },
+  },
+);
+```
+
+`defineOpenApi()` mutates and returns the same handler — validation, dispatch,
+and client inference stay with pracht. Generation adds the framework-known 400
+and 422 validation responses itself, marks a request body optional when the
+validator accepts the empty-body `undefined`, and emits a valid undocumented
+`default` response plus a scoped warning when the contract is unknown.
+
+## Step 4: Shared document metadata
+
+```ts
+prachtOpenApi({
+  info: { title: "Acme API", version: "1.0.0" },
+  document: {
+    servers: [
+      { url: "https://api.example.com", description: "Production" },
+      { url: "http://localhost:3000", description: "Local development" },
+    ],
+    tags: [{ name: "items", description: "Item lifecycle" }],
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
+      },
+    },
+    security: [{ bearerAuth: [] }],
+  },
+});
+```
+
+A security scheme referenced by an operation's `security` must exist in
+`document.components.securitySchemes`. `document.security` applies globally; set
+`security: []` on an operation to mark it public.
+
+**Deploy base:** with Vite `base: "/app/"`, the UI loads its document from
+`/app/openapi.json`, and generation adds `servers: [{ url: "/app" }]` when
+`document.servers` is omitted so "Try it out" reaches base-prefixed routes. An
+explicit `document.servers` always wins, including an empty array.
+
+## Step 5: Make it a CI gate
+
+Conversion failures are warnings by default, so one unsupported handler does not
+erase the document. Once every public operation has an explicit response
+contract, tighten it:
+
+```ts
+prachtOpenApi({ info: { title: "Acme API", version: "1.0.0" }, failOnWarnings: true });
+```
+
+Any warning then fails the dev request and `pracht build`. There is no dedicated
+diff/check command yet — deterministic build output plus `failOnWarnings` is how
+drift is caught.
+
+## Step 6: UI provider, CDN, and CSP
+
+- `ui: "scalar"` — modern reference with request examples and an API client.
+- `ui: "swagger"` — Swagger UI, with deep links on and the remote validator
+  disabled so internal documents are never sent to `validator.swagger.io`.
+- Both shells load pinned browser assets from jsDelivr. Apps with offline
+  requirements or a no-third-party-CDN policy should self-host and override
+  (`scriptUrl` for both providers, `styleUrl` for Swagger), copying the pinned
+  distribution into `public/vendor/`.
+- The shell also contains a small inline bootstrap script. A strict CSP must
+  allow that exact script by hash (and the asset origin), or the page must be
+  replaced with an app-owned route following the app's nonce policy —
+  self-hosting the bundle alone does not fix an inline-script ban. See
+  `docs/CSP.md` and `/audit-headers`.
+
+## Step 7: Verify
+
+```bash
+pracht dev             # GET /openapi.json and the UI path
+pracht build
+pracht verify --json
+```
+
+Confirm the document parses, every intended operation is present with a real
+response contract, and no `500`-only `default` responses remain for public
+endpoints. Then run `/audit-headers` if a CSP is in place and
+`/audit-agent-surface` if the document is part of a deliberate agent-facing
+surface.
+
+## Rules
+
+1. Treat the document and UI as public unless the hosting layer protects the
+   emitted static files. No secrets, internal hostnames, or credentials in
+   descriptions or examples.
+2. Never embed an OAuth client secret in UI configuration — browser-delivered
+   configuration is observable by every visitor.
+3. Keep the UI and JSON on the same origin.
+4. "Try it out" sends real requests: mutation endpoints must carry the same
+   authentication, authorization, CSRF, rate-limit, and confirmation policies as
+   any other client.
+5. Set a sane static cache policy for the document; immutable caching is wrong
+   unless the URL is versioned or deployments purge it.
+6. Do not document a capability HTTP projection here — capability endpoints are
+   not included in generation yet (`/add-capabilities` owns that contract).
+7. Never overwrite an existing `vite.config.ts` or a hand-written
+   `public/openapi.json` — diff first and confirm with `AskUserQuestion`.
+
+$ARGUMENTS

package/skills/audit-a11y/SKILL.md

@@ -1,13 +1,12 @@
 ---
 name: audit-a11y
-version: 1.1.0
+version: 1.1.1
 description: |
-  Per-route accessibility audit for a pracht app. Drives a headless browser
-  through every route in the manifest, runs axe-core, and reports issues
-  grouped by severity and route. Catches alt-text gaps, contrast failures,
-  missing landmarks, focus-order bugs, and form-label problems.
-  Use when asked to "audit a11y", "check accessibility", "axe my app",
-  "WCAG compliance", or "screen reader test".
+  Per-route axe-core audit of a pracht app in a headless browser: alt text,
+  contrast, landmarks, focus order, and form labels, grouped by severity and
+  route.
+  Use for "audit a11y", "check accessibility", "axe my app", "WCAG compliance",
+  "screen reader test".
 allowed-tools:
   - Bash
   - Read
@@ -61,8 +60,8 @@ project tooling.
 
 ## Step 3: Enumerate routes
 
-If the pracht MCP server is registered (see docs/MCP.md), prefer its tools
-(`inspect_routes`, `inspect_api`, `inspect_build`, `doctor`, `verify`) over
+MCP: when the pracht MCP server is registered (docs/MCP.md), prefer its
+`inspect_routes`/`inspect_api`/`inspect_build`/`doctor`/`verify` tools over
 shelling out.
 
 ```bash