From d546f76bc4cba22083982ba5d3849b4e49f604ff Mon Sep 17 00:00:00 2001
From: Carlos <carlos.martin-sanchez@mongodb.com>
Date: Sat, 9 May 2026 13:01:49 +0200
Subject: [PATCH 1/5] chore(skills): update skill version to 1.11.0 and enhance
 documentation

- Bump the skill version to 1.11.0, reflecting new capabilities and triggers.
- Add new guidance for skill loading in AGENTS.md, including instructions for skill checks and loading preferences.
- Update SKILL.md and registry.json to include additional triggers and capabilities related to schema metadata and AI tool integration.
- Ensure consistency across documentation files to improve clarity and usability for developers.

This update aims to enhance the skill's functionality and provide clearer instructions for users implementing the TanStack Fullstack Pattern.
---
 .../SKILL.md                                  | 123 ++++++++++----
 AGENTS.md                                     |  10 ++
 scripts/skills/buildSkills.test.ts            |   4 +-
 ...stack-promptable-fullstack-app-template.md | 127 +++++++++++----
 skills/registry.json                          |  26 ++-
 ...omptable-fullstack-app-template.skill.yaml | 154 ++++++++++++++----
 6 files changed, 353 insertions(+), 91 deletions(-)

diff --git a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
index 6cccc5d..94582af 100644
--- a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
+++ b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
@@ -8,7 +8,7 @@ description: 'Use when scaffolding a new TanStack Start project, adding domain
   instead of training data. Project: TanStack AI-Promptable Full-Stack Template.
   Triggers on "fullstack template", "TanStack Start project", "repository
   pattern", "interface-first", "new app scaffold", "nested routes", "layout
-  route", "beforeLoad", "tanstack cli".'
+  route", "beforeLoad", "tanstack cli", "tanstack intent", "package skills".'
 ---
 
 > This file is generated from `skills/src/*.skill.yaml`. Do not edit manually.
@@ -16,7 +16,7 @@ description: 'Use when scaffolding a new TanStack Start project, adding domain
 
 An interface-first fullstack architecture built on TanStack Start. The pattern defines clear interface boundaries between layers -- interfaces are rigid, implementations are swappable.
 
-> **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, Mantine styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
+> **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, chosen UI-library styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
 
 ## Pattern Overview
 
@@ -27,7 +27,7 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 ## Rigid Rules (Must Follow)
 
 1. Interface-first services: every external service (database, AI, observability) is accessed through an interface.
-2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes.
+2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes. Prefer schema metadata and introspection (`.describe()`, route `validateSearch`, tool schemas, router `staticData`, JSON Schema output) over hand-maintained AI metadata.
 3. Three schema layers: repository (DB-shaped), server-function / AI-tool (API-shaped, shared), router search-param (URL-shaped). Mappers translate between layers.
 4. Repository contracts use repository-layer schemas only.
 5. Server functions and AI tools share the same tools-layer schemas (`.inputValidator(Schema)` / `toolDefinition({ inputSchema })`). Both parse with `Schema.parse(args)`.
@@ -39,29 +39,33 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 11. Query pattern: GET server functions throw on failure for centralized error handling. When possible, use static server functions for performance improvements.
 12. Maximize AI tool coverage: expose **every** repository method (reads and writes) via `createSafeServerTool()` so failures return `{ error, code }`. If a server function exists, it gets a tool.
 13. Router capabilities as AI client tools: expose `router.navigate()` and `router.invalidate()` as client tools via `toolDefinition()`.
-14. AI system prompt context: `buildSystemPrompt()` injects three context blocks into every AI chat request. (a) **Current User** — name, email, role from the auth middleware context (server-side; no client round-trip needed). (b) **Browser Context** — timezone, locale, and current date/time from `browserContext` sent by `ChatDrawer` (client-side). (c) **Current Location** — pathname, search params, and full URL from `browserContext`; route patterns (e.g. `/tasks/$taskId`) are matched to resolve dynamic segments. The navigation manifest mirrors `routeTree.gen.ts` and lists each route's search params. When adding routes, update `navigationManifest.ts` and add pattern-matching in `buildSystemPrompt()` for new dynamic segments.
+14. AI system prompt context: `buildSystemPrompt()` injects context into every AI chat request from the single request context and the client ticket sent by the chat UI. Keep the request context flat (for example `{ ticket, client }` inside TanStack's `ctx.context`) and destructure it early in handlers; do not introduce nested custom context wrappers. Include current user, browser context, and current location. Derive route patterns and search params from live router/schema metadata where possible instead of maintaining static route tables.
 15. JSDoc on exports: every exported function, interface, type, and constant gets a JSDoc comment stating *what* and *why*.
-16. AI chat drawer: render the AI chat in a Mantine `Drawer` (`position="right"`, `size="lg"`) mounted at the root layout level so messages persist across navigation. `useDisclosure` controls open/close. See AGENTS.md section 8 for rendering details.
-17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code styled via `.markdown` CSS Module with Mantine CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
+16. AI chat drawer: render the AI chat in the chosen UI library's right-side drawer/panel component mounted at the root layout level so messages persist across navigation. The template's default is a Mantine `Drawer` (`position="right"`, `size="lg"`), but generated apps may swap the component library when the user chooses a different stack.
+17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code are styled through the chat markdown container using the chosen design system's theme tokens or CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
 18. Thin routes: route files contain only route config (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`). Page UI lives in `src/components/PageName/PageName.tsx`.
 19. Promptable by default: check AI availability at the root loader level via `getAIAvailability()`. Only render the chat trigger and drawer when AI is configured — no disabled-state fallback.
 20. Icon library: use `lucide-react` as the default icon library. Keep one icon library per project for visual consistency.
 21. Structured logging: use `pino` for all server-side logging instead of `console.*`. Configure `@sentry/pino-transport` so error-level logs are automatically forwarded to Sentry when `VITE_SENTRY_DSN` is set. The logger singleton lives in `src/services/logger.ts`.
 22. Build-time app version: extract the semver version from `package.json` at build time via Vite `define` and expose it as `__APP_VERSION__`. Inject it into Sentry (`release`), the pino logger (`version` field), and any other observability tool.
-23. Latest dependencies: install and keep dependencies at latest compatible versions. Never pin exact versions unless a known incompatibility exists. Use `pnpm add <pkg>` (no version suffix); run `pnpm outdated` and `pnpm update` to align the lockfile.
+23. Dependency discipline: avoid installing unnecessary packages. Prefer existing project dependencies and platform APIs. When a package is truly required by the chosen stack, requested capability, or validation contract, use the latest stable compatible version via the package manager (`pnpm add <pkg>` with no guessed version suffix unless a known incompatibility requires a pin); run `pnpm outdated` and `pnpm update` to align the lockfile.
 24. Ask for LLM provider: when scaffolding a new project or when the user's LLM preference is unclear, ask which provider they want before writing the adapter. Install only the chosen `@tanstack/ai-*` adapter package and configure matching env vars. Default is `@tanstack/ai-openai`; do not assume OpenAI without asking. See AGENTS.md section 8 for the full provider table.
 25. Generate the system prompt: when scaffolding a new app, ask the user about their domain — entities, capabilities, and permissions — then generate a tailored `BASE_SYSTEM_PROMPT` in `src/routes/api/chat.ts` with six sections (Capabilities, Data Model, Links and navigation, Mutations and data refresh, Permissions and errors, Guidelines). Do not reuse the template's task-management prompt. `buildSystemPrompt()` composes this base with dynamic context (rule 14) and the navigation manifest. `chat()` from `@tanstack/ai` receives it via `systemPrompts: string[]`. See AGENTS.md section 8 "System Prompt Generation" for the full template.
-26. Repository-resolved authorization: `authMiddleware` extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich `AuthContext` with application-defined access data — roles, group memberships, owned scopes, superuser flags. Downstream guards (`requireAuth`, `requireGroup`, any app-specific `requireOwnerOf`) and AI tools read this enriched context so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of whether the caller is the UI, the AI, or a direct HTTP client.
-27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from `ctx.context.user.email` (available after `requireAuthMiddleware`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
-29. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
-30. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
-31. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
-32. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
-33. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
-34. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
-35. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
-36. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
-37. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
+26. Repository-resolved authorization: auth middleware extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich the request context with application-defined access data — roles, group memberships, owned scopes, superuser flags. Prefer a flat access-ticket object with identity, roles, UI-safe predicates, and throwing server guards. Downstream server functions and AI tools read this one ticket so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of caller.
+27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from the request ticket (for example, `ticket.email`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
+28. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
+29. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
+30. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
+31. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
+32. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
+33. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
+34. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
+35. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
+36. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
+37. Computed-field explanation fallback: for virtual fields whose semantics cannot be inferred from schema metadata (for example derived status, health, disposition, rollup, or permission fields), keep a small explanation registry next to the computation logic and expose an `explainField(fieldName)` AI tool. Do not duplicate explanations for fields already described by schemas.
+38. Overlay repository pattern: when upstream systems own base data and users need local annotations, keep a read-only source collection plus a sparse overrides collection. Reads merge both through a pure `applyOverrides(source, override)` function; writes target only overrides and use explicit null/unset semantics to revert to source values.
+39. URL-driven bulk edit pattern: store selected IDs and edit-category state in validated URL search params, keep dirty tracking local to the edit page, submit only changed fields, authorize per row, persist via a batched mutation, and clear stale selections when closing nested modal/detail routes.
+40. Pre-auth redirect middleware: for renamed routes or legacy URL schemes, add a narrow middleware before auth that returns a relative `308 Permanent Redirect`. This prevents old links from producing misleading 401s. Keep the allowlist small and retire entries once upstream links migrate.
 
 ## Schema Boundaries
 
@@ -71,7 +75,7 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 
 **Layer 1 — Repository schemas (DB-shaped):** internal to the repository, no `.describe()` needed. Define in `src/services/schemas/repository.ts` (target pattern -- currently all schemas live in `schemas.ts`). Infer types with `z.infer<>`.
 
-**Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI.
+**Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI. Use these schema descriptions as the first source for field explanations, filter help, and AI tool guidance before adding any separate metadata file.
 
 ```typescript
 // src/services/schemas/schemas.ts
@@ -82,7 +86,7 @@ const TaskInputSchema = z.object({
 })
 ```
 
-**Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional.
+**Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional. Introspect these schemas, plus route `staticData`, when building AI navigation catalogs and link/filter guidance.
 
 ```typescript
 // src/routes/tasks/index.tsx
@@ -98,7 +102,25 @@ export const Route = createFileRoute('/tasks/')({
 })
 ```
 
-**Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`).
+**Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`). Only add a computed-field explanation registry when the field is virtual and cannot be explained by schema metadata or route/tool introspection.
+
+## Request Context
+
+TanStack server functions expose middleware data at `ctx.context`; keep the app-owned value inside it flat. A good default is `{ ticket, client }`, where `ticket` carries identity, roles, predicates, and server-side guards, and `client` carries browser/runtime context such as timezone, locale, current path, and viewport.
+
+```typescript
+const updateTask = createServerFn({ method: 'POST' })
+  .handler(async ctx => {
+    const { ticket, client } = ctx.context
+    ticket.requireTaskEditor(ctx.data.taskId)
+    return getWritableRepository().updateTask(ctx.data, {
+      actor: ticket.email,
+      timezone: client.timezone,
+    })
+  })
+```
+
+Avoid custom shapes like `{ context: { user, client } }` inside `ctx.context`; they create redundant nested context and make examples harder to copy correctly.
 
 ## Interface Contracts
 
@@ -118,11 +140,40 @@ interface WritableRepository {
 }
 ```
 
+## Overlay Repositories
+
+Use this when base records come from an upstream system (warehouse export, spreadsheet, vendor API) but the app needs local user-owned annotations.
+
+- Keep upstream rows in a read-only source collection.
+- Keep user edits in a sparse overrides collection with audit metadata.
+- Reads load source rows and overrides, then merge through a pure `applyOverrides(source, override)` function.
+- Writes target only the overrides collection; explicit `null`/unset values mean "revert to source".
+- Unit-test the overlay function because it defines the merged view shown to the UI and AI.
+
+## URL-Driven Bulk Editing
+
+For multi-row edits, use a dedicated edit route such as `/tasks/edit?selected=id1&selected=id2`.
+
+- Selection lives in validated URL search params, preferably repeated keys.
+- Edit category/tab state also lives in search params.
+- Dirty tracking stays local to the edit page and submits only changed cells.
+- The mutation server function validates each row's permission and persists through one batched write.
+- Closing nested modal/detail routes clears stale selection search params.
+
+## Dynamic AI Metadata
+
+Prefer live sources over static manifests:
+
+- Route catalog: derive from `router.flatRoutes`, route `staticData`, path params, and `validateSearch` schemas.
+- Field/tool metadata: derive from Zod/ArkType `.describe()` and generated JSON Schema.
+- Help content: keep one markdown artifact for user help, AI help, and suggested prompts when the app needs those surfaces.
+- System prompt: reserve static prompt text for behavior that cannot be discovered from tools, schemas, route metadata, or docs.
+
 ## Styling, Auth, and Observability
 
 These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
 
-- **Mantine UI** -- see AGENTS.md section 3 (component-first styling, CSS Modules, dark mode).
+- **UI library** -- see AGENTS.md section 3 for the selected component library's styling rules. The default template uses Mantine, but generated apps may choose another library.
 - **Auth and Middleware** -- see AGENTS.md section 5 (middleware chain, `AuthContext`, guard helpers, code samples). Rigid rules 9--10 above are the normative summary.
 - **Observability** -- see AGENTS.md section 9 (interface, Sentry/no-op, swap steps).
 
@@ -131,10 +182,26 @@ These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tan
 1. **Schemas**: repo-layer schemas in `repository.ts`, tools-layer in `schemas.ts` (with `.describe()`), mappers via `Schema.parse()`.
 2. **Repository**: interfaces in `types.ts` (repo-layer types only), seed + production implementations.
 3. **Server functions**: GET queries + POST mutations in `serverFns.ts` with `.inputValidator(ToolSchema)`.
-4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`.
-5. **Middleware + manifest**: register auth + invalidation in `start.ts`; keep `navigationManifest.ts` aligned with routes.
+4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`. Reuse schema metadata for tool descriptions before adding hand-maintained explanatory text.
+5. **Middleware + route catalog**: register pre-auth redirects (if needed), auth, and invalidation in `start.ts`; derive the AI route catalog from router/schema metadata instead of duplicating route tables.
 6. **Routes**: `validateSearch` (Zod/ArkType), `loaderDeps`, loaders calling server functions; nest under layout parents when children share `beforeLoad` or loader data (rule 33).
-7. **Chat + tests**: pass `browserContext` location to `/api/chat`; E2E specs in `e2e/` against seed repository.
+7. **Chat + tests**: pass client/browser context to `/api/chat`; E2E specs in `e2e/` against seed repository. For scaffold/setup work, finish by running the app in dev mode and checking `/api/health`.
+
+## TanStack Intent and CLI Workflow
+
+Use `tanstack intent` and `tanstack cli` as executable guidance during development. Do not add them as project dependencies unless the generated app explicitly needs them.
+
+### TanStack Intent (Package Skills)
+Intent answers "which version-matched package skill should the agent follow?"
+- Setup: Run `npx @tanstack/intent@latest install` when configuring agent instructions in a generated app.
+- Discover: Before substantial TanStack work, run `npx @tanstack/intent@latest list` or use skills already listed in context.
+- Load: Load a matching package skill with `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
+- Check staleness: Use `npx @tanstack/intent@latest stale` to detect outdated source documentation references.
+
+### TanStack CLI
+CLI docs search answers "what do the current TanStack docs say about this API or pattern?"
+- The CLI provides docs search, MCP support, modular integrations, Builder, and deployment/scaffold support.
+- See `npx @tanstack/cli --help` for available commands.
 
 ## TanStack documentation (official CLI)
 
@@ -166,14 +233,14 @@ The AI stack uses three packages from `@tanstack/ai`:
 A TanStack Start file-based route at `/api/chat` with two handlers:
 
 - **GET** — returns `{ available: boolean }` so the root loader can decide whether to show the chat UI (rule 19).
-- **POST** — check adapter → parse `{ messages, browserContext }` → extract auth from `context as AuthContext` → validate `BrowserContextSchema` → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
+- **POST** — check adapter → parse `{ messages, browserContext }` → read the request ticket from middleware context → validate client context schema → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
 
 `buildSystemPrompt()` composes `BASE_SYSTEM_PROMPT` (rule 25) + navigation manifest + dynamic context (rule 14). When modifying: add tools to the array, update `BASE_SYSTEM_PROMPT` when the data model changes, add pattern-matching for new dynamic route segments. See AGENTS.md section 8 "System Prompt Generation" for the six-section prompt template.
 
 ## Dynamic Route Schema Extraction for AI
 
-To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params (by inspecting `validateSearch` keys). Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs.
+To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params by introspecting `validateSearch` schemas where possible. Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs. Fall back to hand-maintained metadata only when the framework/schema surface cannot expose the needed description.
 
 ## Verification
 
-Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm test && pnpm build`.
+Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm knip && pnpm test && pnpm build`. If the project has not wired Knip yet, add the latest stable `knip` dev dependency or explicitly document why unused-code validation is deferred. After scaffolding or setup changes, also start dev mode and ping `/api/health`; if required credentials are missing, state which prerequisite blocked the health check and what was verified instead.
diff --git a/AGENTS.md b/AGENTS.md
index 27fde5f..bd2f099 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,3 +1,13 @@
+<!-- intent-skills:start -->
+## Skill Loading
+
+Before substantial work:
+- Skill check: run `pnpm dlx @tanstack/intent@latest list`, or use skills already listed in context.
+- Skill guidance: if one local skill clearly matches the task, run `pnpm dlx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
+- Monorepos: when working across packages, run the skill check from the workspace root and prefer the local skill for the package being changed.
+- Multiple matches: prefer the most specific local skill for the package or concern you are changing; load additional skills only when the task spans multiple packages or concerns.
+<!-- intent-skills:end -->
+
 # Agent Instructions
 
 This document is the default agent and contributor guide for projects built from this template. It covers project structure, conventions, tooling, and operational detail.
diff --git a/scripts/skills/buildSkills.test.ts b/scripts/skills/buildSkills.test.ts
index 5e4beb2..23a3ee2 100644
--- a/scripts/skills/buildSkills.test.ts
+++ b/scripts/skills/buildSkills.test.ts
@@ -76,7 +76,9 @@ describe('buildSkills', () => {
 		const parsedRegistry = JSON.parse(registry)
 		expect(parsedRegistry.skills[0].author.name).toBe('Carlos Martin-Sanchez')
 		expect(parsedRegistry.skills[0].supportedTools[0].id).toBe('windsurf')
-		expect(parsedRegistry.skills[0].outputsByFormat.skill).toBe('.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md')
+		expect(parsedRegistry.skills[0].outputsByFormat.skill).toBe(
+			'.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md',
+		)
 
 		const agentSkill = await readFile(
 			path.join(rootDir, '.agents', 'skills', 'tanstack-promptable-fullstack-app-template', 'SKILL.md'),
diff --git a/skills/dist/tanstack-promptable-fullstack-app-template.md b/skills/dist/tanstack-promptable-fullstack-app-template.md
index a115caa..874340c 100644
--- a/skills/dist/tanstack-promptable-fullstack-app-template.md
+++ b/skills/dist/tanstack-promptable-fullstack-app-template.md
@@ -9,9 +9,9 @@
 - Documentation: https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/skills/README.md
 - Status: stable
 - Supported tools: Windsurf [native, tested], Cursor [copy, tested], Claude Code [copy, tested]
-- Capabilities: AI promptable application architecture, Promptable-by-default AI chat in a side drawer when credentials are present, Natural language querying through repository-backed AI tools, URL-aware AI prompt context using current location and route patterns, Swappable service implementations behind stable interfaces, Layer-specific schemas with explicit mapping between repository and tool contracts, Thin routes with extracted, testable page components, Structured server-side logging with pino and automatic Sentry error forwarding, Build-time semver version injected into observability tools for release tracking, Public runtime config exposed to the browser via window.__ENV__ without relying on import.meta.env, Consistent router UX defaults for preload, stale time, and scroll restoration, Distinct-value filter discovery tools that ground AI filter values in real data, Single markdown artifact backing the help page, an AI tool, and the chat's recommended-prompt list, Parent layout routes that centralize beforeLoad guards and shared loader data for nested child routes, Dynamic route schema extraction for AI tool-calling and context awareness
+- Capabilities: AI promptable application architecture, Promptable-by-default AI chat in a side drawer when credentials are present, Natural language querying through repository-backed AI tools, URL-aware AI prompt context using current location and route patterns, Swappable service implementations behind stable interfaces, Layer-specific schemas with explicit mapping between repository and tool contracts, Thin routes with extracted, testable page components, Structured server-side logging with pino and automatic Sentry error forwarding, Build-time semver version injected into observability tools for release tracking, Public runtime config exposed to the browser via window.__ENV__ without relying on import.meta.env, Consistent router UX defaults for preload, stale time, and scroll restoration, Distinct-value filter discovery tools that ground AI filter values in real data, Single markdown artifact backing the help page, an AI tool, and the chat's recommended-prompt list, Parent layout routes that centralize beforeLoad guards and shared loader data for nested child routes, Dynamic route schema extraction for AI tool-calling and context awareness, Schema metadata and framework introspection used as the primary source for AI-facing field, route, and filter explanations, Optional computed-field explanation registries only for virtual values that schemas cannot describe, Upstream-source overlay repositories with sparse user-owned overrides, URL-driven bulk edit routes with dirty tracking and batched mutation functions, TanStack Intent integration for package-specific skill discovery
 - ID: `tanstack-promptable-fullstack-app-template`
-- Version: `1.10.0`
+- Version: `1.11.0`
 - Tags: tanstack-start, fullstack, architecture, interface-first, repository-pattern, ai-promptable
 
 ## Summary
@@ -29,13 +29,15 @@ Use when scaffolding a new TanStack Start project, adding domain entities to the
 - layout route
 - beforeLoad
 - tanstack cli
+- tanstack intent
+- package skills
 
 ## Canonical Content
 # TanStack Fullstack Pattern
 
 An interface-first fullstack architecture built on TanStack Start. The pattern defines clear interface boundaries between layers -- interfaces are rigid, implementations are swappable.
 
-> **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, Mantine styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
+> **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, chosen UI-library styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
 
 ## Pattern Overview
 
@@ -46,7 +48,7 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 ## Rigid Rules (Must Follow)
 
 1. Interface-first services: every external service (database, AI, observability) is accessed through an interface.
-2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes.
+2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes. Prefer schema metadata and introspection (`.describe()`, route `validateSearch`, tool schemas, router `staticData`, JSON Schema output) over hand-maintained AI metadata.
 3. Three schema layers: repository (DB-shaped), server-function / AI-tool (API-shaped, shared), router search-param (URL-shaped). Mappers translate between layers.
 4. Repository contracts use repository-layer schemas only.
 5. Server functions and AI tools share the same tools-layer schemas (`.inputValidator(Schema)` / `toolDefinition({ inputSchema })`). Both parse with `Schema.parse(args)`.
@@ -58,29 +60,33 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 11. Query pattern: GET server functions throw on failure for centralized error handling. When possible, use static server functions for performance improvements.
 12. Maximize AI tool coverage: expose **every** repository method (reads and writes) via `createSafeServerTool()` so failures return `{ error, code }`. If a server function exists, it gets a tool.
 13. Router capabilities as AI client tools: expose `router.navigate()` and `router.invalidate()` as client tools via `toolDefinition()`.
-14. AI system prompt context: `buildSystemPrompt()` injects three context blocks into every AI chat request. (a) **Current User** — name, email, role from the auth middleware context (server-side; no client round-trip needed). (b) **Browser Context** — timezone, locale, and current date/time from `browserContext` sent by `ChatDrawer` (client-side). (c) **Current Location** — pathname, search params, and full URL from `browserContext`; route patterns (e.g. `/tasks/$taskId`) are matched to resolve dynamic segments. The navigation manifest mirrors `routeTree.gen.ts` and lists each route's search params. When adding routes, update `navigationManifest.ts` and add pattern-matching in `buildSystemPrompt()` for new dynamic segments.
+14. AI system prompt context: `buildSystemPrompt()` injects context into every AI chat request from the single request context and the client ticket sent by the chat UI. Keep the request context flat (for example `{ ticket, client }` inside TanStack's `ctx.context`) and destructure it early in handlers; do not introduce nested custom context wrappers. Include current user, browser context, and current location. Derive route patterns and search params from live router/schema metadata where possible instead of maintaining static route tables.
 15. JSDoc on exports: every exported function, interface, type, and constant gets a JSDoc comment stating *what* and *why*.
-16. AI chat drawer: render the AI chat in a Mantine `Drawer` (`position="right"`, `size="lg"`) mounted at the root layout level so messages persist across navigation. `useDisclosure` controls open/close. See AGENTS.md section 8 for rendering details.
-17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code styled via `.markdown` CSS Module with Mantine CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
+16. AI chat drawer: render the AI chat in the chosen UI library's right-side drawer/panel component mounted at the root layout level so messages persist across navigation. The template's default is a Mantine `Drawer` (`position="right"`, `size="lg"`), but generated apps may swap the component library when the user chooses a different stack.
+17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code are styled through the chat markdown container using the chosen design system's theme tokens or CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
 18. Thin routes: route files contain only route config (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`). Page UI lives in `src/components/PageName/PageName.tsx`.
 19. Promptable by default: check AI availability at the root loader level via `getAIAvailability()`. Only render the chat trigger and drawer when AI is configured — no disabled-state fallback.
 20. Icon library: use `lucide-react` as the default icon library. Keep one icon library per project for visual consistency.
 21. Structured logging: use `pino` for all server-side logging instead of `console.*`. Configure `@sentry/pino-transport` so error-level logs are automatically forwarded to Sentry when `VITE_SENTRY_DSN` is set. The logger singleton lives in `src/services/logger.ts`.
 22. Build-time app version: extract the semver version from `package.json` at build time via Vite `define` and expose it as `__APP_VERSION__`. Inject it into Sentry (`release`), the pino logger (`version` field), and any other observability tool.
-23. Latest dependencies: install and keep dependencies at latest compatible versions. Never pin exact versions unless a known incompatibility exists. Use `pnpm add <pkg>` (no version suffix); run `pnpm outdated` and `pnpm update` to align the lockfile.
+23. Dependency discipline: avoid installing unnecessary packages. Prefer existing project dependencies and platform APIs. When a package is truly required by the chosen stack, requested capability, or validation contract, use the latest stable compatible version via the package manager (`pnpm add <pkg>` with no guessed version suffix unless a known incompatibility requires a pin); run `pnpm outdated` and `pnpm update` to align the lockfile.
 24. Ask for LLM provider: when scaffolding a new project or when the user's LLM preference is unclear, ask which provider they want before writing the adapter. Install only the chosen `@tanstack/ai-*` adapter package and configure matching env vars. Default is `@tanstack/ai-openai`; do not assume OpenAI without asking. See AGENTS.md section 8 for the full provider table.
 25. Generate the system prompt: when scaffolding a new app, ask the user about their domain — entities, capabilities, and permissions — then generate a tailored `BASE_SYSTEM_PROMPT` in `src/routes/api/chat.ts` with six sections (Capabilities, Data Model, Links and navigation, Mutations and data refresh, Permissions and errors, Guidelines). Do not reuse the template's task-management prompt. `buildSystemPrompt()` composes this base with dynamic context (rule 14) and the navigation manifest. `chat()` from `@tanstack/ai` receives it via `systemPrompts: string[]`. See AGENTS.md section 8 "System Prompt Generation" for the full template.
-26. Repository-resolved authorization: `authMiddleware` extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich `AuthContext` with application-defined access data — roles, group memberships, owned scopes, superuser flags. Downstream guards (`requireAuth`, `requireGroup`, any app-specific `requireOwnerOf`) and AI tools read this enriched context so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of whether the caller is the UI, the AI, or a direct HTTP client.
-27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from `ctx.context.user.email` (available after `requireAuthMiddleware`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
-29. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
-30. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
-31. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
-32. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
-33. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
-34. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
-35. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
-36. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
-37. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
+26. Repository-resolved authorization: auth middleware extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich the request context with application-defined access data — roles, group memberships, owned scopes, superuser flags. Prefer a flat access-ticket object with identity, roles, UI-safe predicates, and throwing server guards. Downstream server functions and AI tools read this one ticket so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of caller.
+27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from the request ticket (for example, `ticket.email`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
+28. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
+29. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
+30. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
+31. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
+32. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
+33. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
+34. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
+35. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
+36. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
+37. Computed-field explanation fallback: for virtual fields whose semantics cannot be inferred from schema metadata (for example derived status, health, disposition, rollup, or permission fields), keep a small explanation registry next to the computation logic and expose an `explainField(fieldName)` AI tool. Do not duplicate explanations for fields already described by schemas.
+38. Overlay repository pattern: when upstream systems own base data and users need local annotations, keep a read-only source collection plus a sparse overrides collection. Reads merge both through a pure `applyOverrides(source, override)` function; writes target only overrides and use explicit null/unset semantics to revert to source values.
+39. URL-driven bulk edit pattern: store selected IDs and edit-category state in validated URL search params, keep dirty tracking local to the edit page, submit only changed fields, authorize per row, persist via a batched mutation, and clear stale selections when closing nested modal/detail routes.
+40. Pre-auth redirect middleware: for renamed routes or legacy URL schemes, add a narrow middleware before auth that returns a relative `308 Permanent Redirect`. This prevents old links from producing misleading 401s. Keep the allowlist small and retire entries once upstream links migrate.
 
 ## Schema Boundaries
 
@@ -90,7 +96,7 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 
 **Layer 1 — Repository schemas (DB-shaped):** internal to the repository, no `.describe()` needed. Define in `src/services/schemas/repository.ts` (target pattern -- currently all schemas live in `schemas.ts`). Infer types with `z.infer<>`.
 
-**Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI.
+**Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI. Use these schema descriptions as the first source for field explanations, filter help, and AI tool guidance before adding any separate metadata file.
 
 ```typescript
 // src/services/schemas/schemas.ts
@@ -101,7 +107,7 @@ const TaskInputSchema = z.object({
 })
 ```
 
-**Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional.
+**Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional. Introspect these schemas, plus route `staticData`, when building AI navigation catalogs and link/filter guidance.
 
 ```typescript
 // src/routes/tasks/index.tsx
@@ -117,7 +123,25 @@ export const Route = createFileRoute('/tasks/')({
 })
 ```
 
-**Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`).
+**Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`). Only add a computed-field explanation registry when the field is virtual and cannot be explained by schema metadata or route/tool introspection.
+
+## Request Context
+
+TanStack server functions expose middleware data at `ctx.context`; keep the app-owned value inside it flat. A good default is `{ ticket, client }`, where `ticket` carries identity, roles, predicates, and server-side guards, and `client` carries browser/runtime context such as timezone, locale, current path, and viewport.
+
+```typescript
+const updateTask = createServerFn({ method: 'POST' })
+  .handler(async ctx => {
+    const { ticket, client } = ctx.context
+    ticket.requireTaskEditor(ctx.data.taskId)
+    return getWritableRepository().updateTask(ctx.data, {
+      actor: ticket.email,
+      timezone: client.timezone,
+    })
+  })
+```
+
+Avoid custom shapes like `{ context: { user, client } }` inside `ctx.context`; they create redundant nested context and make examples harder to copy correctly.
 
 ## Interface Contracts
 
@@ -137,11 +161,40 @@ interface WritableRepository {
 }
 ```
 
+## Overlay Repositories
+
+Use this when base records come from an upstream system (warehouse export, spreadsheet, vendor API) but the app needs local user-owned annotations.
+
+- Keep upstream rows in a read-only source collection.
+- Keep user edits in a sparse overrides collection with audit metadata.
+- Reads load source rows and overrides, then merge through a pure `applyOverrides(source, override)` function.
+- Writes target only the overrides collection; explicit `null`/unset values mean "revert to source".
+- Unit-test the overlay function because it defines the merged view shown to the UI and AI.
+
+## URL-Driven Bulk Editing
+
+For multi-row edits, use a dedicated edit route such as `/tasks/edit?selected=id1&selected=id2`.
+
+- Selection lives in validated URL search params, preferably repeated keys.
+- Edit category/tab state also lives in search params.
+- Dirty tracking stays local to the edit page and submits only changed cells.
+- The mutation server function validates each row's permission and persists through one batched write.
+- Closing nested modal/detail routes clears stale selection search params.
+
+## Dynamic AI Metadata
+
+Prefer live sources over static manifests:
+
+- Route catalog: derive from `router.flatRoutes`, route `staticData`, path params, and `validateSearch` schemas.
+- Field/tool metadata: derive from Zod/ArkType `.describe()` and generated JSON Schema.
+- Help content: keep one markdown artifact for user help, AI help, and suggested prompts when the app needs those surfaces.
+- System prompt: reserve static prompt text for behavior that cannot be discovered from tools, schemas, route metadata, or docs.
+
 ## Styling, Auth, and Observability
 
 These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
 
-- **Mantine UI** -- see AGENTS.md section 3 (component-first styling, CSS Modules, dark mode).
+- **UI library** -- see AGENTS.md section 3 for the selected component library's styling rules. The default template uses Mantine, but generated apps may choose another library.
 - **Auth and Middleware** -- see AGENTS.md section 5 (middleware chain, `AuthContext`, guard helpers, code samples). Rigid rules 9--10 above are the normative summary.
 - **Observability** -- see AGENTS.md section 9 (interface, Sentry/no-op, swap steps).
 
@@ -150,10 +203,26 @@ These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tan
 1. **Schemas**: repo-layer schemas in `repository.ts`, tools-layer in `schemas.ts` (with `.describe()`), mappers via `Schema.parse()`.
 2. **Repository**: interfaces in `types.ts` (repo-layer types only), seed + production implementations.
 3. **Server functions**: GET queries + POST mutations in `serverFns.ts` with `.inputValidator(ToolSchema)`.
-4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`.
-5. **Middleware + manifest**: register auth + invalidation in `start.ts`; keep `navigationManifest.ts` aligned with routes.
+4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`. Reuse schema metadata for tool descriptions before adding hand-maintained explanatory text.
+5. **Middleware + route catalog**: register pre-auth redirects (if needed), auth, and invalidation in `start.ts`; derive the AI route catalog from router/schema metadata instead of duplicating route tables.
 6. **Routes**: `validateSearch` (Zod/ArkType), `loaderDeps`, loaders calling server functions; nest under layout parents when children share `beforeLoad` or loader data (rule 33).
-7. **Chat + tests**: pass `browserContext` location to `/api/chat`; E2E specs in `e2e/` against seed repository.
+7. **Chat + tests**: pass client/browser context to `/api/chat`; E2E specs in `e2e/` against seed repository. For scaffold/setup work, finish by running the app in dev mode and checking `/api/health`.
+
+## TanStack Intent and CLI Workflow
+
+Use `tanstack intent` and `tanstack cli` as executable guidance during development. Do not add them as project dependencies unless the generated app explicitly needs them.
+
+### TanStack Intent (Package Skills)
+Intent answers "which version-matched package skill should the agent follow?"
+- Setup: Run `npx @tanstack/intent@latest install` when configuring agent instructions in a generated app.
+- Discover: Before substantial TanStack work, run `npx @tanstack/intent@latest list` or use skills already listed in context.
+- Load: Load a matching package skill with `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
+- Check staleness: Use `npx @tanstack/intent@latest stale` to detect outdated source documentation references.
+
+### TanStack CLI
+CLI docs search answers "what do the current TanStack docs say about this API or pattern?"
+- The CLI provides docs search, MCP support, modular integrations, Builder, and deployment/scaffold support.
+- See `npx @tanstack/cli --help` for available commands.
 
 ## TanStack documentation (official CLI)
 
@@ -185,14 +254,14 @@ The AI stack uses three packages from `@tanstack/ai`:
 A TanStack Start file-based route at `/api/chat` with two handlers:
 
 - **GET** — returns `{ available: boolean }` so the root loader can decide whether to show the chat UI (rule 19).
-- **POST** — check adapter → parse `{ messages, browserContext }` → extract auth from `context as AuthContext` → validate `BrowserContextSchema` → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
+- **POST** — check adapter → parse `{ messages, browserContext }` → read the request ticket from middleware context → validate client context schema → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
 
 `buildSystemPrompt()` composes `BASE_SYSTEM_PROMPT` (rule 25) + navigation manifest + dynamic context (rule 14). When modifying: add tools to the array, update `BASE_SYSTEM_PROMPT` when the data model changes, add pattern-matching for new dynamic route segments. See AGENTS.md section 8 "System Prompt Generation" for the six-section prompt template.
 
 ## Dynamic Route Schema Extraction for AI
 
-To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params (by inspecting `validateSearch` keys). Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs.
+To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params by introspecting `validateSearch` schemas where possible. Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs. Fall back to hand-maintained metadata only when the framework/schema surface cannot expose the needed description.
 
 ## Verification
 
-Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm test && pnpm build`.
+Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm knip && pnpm test && pnpm build`. If the project has not wired Knip yet, add the latest stable `knip` dev dependency or explicitly document why unused-code validation is deferred. After scaffolding or setup changes, also start dev mode and ping `/api/health`; if required credentials are missing, state which prerequisite blocked the health check and what was verified instead.
diff --git a/skills/registry.json b/skills/registry.json
index 80b87a0..99f9a34 100644
--- a/skills/registry.json
+++ b/skills/registry.json
@@ -7,7 +7,7 @@
       "summary": "Use when scaffolding a new TanStack Start project, adding domain entities to the fullstack template, or implementing the interface-first repository pattern with AI-promptable tools, or nested layout routes duplicate beforeLoad checks or loaders that should live on a parent route, or TanStack Router, Start, or AI behavior must be verified against current documentation instead of training data.",
       "projectName": "TanStack AI-Promptable Full-Stack Template",
       "projectSummary": "A production-ready TanStack Start template designed to make internal tools AI promptable by default.",
-      "version": "1.10.0",
+      "version": "1.11.0",
       "author": {
         "name": "Carlos Martin-Sanchez",
         "url": "https://github.com/carlosvin"
@@ -63,7 +63,12 @@
         "Distinct-value filter discovery tools that ground AI filter values in real data",
         "Single markdown artifact backing the help page, an AI tool, and the chat's recommended-prompt list",
         "Parent layout routes that centralize beforeLoad guards and shared loader data for nested child routes",
-        "Dynamic route schema extraction for AI tool-calling and context awareness"
+        "Dynamic route schema extraction for AI tool-calling and context awareness",
+        "Schema metadata and framework introspection used as the primary source for AI-facing field, route, and filter explanations",
+        "Optional computed-field explanation registries only for virtual values that schemas cannot describe",
+        "Upstream-source overlay repositories with sparse user-owned overrides",
+        "URL-driven bulk edit routes with dirty tracking and batched mutation functions",
+        "TanStack Intent integration for package-specific skill discovery"
       ],
       "triggers": [
         "fullstack template",
@@ -74,7 +79,9 @@
         "nested routes",
         "layout route",
         "beforeLoad",
-        "tanstack cli"
+        "tanstack cli",
+        "tanstack intent",
+        "package skills"
       ],
       "inputs": [
         "Existing or new TanStack Start codebase",
@@ -103,7 +110,13 @@
         "Actively ask the skill user for clarifications when needed, especially when making choices about movable pieces or architectural decisions.",
         "Every enum-ish field exposes a distinct-values AI tool so the assistant grounds filter arguments in real data",
         "Router configures defaultStaleTime, defaultPreload, defaultPreloadStaleTime, scrollRestoration, and a root notFoundComponent",
-        "Reduce the usage of \"use client\". Rely on Server Components by default. Only use \"use client\" when state, effects, or browser APIs are strictly necessary."
+        "Reduce the usage of \"use client\". Rely on Server Components by default. Only use \"use client\" when state, effects, or browser APIs are strictly necessary.",
+        "Prefer schema metadata and introspection over hand-maintained AI metadata. Use Zod/ArkType `.describe()`, route `validateSearch`, tool schemas, router `staticData`, and JSON Schema output wherever possible",
+        "Hand-maintained virtual-field registries are a fallback only for computed fields whose semantics cannot be inferred from schemas",
+        "Request context is a single flat value carried by TanStack middleware. Avoid custom nested `context.context`-style wrappers; destructure `ctx.context` early in handlers",
+        "Avoid unnecessary packages. Add dependencies only when required by the chosen stack, requested capability, or validation contract; when needed, use the latest stable compatible release through the package manager",
+        "Use TanStack Intent and CLI as executable guidance; do not add them as project dependencies unless a generated app explicitly needs them as part of its own tooling",
+        "Generated apps must be validated locally by starting dev mode and pinging `/api/health` when required environment configuration is available"
       ],
       "steps": [
         "Define schemas as source of truth and infer types",
@@ -121,7 +134,10 @@
         "Use a project-local Link wrapper that preserves search by default",
         "Back the help page, an AI help tool, and the chat's recommended-prompt list from one markdown file",
         "Keep route state in URL search params with validateSearch",
-        "Model nested URLs with parent layout routes so beforeLoad and shared loaders run once per navigation; children read parent loader data via getRouteApi or useLoaderData from the parent path"
+        "Model nested URLs with parent layout routes so beforeLoad and shared loaders run once per navigation; children read parent loader data via getRouteApi or useLoaderData from the parent path",
+        "Prefer schema/router introspection over static hand-maintained AI route and field manifests",
+        "For upstream-owned data, model source rows plus sparse override documents and merge them with a pure overlay function",
+        "For bulk edits, store selected IDs in URL search params and persist only changed fields through a batched mutation"
       ],
       "examples": [
         {
diff --git a/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml b/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
index 492eb6e..1907cfa 100644
--- a/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
+++ b/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
@@ -11,7 +11,7 @@ projectName: TanStack AI-Promptable Full-Stack Template
 projectSummary: >-
   A production-ready TanStack Start template designed to make internal tools AI
   promptable by default.
-version: 1.10.0
+version: 1.11.0
 author:
   name: Carlos Martin-Sanchez
   url: https://github.com/carlosvin
@@ -66,6 +66,14 @@ capabilities:
   - Parent layout routes that centralize beforeLoad guards and shared loader
     data for nested child routes
   - Dynamic route schema extraction for AI tool-calling and context awareness
+  - Schema metadata and framework introspection used as the primary source for
+    AI-facing field, route, and filter explanations
+  - Optional computed-field explanation registries only for virtual values that
+    schemas cannot describe
+  - Upstream-source overlay repositories with sparse user-owned overrides
+  - URL-driven bulk edit routes with dirty tracking and batched mutation
+    functions
+  - TanStack Intent integration for package-specific skill discovery
 triggers:
   - fullstack template
   - TanStack Start project
@@ -76,6 +84,8 @@ triggers:
   - layout route
   - beforeLoad
   - tanstack cli
+  - tanstack intent
+  - package skills
 inputs:
   - Existing or new TanStack Start codebase
   - Domain requirements for data model and auth
@@ -114,6 +124,21 @@ constraints:
   - Router configures defaultStaleTime, defaultPreload, defaultPreloadStaleTime,
     scrollRestoration, and a root notFoundComponent
   - Reduce the usage of "use client". Rely on Server Components by default. Only use "use client" when state, effects, or browser APIs are strictly necessary.
+  - Prefer schema metadata and introspection over hand-maintained AI metadata.
+    Use Zod/ArkType `.describe()`, route `validateSearch`, tool schemas, router
+    `staticData`, and JSON Schema output wherever possible
+  - Hand-maintained virtual-field registries are a fallback only for computed
+    fields whose semantics cannot be inferred from schemas
+  - Request context is a single flat value carried by TanStack middleware.
+    Avoid custom nested `context.context`-style wrappers; destructure
+    `ctx.context` early in handlers
+  - Avoid unnecessary packages. Add dependencies only when required by the chosen
+    stack, requested capability, or validation contract; when needed, use the
+    latest stable compatible release through the package manager
+  - Use TanStack Intent and CLI as executable guidance; do not add them as project
+    dependencies unless a generated app explicitly needs them as part of its own tooling
+  - Generated apps must be validated locally by starting dev mode and pinging
+    `/api/health` when required environment configuration is available
 steps:
   - Define schemas as source of truth and infer types
   - "Split schemas by layer: repository input/output schemas and tool-facing
@@ -138,6 +163,12 @@ steps:
   - Model nested URLs with parent layout routes so beforeLoad and shared loaders
     run once per navigation; children read parent loader data via getRouteApi or
     useLoaderData from the parent path
+  - Prefer schema/router introspection over static hand-maintained AI route and
+    field manifests
+  - For upstream-owned data, model source rows plus sparse override documents and
+    merge them with a pure overlay function
+  - For bulk edits, store selected IDs in URL search params and persist only
+    changed fields through a batched mutation
 examples:
   - input: Add a new domain entity to the template
     output: Update schema, repository interfaces, server functions, routes, and AI
@@ -149,7 +180,7 @@ content: |
 
   An interface-first fullstack architecture built on TanStack Start. The pattern defines clear interface boundaries between layers -- interfaces are rigid, implementations are swappable.
 
-  > **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, Mantine styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
+  > **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, chosen UI-library styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
 
   ## Pattern Overview
 
@@ -160,7 +191,7 @@ content: |
   ## Rigid Rules (Must Follow)
 
   1. Interface-first services: every external service (database, AI, observability) is accessed through an interface.
-  2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes.
+  2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes. Prefer schema metadata and introspection (`.describe()`, route `validateSearch`, tool schemas, router `staticData`, JSON Schema output) over hand-maintained AI metadata.
   3. Three schema layers: repository (DB-shaped), server-function / AI-tool (API-shaped, shared), router search-param (URL-shaped). Mappers translate between layers.
   4. Repository contracts use repository-layer schemas only.
   5. Server functions and AI tools share the same tools-layer schemas (`.inputValidator(Schema)` / `toolDefinition({ inputSchema })`). Both parse with `Schema.parse(args)`.
@@ -172,29 +203,33 @@ content: |
   11. Query pattern: GET server functions throw on failure for centralized error handling. When possible, use static server functions for performance improvements.
   12. Maximize AI tool coverage: expose **every** repository method (reads and writes) via `createSafeServerTool()` so failures return `{ error, code }`. If a server function exists, it gets a tool.
   13. Router capabilities as AI client tools: expose `router.navigate()` and `router.invalidate()` as client tools via `toolDefinition()`.
-  14. AI system prompt context: `buildSystemPrompt()` injects three context blocks into every AI chat request. (a) **Current User** — name, email, role from the auth middleware context (server-side; no client round-trip needed). (b) **Browser Context** — timezone, locale, and current date/time from `browserContext` sent by `ChatDrawer` (client-side). (c) **Current Location** — pathname, search params, and full URL from `browserContext`; route patterns (e.g. `/tasks/$taskId`) are matched to resolve dynamic segments. The navigation manifest mirrors `routeTree.gen.ts` and lists each route's search params. When adding routes, update `navigationManifest.ts` and add pattern-matching in `buildSystemPrompt()` for new dynamic segments.
+  14. AI system prompt context: `buildSystemPrompt()` injects context into every AI chat request from the single request context and the client ticket sent by the chat UI. Keep the request context flat (for example `{ ticket, client }` inside TanStack's `ctx.context`) and destructure it early in handlers; do not introduce nested custom context wrappers. Include current user, browser context, and current location. Derive route patterns and search params from live router/schema metadata where possible instead of maintaining static route tables.
   15. JSDoc on exports: every exported function, interface, type, and constant gets a JSDoc comment stating *what* and *why*.
-  16. AI chat drawer: render the AI chat in a Mantine `Drawer` (`position="right"`, `size="lg"`) mounted at the root layout level so messages persist across navigation. `useDisclosure` controls open/close. See AGENTS.md section 8 for rendering details.
-  17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code styled via `.markdown` CSS Module with Mantine CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
+  16. AI chat drawer: render the AI chat in the chosen UI library's right-side drawer/panel component mounted at the root layout level so messages persist across navigation. The template's default is a Mantine `Drawer` (`position="right"`, `size="lg"`), but generated apps may swap the component library when the user chooses a different stack.
+  17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code are styled through the chat markdown container using the chosen design system's theme tokens or CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
   18. Thin routes: route files contain only route config (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`). Page UI lives in `src/components/PageName/PageName.tsx`.
   19. Promptable by default: check AI availability at the root loader level via `getAIAvailability()`. Only render the chat trigger and drawer when AI is configured — no disabled-state fallback.
   20. Icon library: use `lucide-react` as the default icon library. Keep one icon library per project for visual consistency.
   21. Structured logging: use `pino` for all server-side logging instead of `console.*`. Configure `@sentry/pino-transport` so error-level logs are automatically forwarded to Sentry when `VITE_SENTRY_DSN` is set. The logger singleton lives in `src/services/logger.ts`.
   22. Build-time app version: extract the semver version from `package.json` at build time via Vite `define` and expose it as `__APP_VERSION__`. Inject it into Sentry (`release`), the pino logger (`version` field), and any other observability tool.
-  23. Latest dependencies: install and keep dependencies at latest compatible versions. Never pin exact versions unless a known incompatibility exists. Use `pnpm add <pkg>` (no version suffix); run `pnpm outdated` and `pnpm update` to align the lockfile.
+  23. Dependency discipline: avoid installing unnecessary packages. Prefer existing project dependencies and platform APIs. When a package is truly required by the chosen stack, requested capability, or validation contract, use the latest stable compatible version via the package manager (`pnpm add <pkg>` with no guessed version suffix unless a known incompatibility requires a pin); run `pnpm outdated` and `pnpm update` to align the lockfile.
   24. Ask for LLM provider: when scaffolding a new project or when the user's LLM preference is unclear, ask which provider they want before writing the adapter. Install only the chosen `@tanstack/ai-*` adapter package and configure matching env vars. Default is `@tanstack/ai-openai`; do not assume OpenAI without asking. See AGENTS.md section 8 for the full provider table.
   25. Generate the system prompt: when scaffolding a new app, ask the user about their domain — entities, capabilities, and permissions — then generate a tailored `BASE_SYSTEM_PROMPT` in `src/routes/api/chat.ts` with six sections (Capabilities, Data Model, Links and navigation, Mutations and data refresh, Permissions and errors, Guidelines). Do not reuse the template's task-management prompt. `buildSystemPrompt()` composes this base with dynamic context (rule 14) and the navigation manifest. `chat()` from `@tanstack/ai` receives it via `systemPrompts: string[]`. See AGENTS.md section 8 "System Prompt Generation" for the full template.
-  26. Repository-resolved authorization: `authMiddleware` extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich `AuthContext` with application-defined access data — roles, group memberships, owned scopes, superuser flags. Downstream guards (`requireAuth`, `requireGroup`, any app-specific `requireOwnerOf`) and AI tools read this enriched context so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of whether the caller is the UI, the AI, or a direct HTTP client.
-  27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from `ctx.context.user.email` (available after `requireAuthMiddleware`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
-  29. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
-  30. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
-  31. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
-  32. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
-  33. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
-  34. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
-  35. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
-  36. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
-  37. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
+  26. Repository-resolved authorization: auth middleware extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich the request context with application-defined access data — roles, group memberships, owned scopes, superuser flags. Prefer a flat access-ticket object with identity, roles, UI-safe predicates, and throwing server guards. Downstream server functions and AI tools read this one ticket so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of caller.
+  27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from the request ticket (for example, `ticket.email`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
+  28. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
+  29. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
+  30. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
+  31. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
+  32. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
+  33. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
+  34. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
+  35. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
+  36. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
+  37. Computed-field explanation fallback: for virtual fields whose semantics cannot be inferred from schema metadata (for example derived status, health, disposition, rollup, or permission fields), keep a small explanation registry next to the computation logic and expose an `explainField(fieldName)` AI tool. Do not duplicate explanations for fields already described by schemas.
+  38. Overlay repository pattern: when upstream systems own base data and users need local annotations, keep a read-only source collection plus a sparse overrides collection. Reads merge both through a pure `applyOverrides(source, override)` function; writes target only overrides and use explicit null/unset semantics to revert to source values.
+  39. URL-driven bulk edit pattern: store selected IDs and edit-category state in validated URL search params, keep dirty tracking local to the edit page, submit only changed fields, authorize per row, persist via a batched mutation, and clear stale selections when closing nested modal/detail routes.
+  40. Pre-auth redirect middleware: for renamed routes or legacy URL schemes, add a narrow middleware before auth that returns a relative `308 Permanent Redirect`. This prevents old links from producing misleading 401s. Keep the allowlist small and retire entries once upstream links migrate.
 
   ## Schema Boundaries
 
@@ -204,7 +239,7 @@ content: |
 
   **Layer 1 — Repository schemas (DB-shaped):** internal to the repository, no `.describe()` needed. Define in `src/services/schemas/repository.ts` (target pattern -- currently all schemas live in `schemas.ts`). Infer types with `z.infer<>`.
 
-  **Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI.
+  **Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI. Use these schema descriptions as the first source for field explanations, filter help, and AI tool guidance before adding any separate metadata file.
 
   ```typescript
   // src/services/schemas/schemas.ts
@@ -215,7 +250,7 @@ content: |
   })
   ```
 
-  **Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional.
+  **Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional. Introspect these schemas, plus route `staticData`, when building AI navigation catalogs and link/filter guidance.
 
   ```typescript
   // src/routes/tasks/index.tsx
@@ -231,7 +266,25 @@ content: |
   })
   ```
 
-  **Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`).
+  **Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`). Only add a computed-field explanation registry when the field is virtual and cannot be explained by schema metadata or route/tool introspection.
+
+  ## Request Context
+
+  TanStack server functions expose middleware data at `ctx.context`; keep the app-owned value inside it flat. A good default is `{ ticket, client }`, where `ticket` carries identity, roles, predicates, and server-side guards, and `client` carries browser/runtime context such as timezone, locale, current path, and viewport.
+
+  ```typescript
+  const updateTask = createServerFn({ method: 'POST' })
+    .handler(async ctx => {
+      const { ticket, client } = ctx.context
+      ticket.requireTaskEditor(ctx.data.taskId)
+      return getWritableRepository().updateTask(ctx.data, {
+        actor: ticket.email,
+        timezone: client.timezone,
+      })
+    })
+  ```
+
+  Avoid custom shapes like `{ context: { user, client } }` inside `ctx.context`; they create redundant nested context and make examples harder to copy correctly.
 
   ## Interface Contracts
 
@@ -251,11 +304,40 @@ content: |
   }
   ```
 
+  ## Overlay Repositories
+
+  Use this when base records come from an upstream system (warehouse export, spreadsheet, vendor API) but the app needs local user-owned annotations.
+
+  - Keep upstream rows in a read-only source collection.
+  - Keep user edits in a sparse overrides collection with audit metadata.
+  - Reads load source rows and overrides, then merge through a pure `applyOverrides(source, override)` function.
+  - Writes target only the overrides collection; explicit `null`/unset values mean "revert to source".
+  - Unit-test the overlay function because it defines the merged view shown to the UI and AI.
+
+  ## URL-Driven Bulk Editing
+
+  For multi-row edits, use a dedicated edit route such as `/tasks/edit?selected=id1&selected=id2`.
+
+  - Selection lives in validated URL search params, preferably repeated keys.
+  - Edit category/tab state also lives in search params.
+  - Dirty tracking stays local to the edit page and submits only changed cells.
+  - The mutation server function validates each row's permission and persists through one batched write.
+  - Closing nested modal/detail routes clears stale selection search params.
+
+  ## Dynamic AI Metadata
+
+  Prefer live sources over static manifests:
+
+  - Route catalog: derive from `router.flatRoutes`, route `staticData`, path params, and `validateSearch` schemas.
+  - Field/tool metadata: derive from Zod/ArkType `.describe()` and generated JSON Schema.
+  - Help content: keep one markdown artifact for user help, AI help, and suggested prompts when the app needs those surfaces.
+  - System prompt: reserve static prompt text for behavior that cannot be discovered from tools, schemas, route metadata, or docs.
+
   ## Styling, Auth, and Observability
 
   These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
 
-  - **Mantine UI** -- see AGENTS.md section 3 (component-first styling, CSS Modules, dark mode).
+  - **UI library** -- see AGENTS.md section 3 for the selected component library's styling rules. The default template uses Mantine, but generated apps may choose another library.
   - **Auth and Middleware** -- see AGENTS.md section 5 (middleware chain, `AuthContext`, guard helpers, code samples). Rigid rules 9--10 above are the normative summary.
   - **Observability** -- see AGENTS.md section 9 (interface, Sentry/no-op, swap steps).
 
@@ -264,10 +346,26 @@ content: |
   1. **Schemas**: repo-layer schemas in `repository.ts`, tools-layer in `schemas.ts` (with `.describe()`), mappers via `Schema.parse()`.
   2. **Repository**: interfaces in `types.ts` (repo-layer types only), seed + production implementations.
   3. **Server functions**: GET queries + POST mutations in `serverFns.ts` with `.inputValidator(ToolSchema)`.
-  4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`.
-  5. **Middleware + manifest**: register auth + invalidation in `start.ts`; keep `navigationManifest.ts` aligned with routes.
+  4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`. Reuse schema metadata for tool descriptions before adding hand-maintained explanatory text.
+  5. **Middleware + route catalog**: register pre-auth redirects (if needed), auth, and invalidation in `start.ts`; derive the AI route catalog from router/schema metadata instead of duplicating route tables.
   6. **Routes**: `validateSearch` (Zod/ArkType), `loaderDeps`, loaders calling server functions; nest under layout parents when children share `beforeLoad` or loader data (rule 33).
-  7. **Chat + tests**: pass `browserContext` location to `/api/chat`; E2E specs in `e2e/` against seed repository.
+  7. **Chat + tests**: pass client/browser context to `/api/chat`; E2E specs in `e2e/` against seed repository. For scaffold/setup work, finish by running the app in dev mode and checking `/api/health`.
+
+  ## TanStack Intent and CLI Workflow
+  
+  Use `tanstack intent` and `tanstack cli` as executable guidance during development. Do not add them as project dependencies unless the generated app explicitly needs them.
+
+  ### TanStack Intent (Package Skills)
+  Intent answers "which version-matched package skill should the agent follow?"
+  - Setup: Run `npx @tanstack/intent@latest install` when configuring agent instructions in a generated app.
+  - Discover: Before substantial TanStack work, run `npx @tanstack/intent@latest list` or use skills already listed in context.
+  - Load: Load a matching package skill with `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
+  - Check staleness: Use `npx @tanstack/intent@latest stale` to detect outdated source documentation references.
+
+  ### TanStack CLI
+  CLI docs search answers "what do the current TanStack docs say about this API or pattern?"
+  - The CLI provides docs search, MCP support, modular integrations, Builder, and deployment/scaffold support.
+  - See `npx @tanstack/cli --help` for available commands.
 
   ## TanStack documentation (official CLI)
 
@@ -299,14 +397,14 @@ content: |
   A TanStack Start file-based route at `/api/chat` with two handlers:
 
   - **GET** — returns `{ available: boolean }` so the root loader can decide whether to show the chat UI (rule 19).
-  - **POST** — check adapter → parse `{ messages, browserContext }` → extract auth from `context as AuthContext` → validate `BrowserContextSchema` → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
+  - **POST** — check adapter → parse `{ messages, browserContext }` → read the request ticket from middleware context → validate client context schema → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
 
   `buildSystemPrompt()` composes `BASE_SYSTEM_PROMPT` (rule 25) + navigation manifest + dynamic context (rule 14). When modifying: add tools to the array, update `BASE_SYSTEM_PROMPT` when the data model changes, add pattern-matching for new dynamic route segments. See AGENTS.md section 8 "System Prompt Generation" for the six-section prompt template.
 
   ## Dynamic Route Schema Extraction for AI
 
-  To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params (by inspecting `validateSearch` keys). Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs.
+  To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params by introspecting `validateSearch` schemas where possible. Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs. Fall back to hand-maintained metadata only when the framework/schema surface cannot expose the needed description.
 
   ## Verification
 
-  Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm test && pnpm build`.
+  Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm knip && pnpm test && pnpm build`. If the project has not wired Knip yet, add the latest stable `knip` dev dependency or explicitly document why unused-code validation is deferred. After scaffolding or setup changes, also start dev mode and ping `/api/health`; if required credentials are missing, state which prerequisite blocked the health check and what was verified instead.

From 17962e9c8632f7486556399fa1b6de959299322c Mon Sep 17 00:00:00 2001
From: Carlos <carlos.martin-sanchez@mongodb.com>
Date: Sun, 10 May 2026 12:48:05 +0200
Subject: [PATCH 2/5] chore(skills): bump version to 1.14.0 and update
 capabilities

- Update the skill version to 1.14.0 to reflect new architectural enhancements.
- Revise capabilities in SKILL.md, registry.json, and YAML files to emphasize interface-first boundaries, schema layers, and loader-first routes.
- Ensure consistency across documentation to improve clarity for developers implementing the TanStack Fullstack Pattern.

This update aims to enhance the skill's functionality and provide clearer guidance for users.
---
 .../SKILL.md                                  | 332 ++++++------
 ...stack-promptable-fullstack-app-template.md | 336 ++++++-------
 skills/registry.json                          | 100 ++--
 ...omptable-fullstack-app-template.skill.yaml | 473 ++++++++----------
 4 files changed, 563 insertions(+), 678 deletions(-)

diff --git a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
index 94582af..e7efd49 100644
--- a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
+++ b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
@@ -14,82 +14,86 @@ description: 'Use when scaffolding a new TanStack Start project, adding domain
 > This file is generated from `skills/src/*.skill.yaml`. Do not edit manually.
 # TanStack Fullstack Pattern
 
-An interface-first fullstack architecture built on TanStack Start. The pattern defines clear interface boundaries between layers -- interfaces are rigid, implementations are swappable.
-
-> **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, chosen UI-library styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
-
-## Pattern Overview
-
-- Zero-config development with seed implementations and swappable service layers
-- AI promptability by exposing every repository method (reads and writes) as tools
-- End-to-end type safety from schema-first definitions with explicit layer boundaries
-
-## Rigid Rules (Must Follow)
-
-1. Interface-first services: every external service (database, AI, observability) is accessed through an interface.
-2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes. Prefer schema metadata and introspection (`.describe()`, route `validateSearch`, tool schemas, router `staticData`, JSON Schema output) over hand-maintained AI metadata.
-3. Three schema layers: repository (DB-shaped), server-function / AI-tool (API-shaped, shared), router search-param (URL-shaped). Mappers translate between layers.
-4. Repository contracts use repository-layer schemas only.
-5. Server functions and AI tools share the same tools-layer schemas (`.inputValidator(Schema)` / `toolDefinition({ inputSchema })`). Both parse with `Schema.parse(args)`.
-6. AI and UI interact only with tools-layer schemas; they must not depend directly on repository schemas.
-7. Loaders-first data fetching: fetch route data in loaders through server functions.
-8. URL-as-state: filters, tabs, selections live in URL search params via `validateSearch` (Zod/ArkType). Use `loaderDeps` to feed validated search into loaders.
-9. Middleware chain: auth is global middleware, invalidation runs on mutation server functions.
-10. Mutation pattern: POST server functions chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`, return domain data or throw `HttpError`. Callers normalize errors: UI via `processResponse()`, AI tools via `safeToolHandler()` / `createSafeServerTool()`.
-11. Query pattern: GET server functions throw on failure for centralized error handling. When possible, use static server functions for performance improvements.
-12. Maximize AI tool coverage: expose **every** repository method (reads and writes) via `createSafeServerTool()` so failures return `{ error, code }`. If a server function exists, it gets a tool.
-13. Router capabilities as AI client tools: expose `router.navigate()` and `router.invalidate()` as client tools via `toolDefinition()`.
-14. AI system prompt context: `buildSystemPrompt()` injects context into every AI chat request from the single request context and the client ticket sent by the chat UI. Keep the request context flat (for example `{ ticket, client }` inside TanStack's `ctx.context`) and destructure it early in handlers; do not introduce nested custom context wrappers. Include current user, browser context, and current location. Derive route patterns and search params from live router/schema metadata where possible instead of maintaining static route tables.
-15. JSDoc on exports: every exported function, interface, type, and constant gets a JSDoc comment stating *what* and *why*.
-16. AI chat drawer: render the AI chat in the chosen UI library's right-side drawer/panel component mounted at the root layout level so messages persist across navigation. The template's default is a Mantine `Drawer` (`position="right"`, `size="lg"`), but generated apps may swap the component library when the user chooses a different stack.
-17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code are styled through the chat markdown container using the chosen design system's theme tokens or CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
-18. Thin routes: route files contain only route config (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`). Page UI lives in `src/components/PageName/PageName.tsx`.
-19. Promptable by default: check AI availability at the root loader level via `getAIAvailability()`. Only render the chat trigger and drawer when AI is configured — no disabled-state fallback.
-20. Icon library: use `lucide-react` as the default icon library. Keep one icon library per project for visual consistency.
-21. Structured logging: use `pino` for all server-side logging instead of `console.*`. Configure `@sentry/pino-transport` so error-level logs are automatically forwarded to Sentry when `VITE_SENTRY_DSN` is set. The logger singleton lives in `src/services/logger.ts`.
-22. Build-time app version: extract the semver version from `package.json` at build time via Vite `define` and expose it as `__APP_VERSION__`. Inject it into Sentry (`release`), the pino logger (`version` field), and any other observability tool.
-23. Dependency discipline: avoid installing unnecessary packages. Prefer existing project dependencies and platform APIs. When a package is truly required by the chosen stack, requested capability, or validation contract, use the latest stable compatible version via the package manager (`pnpm add <pkg>` with no guessed version suffix unless a known incompatibility requires a pin); run `pnpm outdated` and `pnpm update` to align the lockfile.
-24. Ask for LLM provider: when scaffolding a new project or when the user's LLM preference is unclear, ask which provider they want before writing the adapter. Install only the chosen `@tanstack/ai-*` adapter package and configure matching env vars. Default is `@tanstack/ai-openai`; do not assume OpenAI without asking. See AGENTS.md section 8 for the full provider table.
-25. Generate the system prompt: when scaffolding a new app, ask the user about their domain — entities, capabilities, and permissions — then generate a tailored `BASE_SYSTEM_PROMPT` in `src/routes/api/chat.ts` with six sections (Capabilities, Data Model, Links and navigation, Mutations and data refresh, Permissions and errors, Guidelines). Do not reuse the template's task-management prompt. `buildSystemPrompt()` composes this base with dynamic context (rule 14) and the navigation manifest. `chat()` from `@tanstack/ai` receives it via `systemPrompts: string[]`. See AGENTS.md section 8 "System Prompt Generation" for the full template.
-26. Repository-resolved authorization: auth middleware extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich the request context with application-defined access data — roles, group memberships, owned scopes, superuser flags. Prefer a flat access-ticket object with identity, roles, UI-safe predicates, and throwing server guards. Downstream server functions and AI tools read this one ticket so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of caller.
-27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from the request ticket (for example, `ticket.email`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
-28. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
-29. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
-30. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
-31. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
-32. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
-33. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
-34. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
-35. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
-36. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
-37. Computed-field explanation fallback: for virtual fields whose semantics cannot be inferred from schema metadata (for example derived status, health, disposition, rollup, or permission fields), keep a small explanation registry next to the computation logic and expose an `explainField(fieldName)` AI tool. Do not duplicate explanations for fields already described by schemas.
-38. Overlay repository pattern: when upstream systems own base data and users need local annotations, keep a read-only source collection plus a sparse overrides collection. Reads merge both through a pure `applyOverrides(source, override)` function; writes target only overrides and use explicit null/unset semantics to revert to source values.
-39. URL-driven bulk edit pattern: store selected IDs and edit-category state in validated URL search params, keep dirty tracking local to the edit page, submit only changed fields, authorize per row, persist via a batched mutation, and clear stale selections when closing nested modal/detail routes.
-40. Pre-auth redirect middleware: for renamed routes or legacy URL schemes, add a narrow middleware before auth that returns a relative `308 Permanent Redirect`. This prevents old links from producing misleading 401s. Keep the allowlist small and retire entries once upstream links migrate.
+**Purpose:** Capture the **interface-first, schema-layered, AI-promptable** contract for TanStack Start apps from this template. Day-to-day conventions (UI kit, chat wiring, logging, tests) live in the repo’s **AGENTS.md** — use this skill for **architecture**, AGENTS.md for **operations**.
+
+> **Companion handbook:** [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) — structure, styling, auth snippets, Biome, testing/E2E, validation checklist, AI chat setup.
+
+## Core Contract
+
+1. **Interfaces:** Database, AI, observability (and other externals) sit behind interfaces; implementations are swappable.
+2. **Schemas as the type source:** Wire and tool shapes use Zod/ArkType + `z.infer<>`. Hand-written interfaces define **behavior** (`ReadRepository`, `AIAdapterService`, …), not ad-hoc JSON types.
+3. **Three schema layers:** **Repository** (DB-shaped), **tools / server-fn** (API-shaped, shared between `createServerFn` and `toolDefinition`), **router search** (URL-shaped). Translate with `Schema.parse()` at each boundary.
+4. **TypeScript inside the typed flow:** After schema boundaries, preserve **inferred types end-to-end** — prefer `satisfies`, discriminated unions, `as const` tuples, narrow **type guards**, and **exhaustive `switch`** (e.g. `default` branch calling `assertNever`) over `any`, broad `unknown` plumbing, or `as` casts (only use `as` at documented third-party/library seams per AGENTS.md).
+5. **Repository vs tools:** Repository implementations use repository-layer schemas only. **Server functions and AI tools share the same tools-layer schemas** (`.inputValidator` / `toolDefinition` inputSchema + `Schema.parse`). UI and AI consume tools-layer types only — never import repository schemas at those edges.
+6. **Server functions:** GET queries throw on failure; POST mutations chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`; handlers return data or throw `HttpError`; callers normalize with `processResponse` / `safeToolHandler` / `createSafeServerTool`.
+7. **Routes:** Thin route files (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`); page UI in `src/components/`. **Loaders** fetch via server functions — no `useEffect` data fetching for route data.
+8. **URL-as-state:** Filters, tabs, selections in validated **search** params; use `loaderDeps` so only relevant search fields key the loader cache.
+9. **Router config bundle:** ship a project-local `Link` wrapper with `search: true` default (use it for every internal link) **and** these router defaults together: `defaultStaleTime`, `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0`, `scrollRestoration: true`, `notFoundComponent`.
+10. **Auth ticket built in middleware:** auth middleware enriches `ctx.context` with a repository-built ticket (e.g. `getReadRepository().getUserAccess(email)`) carrying identity, roles, and guards; `WritableRepository` mutations accept a `TraceabilityContext` (`createdBy`, `lastModifiedBy`, …) constructed from that ticket so writes are attributed consistently across UI and AI.
+11. **AI tool coverage:** expose **every** repository method as a server AI tool via `createSafeServerTool`; add **distinct-values** tools for enum-ish filters; expose `navigate` and `invalidateRouter` as client tools.
+12. **Promptable by default:** root loader checks `getAIAvailability()` and only mounts chat UI when configured (no disabled state). Chat input includes a `browserContext` (timezone, locale, path) consumed by `buildSystemPrompt` alongside the auth ticket.
+13. **Bound the agent loop:** every `chat()` call sets `agentLoopStrategy: maxIterations(N)` explicitly (default `N=10`); tune after measuring — do not rely on the framework default.
+14. **Metadata for AI and UI:** Use `.describe()` for all narrative explanations (JSON Schema `description`). Use `.meta({ ... })` only for **structured extras** — `unit`, `format`, optional `title`, app-specific hints — not as a substitute for `.describe()`. Prefer deriving prompts and UI copy from schemas + `z.toJSONSchema()` and router introspection over parallel hand-maintained maps.
+15. **Parent layouts:** Shared `beforeLoad`, redirects, and expensive reads belong on the **parent** layout route; children read parent loader data via `getRouteApi` / `useLoaderData({ from })` — do not duplicate parent work.
+
+Day-to-day operational concerns (UI kit, chat drawer placement, markdown rendering, LLM provider choice, pino/Sentry, icons, RSC vs `"use client"`, full validation commands) follow **AGENTS.md** — see the handbook table below.
+
+## Architecture Checklist
+
+Scan before changing code:
+
+- **One tools-layer schema per wire shape:** `createServerFn` `.inputValidator(Schema)` and AI `toolDefinition({ inputSchema })` share the same schema — no duplicate hand-written wire types.
+- **Parse both directions:** tools → repository inputs and repository rows → tools/API outputs each end in the target layer’s `Schema.parse()` (pure mapper functions are fine if the final step is always `.parse()`).
+- **No type erasure:** after `Schema.parse`, carry **`z.infer`-derived types** through server functions, repos, tools, and components — do not widen back to `Record<string, unknown>` / `any`.
+- **Repository interfaces = repo-layer types only:** mapping lives beside schemas / mappers — not in React components.
+- **Auth ticket is repository-backed and server-enforced:** middleware builds the ticket (e.g. `getReadRepository().getUserAccess(email)`); guards run in **server handlers**, never UI-only.
+- **Writes use `TraceabilityContext`:** pass audit fields from the ticket through a single context object on `WritableRepository` mutations — avoid sprinkling raw `email` arguments.
+- **Navigation is one decision:** ship the **router defaults bundle** and the **project `Link` wrapper** (`search: true`) together so URL state survives navigation.
+- **AI stack is complete:** every repo method → server tool + safe handler; client **`navigate`** / **`invalidateRouter`**; root **`getAIAvailability()`**; chat payload includes **`browserContext`**; **`chat({ agentLoopStrategy: maxIterations(N) })`**.
+- **Routes:** **`validateSearch`** + **`loaderDeps`**; duplicate **`beforeLoad`** / shared loaders only on **parent** layouts.
+- **Metadata discipline:** `.describe()` for narrative copy; `.meta()` for structured extras; closed vocabularies = `as const` tuple + `z.enum` + `z.infer<>`.
 
 ## Schema Boundaries
 
-`Route search schema -> loader -> tools schema -> server fn -> mapping -> repo schema -> repo impl`
+`Route search schema → loader → tools schema → server fn → mapping → repo schema → repo`
 
-`repo output -> mapping -> tools schema -> AI or UI`
+`repo output → mapping → tools schema → AI or UI`
 
-**Layer 1 — Repository schemas (DB-shaped):** internal to the repository, no `.describe()` needed. Define in `src/services/schemas/repository.ts` (target pattern -- currently all schemas live in `schemas.ts`). Infer types with `z.infer<>`.
+**Layer 1 — Repository (DB-shaped):** define in `src/services/schemas/repository.ts` (target layout; today some apps still colocate in `schemas.ts`). No `.describe()` required here. Infer with `z.infer<>`.
 
-**Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI. Use these schema descriptions as the first source for field explanations, filter help, and AI tool guidance before adding any separate metadata file.
+**Layer 2 — Tools / server functions (API-shaped):** one schema for `.inputValidator(Schema)` and `toolDefinition({ inputSchema })`; parse args with `Schema.parse(args)`.
 
 ```typescript
-// src/services/schemas/schemas.ts
+// Example: tools-layer object — .describe() for text; .meta() for non-description fields
 const TaskInputSchema = z.object({
   title: z.string().min(1).describe('Short title'),
   status: TaskStatusSchema.default('pending').describe('Current status'),
-  assignee: z.string().optional().describe('Assignee email'),
+  estimateHours: z
+    .number()
+    .optional()
+    .describe('Estimated effort in hours')
+    .meta({ unit: 'h', format: 'decimal' }),
 })
 ```
 
-**Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional. Introspect these schemas, plus route `staticData`, when building AI navigation catalogs and link/filter guidance.
+**Closed vocabularies (enums, tool categories, filter buckets):** `const VALUES = [...] as const`, then `z.enum(VALUES)`, put prose in `.describe()`, optional `.meta({ title: '...' })`, infer with `z.infer<>`. **Do not** treat `export const LABELS = { id: 'Display Name' } as const` as the authority for the same strings unless it is derived from or validated by that schema.
+
+```typescript
+const TOOL_CATEGORY_VALUES = ['Metadata & Navigation', 'Strategic Objectives'] as const
+
+export const ToolCategorySchema = z
+  .enum(TOOL_CATEGORY_VALUES)
+  .describe(
+    'Used in toolDefinition metadata.category; groups tools and documents allowed values for the LLM.',
+  )
+  .meta({ title: 'Tool category' })
+
+export type ToolCategory = z.infer<typeof ToolCategorySchema>
+```
+
+**Layer 3 — Router search (URL-shaped):** local `validateSearch` schemas; fields are usually optional for partial URLs.
 
 ```typescript
-// src/routes/tasks/index.tsx
 const TasksSearchSchema = z.object({
   status: z.enum(TASK_STATUSES).optional(),
   priority: z.enum(TASK_PRIORITIES).optional(),
@@ -102,31 +106,80 @@ export const Route = createFileRoute('/tasks/')({
 })
 ```
 
-**Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`). Only add a computed-field explanation registry when the field is virtual and cannot be explained by schema metadata or route/tool introspection.
+**Boundary mapping (mandatory):** layer switches happen only in mapper functions; **inbound** tool payloads become repo inputs with `RepoLayerSchema.parse(...)`, **outbound** repo documents become tools/API shapes with `ToolsLayerSchema.parse(...)`.
+
+```typescript
+// Inbound — tools-layer → repository-layer before calling the repo
+function toRepoCreateInput(tool: z.infer<typeof TaskCreateToolSchema>): TaskRepoInput {
+  return TaskRepoInputSchema.parse({
+    title: tool.title,
+    status: tool.status,
+  })
+}
+
+// Outbound — repository row → tools-layer response for server fn + AI
+function toToolTask(row: TaskRepo): z.infer<typeof TaskToolSchema> {
+  return TaskToolSchema.parse({
+    id: row.id,
+    title: row.title,
+    status: row.status,
+  })
+}
+```
+
+**TypeScript discipline (complements Zod):** Zod validates **at boundaries**; TypeScript keeps the interior honest — narrow with guards instead of casting.
+
+```typescript
+type TaskStatus = 'pending' | 'done'
+
+const STATUS_LABEL = {
+  pending: 'Pending',
+  done: 'Done',
+} as const satisfies Record<TaskStatus, string>
+
+function assertNever(x: never): never {
+  throw new Error(`Unexpected ${String(x)}`)
+}
+
+function labelForStatus(status: TaskStatus): string {
+  switch (status) {
+    case 'pending':
+      return STATUS_LABEL.pending
+    case 'done':
+      return STATUS_LABEL.done
+    default:
+      return assertNever(status)
+  }
+}
+```
+
+**Virtual / computed fields:** If semantics cannot live in schema metadata, keep a small registry next to the derivation and expose `explainField` — do not duplicate fields already described by schemas.
 
 ## Request Context
 
-TanStack server functions expose middleware data at `ctx.context`; keep the app-owned value inside it flat. A good default is `{ ticket, client }`, where `ticket` carries identity, roles, predicates, and server-side guards, and `client` carries browser/runtime context such as timezone, locale, current path, and viewport.
+Keep middleware payload at `ctx.context` flat — for example `{ ticket, client }`. **`ticket`** must be **repository-enriched** in middleware (identity, roles, predicates, throwing guards), not just raw JWT claims. Enforce authorization in **server handlers** for every mutation and sensitive read — components may hide buttons, but handlers are authoritative.
 
 ```typescript
-const updateTask = createServerFn({ method: 'POST' })
-  .handler(async ctx => {
-    const { ticket, client } = ctx.context
-    ticket.requireTaskEditor(ctx.data.taskId)
-    return getWritableRepository().updateTask(ctx.data, {
-      actor: ticket.email,
-      timezone: client.timezone,
-    })
+const updateTask = createServerFn({ method: 'POST' }).handler(async ctx => {
+  const { ticket } = ctx.context
+  ticket.requireTaskEditor(ctx.data.taskId)
+  const repoPatch = TaskRepoPatchSchema.parse(mapToolUpdateToRepo(ctx.data))
+  return getWritableRepository().updateTask(ctx.data.taskId, repoPatch, {
+    lastModifiedBy: ticket.email,
   })
+})
 ```
 
-Avoid custom shapes like `{ context: { user, client } }` inside `ctx.context`; they create redundant nested context and make examples harder to copy correctly.
-
 ## Interface Contracts
 
-Repository interfaces use repository-layer types only (never tools-layer schemas). `AIAdapterService` and `ObservabilityService` follow the same interface-first pattern -- see their `types.ts` files.
+Repository interfaces reference **repository-layer types** only. **`WritableRepository`** mutations take an optional **`TraceabilityContext`** built from the auth ticket — not ad-hoc optional email parameters at each call site.
 
 ```typescript
+interface TraceabilityContext {
+  createdBy?: string
+  lastModifiedBy?: string
+}
+
 interface ReadRepository {
   getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
   getTask(id: string): Promise<TaskRepoOutput | null>
@@ -134,113 +187,54 @@ interface ReadRepository {
   getUserProfile(email: string): Promise<UserProfile | null>
 }
 interface WritableRepository {
-  createTask(input: TaskRepoInput, createdBy?: string): Promise<TaskRepoOutput>
-  updateTask(id: string, input: Partial<TaskRepoInput>): Promise<TaskRepoOutput | null>
+  createTask(input: TaskRepoInput, trace?: TraceabilityContext): Promise<TaskRepoOutput>
+  updateTask(
+    id: string,
+    input: Partial<TaskRepoInput>,
+    trace?: TraceabilityContext,
+  ): Promise<TaskRepoOutput | null>
   deleteTask(id: string): Promise<boolean>
 }
 ```
 
-## Overlay Repositories
-
-Use this when base records come from an upstream system (warehouse export, spreadsheet, vendor API) but the app needs local user-owned annotations.
-
-- Keep upstream rows in a read-only source collection.
-- Keep user edits in a sparse overrides collection with audit metadata.
-- Reads load source rows and overrides, then merge through a pure `applyOverrides(source, override)` function.
-- Writes target only the overrides collection; explicit `null`/unset values mean "revert to source".
-- Unit-test the overlay function because it defines the merged view shown to the UI and AI.
-
-## URL-Driven Bulk Editing
-
-For multi-row edits, use a dedicated edit route such as `/tasks/edit?selected=id1&selected=id2`.
-
-- Selection lives in validated URL search params, preferably repeated keys.
-- Edit category/tab state also lives in search params.
-- Dirty tracking stays local to the edit page and submits only changed cells.
-- The mutation server function validates each row's permission and persists through one batched write.
-- Closing nested modal/detail routes clears stale selection search params.
-
-## Dynamic AI Metadata
-
-Prefer live sources over static manifests:
-
-- Route catalog: derive from `router.flatRoutes`, route `staticData`, path params, and `validateSearch` schemas.
-- Field/tool metadata: derive from Zod/ArkType `.describe()` and generated JSON Schema.
-- Help content: keep one markdown artifact for user help, AI help, and suggested prompts when the app needs those surfaces.
-- System prompt: reserve static prompt text for behavior that cannot be discovered from tools, schemas, route metadata, or docs.
-
-## Styling, Auth, and Observability
-
-These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
-
-- **UI library** -- see AGENTS.md section 3 for the selected component library's styling rules. The default template uses Mantine, but generated apps may choose another library.
-- **Auth and Middleware** -- see AGENTS.md section 5 (middleware chain, `AuthContext`, guard helpers, code samples). Rigid rules 9--10 above are the normative summary.
-- **Observability** -- see AGENTS.md section 9 (interface, Sentry/no-op, swap steps).
-
-## Migration / Build Workflow
+## Implementation Flow
 
-1. **Schemas**: repo-layer schemas in `repository.ts`, tools-layer in `schemas.ts` (with `.describe()`), mappers via `Schema.parse()`.
-2. **Repository**: interfaces in `types.ts` (repo-layer types only), seed + production implementations.
-3. **Server functions**: GET queries + POST mutations in `serverFns.ts` with `.inputValidator(ToolSchema)`.
-4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`. Reuse schema metadata for tool descriptions before adding hand-maintained explanatory text.
-5. **Middleware + route catalog**: register pre-auth redirects (if needed), auth, and invalidation in `start.ts`; derive the AI route catalog from router/schema metadata instead of duplicating route tables.
-6. **Routes**: `validateSearch` (Zod/ArkType), `loaderDeps`, loaders calling server functions; nest under layout parents when children share `beforeLoad` or loader data (rule 33).
-7. **Chat + tests**: pass client/browser context to `/api/chat`; E2E specs in `e2e/` against seed repository. For scaffold/setup work, finish by running the app in dev mode and checking `/api/health`.
+1. **Schemas:** repo + tools layers; mappers with `Schema.parse()`.
+2. **Repository:** interfaces in `types.ts`; seed + production implementations.
+3. **Server functions:** `serverFns.ts` — GET queries, POST mutations with shared validators.
+4. **AI tools:** each server function → `toolDefinition` + `createSafeServerTool`; wire client tools in the chat shell (see AGENTS.md §8).
+5. **Middleware:** `start.ts` — auth, invalidation, optional pre-auth `308` redirects for legacy paths.
+6. **Routes:** `validateSearch`, `loaderDeps`, loaders; parent layouts for shared `beforeLoad`/data.
+7. **Chat:** adapter, `chat()`, `buildSystemPrompt`, tool list — details in AGENTS.md §8.
 
-## TanStack Intent and CLI Workflow
+## Special Patterns (use when the feature applies)
 
-Use `tanstack intent` and `tanstack cli` as executable guidance during development. Do not add them as project dependencies unless the generated app explicitly needs them.
+- **Overlay repository:** read-only upstream source + sparse user overrides; pure `applyOverrides`; writes only to overrides.
+- **URL bulk edit:** selection and category tabs in search params; batched mutation; per-row auth.
+- **Help surface:** single `docs/help.md` can back `/help`, an AI tool, and suggested prompts (see AGENTS.md).
+- **Distinct values:** `getDistinctValues` → GET server fn → read-only AI tool so filters match real data.
+- **Dynamic AI navigation:** derive route/help context from `router.flatRoutes` + `validateSearch` introspection where possible.
 
-### TanStack Intent (Package Skills)
-Intent answers "which version-matched package skill should the agent follow?"
-- Setup: Run `npx @tanstack/intent@latest install` when configuring agent instructions in a generated app.
-- Discover: Before substantial TanStack work, run `npx @tanstack/intent@latest list` or use skills already listed in context.
-- Load: Load a matching package skill with `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
-- Check staleness: Use `npx @tanstack/intent@latest stale` to detect outdated source documentation references.
+## TanStack Intent, CLI, and AI
 
-### TanStack CLI
-CLI docs search answers "what do the current TanStack docs say about this API or pattern?"
-- The CLI provides docs search, MCP support, modular integrations, Builder, and deployment/scaffold support.
-- See `npx @tanstack/cli --help` for available commands.
+- **Intent:** `npx @tanstack/intent@latest list | load <pkg>#<skill> | stale` — pick version-matched package skills before deep TanStack work.
+- **CLI (prefer current docs over memory):** `npx @tanstack/cli --help` → `libraries`, `search-docs "<query>" --library router|start|ai`, `doc <library> <path>`.
+- **AI stack:** `@tanstack/ai`, `@tanstack/ai-react`, `/api/chat` — provider table, SSE wiring, system prompt sections, and chat endpoint anatomy are spelled out in **AGENTS.md §8**.
 
-## TanStack documentation (official CLI)
+## Use the handbook (AGENTS.md)
 
-Prefer **current** TanStack guidance over training-data recall. The TanStack team ships a CLI that mirrors the docs site.
-
-- Run `npx @tanstack/cli --help` first to see the command surface; use `npx @tanstack/cli help <command>` (e.g. `help search-docs`) for flags and arguments on the machine you are using.
-- `npx @tanstack/cli libraries` — list library **IDs** and versions (use these IDs with `doc` and `search-docs --library`).
-- `npx @tanstack/cli search-docs "<query>" [--library router|start|ai|query|table|...] [--framework <name>] [--limit N]` — find doc sections before changing router, Start, or AI code.
-- `npx @tanstack/cli doc <library> <path> [--docs-version latest]` — fetch a full doc page (library examples: `router`, `start`, `ai`, `query`; path examples mirror the docs tree, e.g. `framework/react/guide/data-loading` — confirm the exact path via `search-docs` when unsure).
-
-**Quick reference**
-
-| Need | Starting point |
-|------|----------------|
-| Correct loader / `beforeLoad` / layout behavior | `search-docs` with `--library router` (or `start` for TanStack Start) |
-| Exact chat / tool / adapter API | `search-docs` / `doc` with `--library ai` |
-| Unknown CLI flag | `npx @tanstack/cli --help` and command-specific `--help` |
-
-## AI Architecture
-
-The AI stack uses three packages from `@tanstack/ai`:
-
-- **Server** (`@tanstack/ai`): `chat()`, `toolDefinition()`, `convertMessagesToModelMessages()`, `toServerSentEventsResponse()`, `maxIterations()`. Adapter packages: `@tanstack/ai-openai`, `@tanstack/ai-anthropic`, `@tanstack/ai-gemini`, `@tanstack/ai-ollama`, `@tanstack/ai-openrouter`, `@tanstack/ai-groq`, `@tanstack/ai-grok`. See AGENTS.md section 8 for the provider table, env vars, and adapter factory pattern.
-- **Client** (`@tanstack/ai-react` + `@tanstack/ai-client`): `useChat()`, `fetchServerSentEvents()`, `clientTools()`, `createChatClientOptions()`. Client tools execute automatically — no `onToolCall` callback. See AGENTS.md section 8 "Chat Client Setup" for the wiring example.
-- **Endpoint** (`src/routes/api/chat.ts`): the wiring point connecting adapter, system prompt, tools, and auth. See below and AGENTS.md section 8 "Chat Endpoint" for the full anatomy.
-
-### Chat Endpoint (`src/routes/api/chat.ts`)
-
-A TanStack Start file-based route at `/api/chat` with two handlers:
-
-- **GET** — returns `{ available: boolean }` so the root loader can decide whether to show the chat UI (rule 19).
-- **POST** — check adapter → parse `{ messages, browserContext }` → read the request ticket from middleware context → validate client context schema → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
-
-`buildSystemPrompt()` composes `BASE_SYSTEM_PROMPT` (rule 25) + navigation manifest + dynamic context (rule 14). When modifying: add tools to the array, update `BASE_SYSTEM_PROMPT` when the data model changes, add pattern-matching for new dynamic route segments. See AGENTS.md section 8 "System Prompt Generation" for the six-section prompt template.
-
-## Dynamic Route Schema Extraction for AI
-
-To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params by introspecting `validateSearch` schemas where possible. Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs. Fall back to hand-maintained metadata only when the framework/schema surface cannot expose the needed description.
+| Need | Where |
+|------|--------|
+| UI kit (default Mantine), styling | §3 |
+| Auth, middleware, guards | §5 |
+| AI adapters, chat client, tools, prompts | §8 |
+| Observability (Sentry, pino, `__APP_VERSION__`) | §9 |
+| Vitest, Playwright, E2E fixtures | §10 |
+| Full validation checklist (format, lint, test, build) | §17 |
+| Public runtime `window.__ENV__` | §13 |
 
 ## Verification
 
-Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm knip && pnpm test && pnpm build`. If the project has not wired Knip yet, add the latest stable `knip` dev dependency or explicitly document why unused-code validation is deferred. After scaffolding or setup changes, also start dev mode and ping `/api/health`; if required credentials are missing, state which prerequisite blocked the health check and what was verified instead.
+**This template repo (skill authors):** after editing YAML, run `pnpm skills:build` and `pnpm skills:check`.
+
+**Apps built from the template:** follow **AGENTS.md** §17 — e.g. `pnpm format && pnpm lint && pnpm test && pnpm build`; smoke with dev server and `/api/health` when configuration allows.
diff --git a/skills/dist/tanstack-promptable-fullstack-app-template.md b/skills/dist/tanstack-promptable-fullstack-app-template.md
index 874340c..31d54d5 100644
--- a/skills/dist/tanstack-promptable-fullstack-app-template.md
+++ b/skills/dist/tanstack-promptable-fullstack-app-template.md
@@ -9,9 +9,9 @@
 - Documentation: https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/skills/README.md
 - Status: stable
 - Supported tools: Windsurf [native, tested], Cursor [copy, tested], Claude Code [copy, tested]
-- Capabilities: AI promptable application architecture, Promptable-by-default AI chat in a side drawer when credentials are present, Natural language querying through repository-backed AI tools, URL-aware AI prompt context using current location and route patterns, Swappable service implementations behind stable interfaces, Layer-specific schemas with explicit mapping between repository and tool contracts, Thin routes with extracted, testable page components, Structured server-side logging with pino and automatic Sentry error forwarding, Build-time semver version injected into observability tools for release tracking, Public runtime config exposed to the browser via window.__ENV__ without relying on import.meta.env, Consistent router UX defaults for preload, stale time, and scroll restoration, Distinct-value filter discovery tools that ground AI filter values in real data, Single markdown artifact backing the help page, an AI tool, and the chat's recommended-prompt list, Parent layout routes that centralize beforeLoad guards and shared loader data for nested child routes, Dynamic route schema extraction for AI tool-calling and context awareness, Schema metadata and framework introspection used as the primary source for AI-facing field, route, and filter explanations, Optional computed-field explanation registries only for virtual values that schemas cannot describe, Upstream-source overlay repositories with sparse user-owned overrides, URL-driven bulk edit routes with dirty tracking and batched mutation functions, TanStack Intent integration for package-specific skill discovery
+- Capabilities: Interface-first boundaries with swappable implementations, Three schema layers with mandatory Schema.parse() at every boundary (tool→repo and repo→tool), Strong TypeScript inside the typed flow — inference preserved with satisfies unions exhaustive checks few casts, Loader-first routes and URL-driven state via validateSearch, Router config bundle (defaults + project Link wrapper preserving search params), Full AI tool coverage mirroring repository surface + client navigate/invalidate tools, Schema-first AI/UI metadata (.describe + optional .meta for unit/format/title), Promptable by default — getAIAvailability gating + browserContext + bounded agent loop, Auth ticket built in middleware via repository + TraceabilityContext on writes, Parent layout routes deduplicating shared beforeLoad and loaders, Optional patterns — overlay repo, bulk edit, distinct-values tools, dynamic route introspection, TanStack Intent + CLI as doc-aligned guidance (not duplicated command manuals)
 - ID: `tanstack-promptable-fullstack-app-template`
-- Version: `1.11.0`
+- Version: `1.16.0`
 - Tags: tanstack-start, fullstack, architecture, interface-first, repository-pattern, ai-promptable
 
 ## Summary
@@ -35,82 +35,86 @@ Use when scaffolding a new TanStack Start project, adding domain entities to the
 ## Canonical Content
 # TanStack Fullstack Pattern
 
-An interface-first fullstack architecture built on TanStack Start. The pattern defines clear interface boundaries between layers -- interfaces are rigid, implementations are swappable.
-
-> **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, chosen UI-library styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
-
-## Pattern Overview
-
-- Zero-config development with seed implementations and swappable service layers
-- AI promptability by exposing every repository method (reads and writes) as tools
-- End-to-end type safety from schema-first definitions with explicit layer boundaries
-
-## Rigid Rules (Must Follow)
-
-1. Interface-first services: every external service (database, AI, observability) is accessed through an interface.
-2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes. Prefer schema metadata and introspection (`.describe()`, route `validateSearch`, tool schemas, router `staticData`, JSON Schema output) over hand-maintained AI metadata.
-3. Three schema layers: repository (DB-shaped), server-function / AI-tool (API-shaped, shared), router search-param (URL-shaped). Mappers translate between layers.
-4. Repository contracts use repository-layer schemas only.
-5. Server functions and AI tools share the same tools-layer schemas (`.inputValidator(Schema)` / `toolDefinition({ inputSchema })`). Both parse with `Schema.parse(args)`.
-6. AI and UI interact only with tools-layer schemas; they must not depend directly on repository schemas.
-7. Loaders-first data fetching: fetch route data in loaders through server functions.
-8. URL-as-state: filters, tabs, selections live in URL search params via `validateSearch` (Zod/ArkType). Use `loaderDeps` to feed validated search into loaders.
-9. Middleware chain: auth is global middleware, invalidation runs on mutation server functions.
-10. Mutation pattern: POST server functions chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`, return domain data or throw `HttpError`. Callers normalize errors: UI via `processResponse()`, AI tools via `safeToolHandler()` / `createSafeServerTool()`.
-11. Query pattern: GET server functions throw on failure for centralized error handling. When possible, use static server functions for performance improvements.
-12. Maximize AI tool coverage: expose **every** repository method (reads and writes) via `createSafeServerTool()` so failures return `{ error, code }`. If a server function exists, it gets a tool.
-13. Router capabilities as AI client tools: expose `router.navigate()` and `router.invalidate()` as client tools via `toolDefinition()`.
-14. AI system prompt context: `buildSystemPrompt()` injects context into every AI chat request from the single request context and the client ticket sent by the chat UI. Keep the request context flat (for example `{ ticket, client }` inside TanStack's `ctx.context`) and destructure it early in handlers; do not introduce nested custom context wrappers. Include current user, browser context, and current location. Derive route patterns and search params from live router/schema metadata where possible instead of maintaining static route tables.
-15. JSDoc on exports: every exported function, interface, type, and constant gets a JSDoc comment stating *what* and *why*.
-16. AI chat drawer: render the AI chat in the chosen UI library's right-side drawer/panel component mounted at the root layout level so messages persist across navigation. The template's default is a Mantine `Drawer` (`position="right"`, `size="lg"`), but generated apps may swap the component library when the user chooses a different stack.
-17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code are styled through the chat markdown container using the chosen design system's theme tokens or CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
-18. Thin routes: route files contain only route config (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`). Page UI lives in `src/components/PageName/PageName.tsx`.
-19. Promptable by default: check AI availability at the root loader level via `getAIAvailability()`. Only render the chat trigger and drawer when AI is configured — no disabled-state fallback.
-20. Icon library: use `lucide-react` as the default icon library. Keep one icon library per project for visual consistency.
-21. Structured logging: use `pino` for all server-side logging instead of `console.*`. Configure `@sentry/pino-transport` so error-level logs are automatically forwarded to Sentry when `VITE_SENTRY_DSN` is set. The logger singleton lives in `src/services/logger.ts`.
-22. Build-time app version: extract the semver version from `package.json` at build time via Vite `define` and expose it as `__APP_VERSION__`. Inject it into Sentry (`release`), the pino logger (`version` field), and any other observability tool.
-23. Dependency discipline: avoid installing unnecessary packages. Prefer existing project dependencies and platform APIs. When a package is truly required by the chosen stack, requested capability, or validation contract, use the latest stable compatible version via the package manager (`pnpm add <pkg>` with no guessed version suffix unless a known incompatibility requires a pin); run `pnpm outdated` and `pnpm update` to align the lockfile.
-24. Ask for LLM provider: when scaffolding a new project or when the user's LLM preference is unclear, ask which provider they want before writing the adapter. Install only the chosen `@tanstack/ai-*` adapter package and configure matching env vars. Default is `@tanstack/ai-openai`; do not assume OpenAI without asking. See AGENTS.md section 8 for the full provider table.
-25. Generate the system prompt: when scaffolding a new app, ask the user about their domain — entities, capabilities, and permissions — then generate a tailored `BASE_SYSTEM_PROMPT` in `src/routes/api/chat.ts` with six sections (Capabilities, Data Model, Links and navigation, Mutations and data refresh, Permissions and errors, Guidelines). Do not reuse the template's task-management prompt. `buildSystemPrompt()` composes this base with dynamic context (rule 14) and the navigation manifest. `chat()` from `@tanstack/ai` receives it via `systemPrompts: string[]`. See AGENTS.md section 8 "System Prompt Generation" for the full template.
-26. Repository-resolved authorization: auth middleware extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich the request context with application-defined access data — roles, group memberships, owned scopes, superuser flags. Prefer a flat access-ticket object with identity, roles, UI-safe predicates, and throwing server guards. Downstream server functions and AI tools read this one ticket so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of caller.
-27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from the request ticket (for example, `ticket.email`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
-28. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
-29. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
-30. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
-31. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
-32. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
-33. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
-34. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
-35. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
-36. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
-37. Computed-field explanation fallback: for virtual fields whose semantics cannot be inferred from schema metadata (for example derived status, health, disposition, rollup, or permission fields), keep a small explanation registry next to the computation logic and expose an `explainField(fieldName)` AI tool. Do not duplicate explanations for fields already described by schemas.
-38. Overlay repository pattern: when upstream systems own base data and users need local annotations, keep a read-only source collection plus a sparse overrides collection. Reads merge both through a pure `applyOverrides(source, override)` function; writes target only overrides and use explicit null/unset semantics to revert to source values.
-39. URL-driven bulk edit pattern: store selected IDs and edit-category state in validated URL search params, keep dirty tracking local to the edit page, submit only changed fields, authorize per row, persist via a batched mutation, and clear stale selections when closing nested modal/detail routes.
-40. Pre-auth redirect middleware: for renamed routes or legacy URL schemes, add a narrow middleware before auth that returns a relative `308 Permanent Redirect`. This prevents old links from producing misleading 401s. Keep the allowlist small and retire entries once upstream links migrate.
+**Purpose:** Capture the **interface-first, schema-layered, AI-promptable** contract for TanStack Start apps from this template. Day-to-day conventions (UI kit, chat wiring, logging, tests) live in the repo’s **AGENTS.md** — use this skill for **architecture**, AGENTS.md for **operations**.
+
+> **Companion handbook:** [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) — structure, styling, auth snippets, Biome, testing/E2E, validation checklist, AI chat setup.
+
+## Core Contract
+
+1. **Interfaces:** Database, AI, observability (and other externals) sit behind interfaces; implementations are swappable.
+2. **Schemas as the type source:** Wire and tool shapes use Zod/ArkType + `z.infer<>`. Hand-written interfaces define **behavior** (`ReadRepository`, `AIAdapterService`, …), not ad-hoc JSON types.
+3. **Three schema layers:** **Repository** (DB-shaped), **tools / server-fn** (API-shaped, shared between `createServerFn` and `toolDefinition`), **router search** (URL-shaped). Translate with `Schema.parse()` at each boundary.
+4. **TypeScript inside the typed flow:** After schema boundaries, preserve **inferred types end-to-end** — prefer `satisfies`, discriminated unions, `as const` tuples, narrow **type guards**, and **exhaustive `switch`** (e.g. `default` branch calling `assertNever`) over `any`, broad `unknown` plumbing, or `as` casts (only use `as` at documented third-party/library seams per AGENTS.md).
+5. **Repository vs tools:** Repository implementations use repository-layer schemas only. **Server functions and AI tools share the same tools-layer schemas** (`.inputValidator` / `toolDefinition` inputSchema + `Schema.parse`). UI and AI consume tools-layer types only — never import repository schemas at those edges.
+6. **Server functions:** GET queries throw on failure; POST mutations chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`; handlers return data or throw `HttpError`; callers normalize with `processResponse` / `safeToolHandler` / `createSafeServerTool`.
+7. **Routes:** Thin route files (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`); page UI in `src/components/`. **Loaders** fetch via server functions — no `useEffect` data fetching for route data.
+8. **URL-as-state:** Filters, tabs, selections in validated **search** params; use `loaderDeps` so only relevant search fields key the loader cache.
+9. **Router config bundle:** ship a project-local `Link` wrapper with `search: true` default (use it for every internal link) **and** these router defaults together: `defaultStaleTime`, `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0`, `scrollRestoration: true`, `notFoundComponent`.
+10. **Auth ticket built in middleware:** auth middleware enriches `ctx.context` with a repository-built ticket (e.g. `getReadRepository().getUserAccess(email)`) carrying identity, roles, and guards; `WritableRepository` mutations accept a `TraceabilityContext` (`createdBy`, `lastModifiedBy`, …) constructed from that ticket so writes are attributed consistently across UI and AI.
+11. **AI tool coverage:** expose **every** repository method as a server AI tool via `createSafeServerTool`; add **distinct-values** tools for enum-ish filters; expose `navigate` and `invalidateRouter` as client tools.
+12. **Promptable by default:** root loader checks `getAIAvailability()` and only mounts chat UI when configured (no disabled state). Chat input includes a `browserContext` (timezone, locale, path) consumed by `buildSystemPrompt` alongside the auth ticket.
+13. **Bound the agent loop:** every `chat()` call sets `agentLoopStrategy: maxIterations(N)` explicitly (default `N=10`); tune after measuring — do not rely on the framework default.
+14. **Metadata for AI and UI:** Use `.describe()` for all narrative explanations (JSON Schema `description`). Use `.meta({ ... })` only for **structured extras** — `unit`, `format`, optional `title`, app-specific hints — not as a substitute for `.describe()`. Prefer deriving prompts and UI copy from schemas + `z.toJSONSchema()` and router introspection over parallel hand-maintained maps.
+15. **Parent layouts:** Shared `beforeLoad`, redirects, and expensive reads belong on the **parent** layout route; children read parent loader data via `getRouteApi` / `useLoaderData({ from })` — do not duplicate parent work.
+
+Day-to-day operational concerns (UI kit, chat drawer placement, markdown rendering, LLM provider choice, pino/Sentry, icons, RSC vs `"use client"`, full validation commands) follow **AGENTS.md** — see the handbook table below.
+
+## Architecture Checklist
+
+Scan before changing code:
+
+- **One tools-layer schema per wire shape:** `createServerFn` `.inputValidator(Schema)` and AI `toolDefinition({ inputSchema })` share the same schema — no duplicate hand-written wire types.
+- **Parse both directions:** tools → repository inputs and repository rows → tools/API outputs each end in the target layer’s `Schema.parse()` (pure mapper functions are fine if the final step is always `.parse()`).
+- **No type erasure:** after `Schema.parse`, carry **`z.infer`-derived types** through server functions, repos, tools, and components — do not widen back to `Record<string, unknown>` / `any`.
+- **Repository interfaces = repo-layer types only:** mapping lives beside schemas / mappers — not in React components.
+- **Auth ticket is repository-backed and server-enforced:** middleware builds the ticket (e.g. `getReadRepository().getUserAccess(email)`); guards run in **server handlers**, never UI-only.
+- **Writes use `TraceabilityContext`:** pass audit fields from the ticket through a single context object on `WritableRepository` mutations — avoid sprinkling raw `email` arguments.
+- **Navigation is one decision:** ship the **router defaults bundle** and the **project `Link` wrapper** (`search: true`) together so URL state survives navigation.
+- **AI stack is complete:** every repo method → server tool + safe handler; client **`navigate`** / **`invalidateRouter`**; root **`getAIAvailability()`**; chat payload includes **`browserContext`**; **`chat({ agentLoopStrategy: maxIterations(N) })`**.
+- **Routes:** **`validateSearch`** + **`loaderDeps`**; duplicate **`beforeLoad`** / shared loaders only on **parent** layouts.
+- **Metadata discipline:** `.describe()` for narrative copy; `.meta()` for structured extras; closed vocabularies = `as const` tuple + `z.enum` + `z.infer<>`.
 
 ## Schema Boundaries
 
-`Route search schema -> loader -> tools schema -> server fn -> mapping -> repo schema -> repo impl`
+`Route search schema → loader → tools schema → server fn → mapping → repo schema → repo`
 
-`repo output -> mapping -> tools schema -> AI or UI`
+`repo output → mapping → tools schema → AI or UI`
 
-**Layer 1 — Repository schemas (DB-shaped):** internal to the repository, no `.describe()` needed. Define in `src/services/schemas/repository.ts` (target pattern -- currently all schemas live in `schemas.ts`). Infer types with `z.infer<>`.
+**Layer 1 — Repository (DB-shaped):** define in `src/services/schemas/repository.ts` (target layout; today some apps still colocate in `schemas.ts`). No `.describe()` required here. Infer with `z.infer<>`.
 
-**Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI. Use these schema descriptions as the first source for field explanations, filter help, and AI tool guidance before adding any separate metadata file.
+**Layer 2 — Tools / server functions (API-shaped):** one schema for `.inputValidator(Schema)` and `toolDefinition({ inputSchema })`; parse args with `Schema.parse(args)`.
 
 ```typescript
-// src/services/schemas/schemas.ts
+// Example: tools-layer object — .describe() for text; .meta() for non-description fields
 const TaskInputSchema = z.object({
   title: z.string().min(1).describe('Short title'),
   status: TaskStatusSchema.default('pending').describe('Current status'),
-  assignee: z.string().optional().describe('Assignee email'),
+  estimateHours: z
+    .number()
+    .optional()
+    .describe('Estimated effort in hours')
+    .meta({ unit: 'h', format: 'decimal' }),
 })
 ```
 
-**Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional. Introspect these schemas, plus route `staticData`, when building AI navigation catalogs and link/filter guidance.
+**Closed vocabularies (enums, tool categories, filter buckets):** `const VALUES = [...] as const`, then `z.enum(VALUES)`, put prose in `.describe()`, optional `.meta({ title: '...' })`, infer with `z.infer<>`. **Do not** treat `export const LABELS = { id: 'Display Name' } as const` as the authority for the same strings unless it is derived from or validated by that schema.
+
+```typescript
+const TOOL_CATEGORY_VALUES = ['Metadata & Navigation', 'Strategic Objectives'] as const
+
+export const ToolCategorySchema = z
+  .enum(TOOL_CATEGORY_VALUES)
+  .describe(
+    'Used in toolDefinition metadata.category; groups tools and documents allowed values for the LLM.',
+  )
+  .meta({ title: 'Tool category' })
+
+export type ToolCategory = z.infer<typeof ToolCategorySchema>
+```
+
+**Layer 3 — Router search (URL-shaped):** local `validateSearch` schemas; fields are usually optional for partial URLs.
 
 ```typescript
-// src/routes/tasks/index.tsx
 const TasksSearchSchema = z.object({
   status: z.enum(TASK_STATUSES).optional(),
   priority: z.enum(TASK_PRIORITIES).optional(),
@@ -123,31 +127,80 @@ export const Route = createFileRoute('/tasks/')({
 })
 ```
 
-**Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`). Only add a computed-field explanation registry when the field is virtual and cannot be explained by schema metadata or route/tool introspection.
+**Boundary mapping (mandatory):** layer switches happen only in mapper functions; **inbound** tool payloads become repo inputs with `RepoLayerSchema.parse(...)`, **outbound** repo documents become tools/API shapes with `ToolsLayerSchema.parse(...)`.
+
+```typescript
+// Inbound — tools-layer → repository-layer before calling the repo
+function toRepoCreateInput(tool: z.infer<typeof TaskCreateToolSchema>): TaskRepoInput {
+  return TaskRepoInputSchema.parse({
+    title: tool.title,
+    status: tool.status,
+  })
+}
+
+// Outbound — repository row → tools-layer response for server fn + AI
+function toToolTask(row: TaskRepo): z.infer<typeof TaskToolSchema> {
+  return TaskToolSchema.parse({
+    id: row.id,
+    title: row.title,
+    status: row.status,
+  })
+}
+```
+
+**TypeScript discipline (complements Zod):** Zod validates **at boundaries**; TypeScript keeps the interior honest — narrow with guards instead of casting.
+
+```typescript
+type TaskStatus = 'pending' | 'done'
+
+const STATUS_LABEL = {
+  pending: 'Pending',
+  done: 'Done',
+} as const satisfies Record<TaskStatus, string>
+
+function assertNever(x: never): never {
+  throw new Error(`Unexpected ${String(x)}`)
+}
+
+function labelForStatus(status: TaskStatus): string {
+  switch (status) {
+    case 'pending':
+      return STATUS_LABEL.pending
+    case 'done':
+      return STATUS_LABEL.done
+    default:
+      return assertNever(status)
+  }
+}
+```
+
+**Virtual / computed fields:** If semantics cannot live in schema metadata, keep a small registry next to the derivation and expose `explainField` — do not duplicate fields already described by schemas.
 
 ## Request Context
 
-TanStack server functions expose middleware data at `ctx.context`; keep the app-owned value inside it flat. A good default is `{ ticket, client }`, where `ticket` carries identity, roles, predicates, and server-side guards, and `client` carries browser/runtime context such as timezone, locale, current path, and viewport.
+Keep middleware payload at `ctx.context` flat — for example `{ ticket, client }`. **`ticket`** must be **repository-enriched** in middleware (identity, roles, predicates, throwing guards), not just raw JWT claims. Enforce authorization in **server handlers** for every mutation and sensitive read — components may hide buttons, but handlers are authoritative.
 
 ```typescript
-const updateTask = createServerFn({ method: 'POST' })
-  .handler(async ctx => {
-    const { ticket, client } = ctx.context
-    ticket.requireTaskEditor(ctx.data.taskId)
-    return getWritableRepository().updateTask(ctx.data, {
-      actor: ticket.email,
-      timezone: client.timezone,
-    })
+const updateTask = createServerFn({ method: 'POST' }).handler(async ctx => {
+  const { ticket } = ctx.context
+  ticket.requireTaskEditor(ctx.data.taskId)
+  const repoPatch = TaskRepoPatchSchema.parse(mapToolUpdateToRepo(ctx.data))
+  return getWritableRepository().updateTask(ctx.data.taskId, repoPatch, {
+    lastModifiedBy: ticket.email,
   })
+})
 ```
 
-Avoid custom shapes like `{ context: { user, client } }` inside `ctx.context`; they create redundant nested context and make examples harder to copy correctly.
-
 ## Interface Contracts
 
-Repository interfaces use repository-layer types only (never tools-layer schemas). `AIAdapterService` and `ObservabilityService` follow the same interface-first pattern -- see their `types.ts` files.
+Repository interfaces reference **repository-layer types** only. **`WritableRepository`** mutations take an optional **`TraceabilityContext`** built from the auth ticket — not ad-hoc optional email parameters at each call site.
 
 ```typescript
+interface TraceabilityContext {
+  createdBy?: string
+  lastModifiedBy?: string
+}
+
 interface ReadRepository {
   getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
   getTask(id: string): Promise<TaskRepoOutput | null>
@@ -155,113 +208,54 @@ interface ReadRepository {
   getUserProfile(email: string): Promise<UserProfile | null>
 }
 interface WritableRepository {
-  createTask(input: TaskRepoInput, createdBy?: string): Promise<TaskRepoOutput>
-  updateTask(id: string, input: Partial<TaskRepoInput>): Promise<TaskRepoOutput | null>
+  createTask(input: TaskRepoInput, trace?: TraceabilityContext): Promise<TaskRepoOutput>
+  updateTask(
+    id: string,
+    input: Partial<TaskRepoInput>,
+    trace?: TraceabilityContext,
+  ): Promise<TaskRepoOutput | null>
   deleteTask(id: string): Promise<boolean>
 }
 ```
 
-## Overlay Repositories
-
-Use this when base records come from an upstream system (warehouse export, spreadsheet, vendor API) but the app needs local user-owned annotations.
-
-- Keep upstream rows in a read-only source collection.
-- Keep user edits in a sparse overrides collection with audit metadata.
-- Reads load source rows and overrides, then merge through a pure `applyOverrides(source, override)` function.
-- Writes target only the overrides collection; explicit `null`/unset values mean "revert to source".
-- Unit-test the overlay function because it defines the merged view shown to the UI and AI.
-
-## URL-Driven Bulk Editing
-
-For multi-row edits, use a dedicated edit route such as `/tasks/edit?selected=id1&selected=id2`.
-
-- Selection lives in validated URL search params, preferably repeated keys.
-- Edit category/tab state also lives in search params.
-- Dirty tracking stays local to the edit page and submits only changed cells.
-- The mutation server function validates each row's permission and persists through one batched write.
-- Closing nested modal/detail routes clears stale selection search params.
-
-## Dynamic AI Metadata
-
-Prefer live sources over static manifests:
-
-- Route catalog: derive from `router.flatRoutes`, route `staticData`, path params, and `validateSearch` schemas.
-- Field/tool metadata: derive from Zod/ArkType `.describe()` and generated JSON Schema.
-- Help content: keep one markdown artifact for user help, AI help, and suggested prompts when the app needs those surfaces.
-- System prompt: reserve static prompt text for behavior that cannot be discovered from tools, schemas, route metadata, or docs.
-
-## Styling, Auth, and Observability
-
-These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
-
-- **UI library** -- see AGENTS.md section 3 for the selected component library's styling rules. The default template uses Mantine, but generated apps may choose another library.
-- **Auth and Middleware** -- see AGENTS.md section 5 (middleware chain, `AuthContext`, guard helpers, code samples). Rigid rules 9--10 above are the normative summary.
-- **Observability** -- see AGENTS.md section 9 (interface, Sentry/no-op, swap steps).
-
-## Migration / Build Workflow
+## Implementation Flow
 
-1. **Schemas**: repo-layer schemas in `repository.ts`, tools-layer in `schemas.ts` (with `.describe()`), mappers via `Schema.parse()`.
-2. **Repository**: interfaces in `types.ts` (repo-layer types only), seed + production implementations.
-3. **Server functions**: GET queries + POST mutations in `serverFns.ts` with `.inputValidator(ToolSchema)`.
-4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`. Reuse schema metadata for tool descriptions before adding hand-maintained explanatory text.
-5. **Middleware + route catalog**: register pre-auth redirects (if needed), auth, and invalidation in `start.ts`; derive the AI route catalog from router/schema metadata instead of duplicating route tables.
-6. **Routes**: `validateSearch` (Zod/ArkType), `loaderDeps`, loaders calling server functions; nest under layout parents when children share `beforeLoad` or loader data (rule 33).
-7. **Chat + tests**: pass client/browser context to `/api/chat`; E2E specs in `e2e/` against seed repository. For scaffold/setup work, finish by running the app in dev mode and checking `/api/health`.
+1. **Schemas:** repo + tools layers; mappers with `Schema.parse()`.
+2. **Repository:** interfaces in `types.ts`; seed + production implementations.
+3. **Server functions:** `serverFns.ts` — GET queries, POST mutations with shared validators.
+4. **AI tools:** each server function → `toolDefinition` + `createSafeServerTool`; wire client tools in the chat shell (see AGENTS.md §8).
+5. **Middleware:** `start.ts` — auth, invalidation, optional pre-auth `308` redirects for legacy paths.
+6. **Routes:** `validateSearch`, `loaderDeps`, loaders; parent layouts for shared `beforeLoad`/data.
+7. **Chat:** adapter, `chat()`, `buildSystemPrompt`, tool list — details in AGENTS.md §8.
 
-## TanStack Intent and CLI Workflow
+## Special Patterns (use when the feature applies)
 
-Use `tanstack intent` and `tanstack cli` as executable guidance during development. Do not add them as project dependencies unless the generated app explicitly needs them.
+- **Overlay repository:** read-only upstream source + sparse user overrides; pure `applyOverrides`; writes only to overrides.
+- **URL bulk edit:** selection and category tabs in search params; batched mutation; per-row auth.
+- **Help surface:** single `docs/help.md` can back `/help`, an AI tool, and suggested prompts (see AGENTS.md).
+- **Distinct values:** `getDistinctValues` → GET server fn → read-only AI tool so filters match real data.
+- **Dynamic AI navigation:** derive route/help context from `router.flatRoutes` + `validateSearch` introspection where possible.
 
-### TanStack Intent (Package Skills)
-Intent answers "which version-matched package skill should the agent follow?"
-- Setup: Run `npx @tanstack/intent@latest install` when configuring agent instructions in a generated app.
-- Discover: Before substantial TanStack work, run `npx @tanstack/intent@latest list` or use skills already listed in context.
-- Load: Load a matching package skill with `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
-- Check staleness: Use `npx @tanstack/intent@latest stale` to detect outdated source documentation references.
+## TanStack Intent, CLI, and AI
 
-### TanStack CLI
-CLI docs search answers "what do the current TanStack docs say about this API or pattern?"
-- The CLI provides docs search, MCP support, modular integrations, Builder, and deployment/scaffold support.
-- See `npx @tanstack/cli --help` for available commands.
+- **Intent:** `npx @tanstack/intent@latest list | load <pkg>#<skill> | stale` — pick version-matched package skills before deep TanStack work.
+- **CLI (prefer current docs over memory):** `npx @tanstack/cli --help` → `libraries`, `search-docs "<query>" --library router|start|ai`, `doc <library> <path>`.
+- **AI stack:** `@tanstack/ai`, `@tanstack/ai-react`, `/api/chat` — provider table, SSE wiring, system prompt sections, and chat endpoint anatomy are spelled out in **AGENTS.md §8**.
 
-## TanStack documentation (official CLI)
+## Use the handbook (AGENTS.md)
 
-Prefer **current** TanStack guidance over training-data recall. The TanStack team ships a CLI that mirrors the docs site.
-
-- Run `npx @tanstack/cli --help` first to see the command surface; use `npx @tanstack/cli help <command>` (e.g. `help search-docs`) for flags and arguments on the machine you are using.
-- `npx @tanstack/cli libraries` — list library **IDs** and versions (use these IDs with `doc` and `search-docs --library`).
-- `npx @tanstack/cli search-docs "<query>" [--library router|start|ai|query|table|...] [--framework <name>] [--limit N]` — find doc sections before changing router, Start, or AI code.
-- `npx @tanstack/cli doc <library> <path> [--docs-version latest]` — fetch a full doc page (library examples: `router`, `start`, `ai`, `query`; path examples mirror the docs tree, e.g. `framework/react/guide/data-loading` — confirm the exact path via `search-docs` when unsure).
-
-**Quick reference**
-
-| Need | Starting point |
-|------|----------------|
-| Correct loader / `beforeLoad` / layout behavior | `search-docs` with `--library router` (or `start` for TanStack Start) |
-| Exact chat / tool / adapter API | `search-docs` / `doc` with `--library ai` |
-| Unknown CLI flag | `npx @tanstack/cli --help` and command-specific `--help` |
-
-## AI Architecture
-
-The AI stack uses three packages from `@tanstack/ai`:
-
-- **Server** (`@tanstack/ai`): `chat()`, `toolDefinition()`, `convertMessagesToModelMessages()`, `toServerSentEventsResponse()`, `maxIterations()`. Adapter packages: `@tanstack/ai-openai`, `@tanstack/ai-anthropic`, `@tanstack/ai-gemini`, `@tanstack/ai-ollama`, `@tanstack/ai-openrouter`, `@tanstack/ai-groq`, `@tanstack/ai-grok`. See AGENTS.md section 8 for the provider table, env vars, and adapter factory pattern.
-- **Client** (`@tanstack/ai-react` + `@tanstack/ai-client`): `useChat()`, `fetchServerSentEvents()`, `clientTools()`, `createChatClientOptions()`. Client tools execute automatically — no `onToolCall` callback. See AGENTS.md section 8 "Chat Client Setup" for the wiring example.
-- **Endpoint** (`src/routes/api/chat.ts`): the wiring point connecting adapter, system prompt, tools, and auth. See below and AGENTS.md section 8 "Chat Endpoint" for the full anatomy.
-
-### Chat Endpoint (`src/routes/api/chat.ts`)
-
-A TanStack Start file-based route at `/api/chat` with two handlers:
-
-- **GET** — returns `{ available: boolean }` so the root loader can decide whether to show the chat UI (rule 19).
-- **POST** — check adapter → parse `{ messages, browserContext }` → read the request ticket from middleware context → validate client context schema → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
-
-`buildSystemPrompt()` composes `BASE_SYSTEM_PROMPT` (rule 25) + navigation manifest + dynamic context (rule 14). When modifying: add tools to the array, update `BASE_SYSTEM_PROMPT` when the data model changes, add pattern-matching for new dynamic route segments. See AGENTS.md section 8 "System Prompt Generation" for the six-section prompt template.
-
-## Dynamic Route Schema Extraction for AI
-
-To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params by introspecting `validateSearch` schemas where possible. Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs. Fall back to hand-maintained metadata only when the framework/schema surface cannot expose the needed description.
+| Need | Where |
+|------|--------|
+| UI kit (default Mantine), styling | §3 |
+| Auth, middleware, guards | §5 |
+| AI adapters, chat client, tools, prompts | §8 |
+| Observability (Sentry, pino, `__APP_VERSION__`) | §9 |
+| Vitest, Playwright, E2E fixtures | §10 |
+| Full validation checklist (format, lint, test, build) | §17 |
+| Public runtime `window.__ENV__` | §13 |
 
 ## Verification
 
-Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm knip && pnpm test && pnpm build`. If the project has not wired Knip yet, add the latest stable `knip` dev dependency or explicitly document why unused-code validation is deferred. After scaffolding or setup changes, also start dev mode and ping `/api/health`; if required credentials are missing, state which prerequisite blocked the health check and what was verified instead.
+**This template repo (skill authors):** after editing YAML, run `pnpm skills:build` and `pnpm skills:check`.
+
+**Apps built from the template:** follow **AGENTS.md** §17 — e.g. `pnpm format && pnpm lint && pnpm test && pnpm build`; smoke with dev server and `/api/health` when configuration allows.
diff --git a/skills/registry.json b/skills/registry.json
index 99f9a34..2e41575 100644
--- a/skills/registry.json
+++ b/skills/registry.json
@@ -7,7 +7,7 @@
       "summary": "Use when scaffolding a new TanStack Start project, adding domain entities to the fullstack template, or implementing the interface-first repository pattern with AI-promptable tools, or nested layout routes duplicate beforeLoad checks or loaders that should live on a parent route, or TanStack Router, Start, or AI behavior must be verified against current documentation instead of training data.",
       "projectName": "TanStack AI-Promptable Full-Stack Template",
       "projectSummary": "A production-ready TanStack Start template designed to make internal tools AI promptable by default.",
-      "version": "1.11.0",
+      "version": "1.16.0",
       "author": {
         "name": "Carlos Martin-Sanchez",
         "url": "https://github.com/carlosvin"
@@ -49,26 +49,18 @@
         "ai-promptable"
       ],
       "capabilities": [
-        "AI promptable application architecture",
-        "Promptable-by-default AI chat in a side drawer when credentials are present",
-        "Natural language querying through repository-backed AI tools",
-        "URL-aware AI prompt context using current location and route patterns",
-        "Swappable service implementations behind stable interfaces",
-        "Layer-specific schemas with explicit mapping between repository and tool contracts",
-        "Thin routes with extracted, testable page components",
-        "Structured server-side logging with pino and automatic Sentry error forwarding",
-        "Build-time semver version injected into observability tools for release tracking",
-        "Public runtime config exposed to the browser via window.__ENV__ without relying on import.meta.env",
-        "Consistent router UX defaults for preload, stale time, and scroll restoration",
-        "Distinct-value filter discovery tools that ground AI filter values in real data",
-        "Single markdown artifact backing the help page, an AI tool, and the chat's recommended-prompt list",
-        "Parent layout routes that centralize beforeLoad guards and shared loader data for nested child routes",
-        "Dynamic route schema extraction for AI tool-calling and context awareness",
-        "Schema metadata and framework introspection used as the primary source for AI-facing field, route, and filter explanations",
-        "Optional computed-field explanation registries only for virtual values that schemas cannot describe",
-        "Upstream-source overlay repositories with sparse user-owned overrides",
-        "URL-driven bulk edit routes with dirty tracking and batched mutation functions",
-        "TanStack Intent integration for package-specific skill discovery"
+        "Interface-first boundaries with swappable implementations",
+        "Three schema layers with mandatory Schema.parse() at every boundary (tool→repo and repo→tool)",
+        "Strong TypeScript inside the typed flow — inference preserved with satisfies unions exhaustive checks few casts",
+        "Loader-first routes and URL-driven state via validateSearch",
+        "Router config bundle (defaults + project Link wrapper preserving search params)",
+        "Full AI tool coverage mirroring repository surface + client navigate/invalidate tools",
+        "Schema-first AI/UI metadata (.describe + optional .meta for unit/format/title)",
+        "Promptable by default — getAIAvailability gating + browserContext + bounded agent loop",
+        "Auth ticket built in middleware via repository + TraceabilityContext on writes",
+        "Parent layout routes deduplicating shared beforeLoad and loaders",
+        "Optional patterns — overlay repo, bulk edit, distinct-values tools, dynamic route introspection",
+        "TanStack Intent + CLI as doc-aligned guidance (not duplicated command manuals)"
       ],
       "triggers": [
         "fullstack template",
@@ -93,51 +85,31 @@
       ],
       "constraints": [
         "External services are accessed through interfaces only",
-        "Domain types come from schemas and inferred types",
-        "Repository and tools use separate schemas with explicit mapping between layers",
-        "AI and UI consume tools-layer schemas only, never repository schemas directly",
-        "Route data fetching is done in loaders, not effects",
-        "Mutations use invalidation middleware; handlers return data or throw, callers normalize errors",
-        "Route files are thin; page components are extracted into src/components/ for testability",
-        "AI chat is conditionally enabled based on adapter configuration at the root loader level",
-        "Server-side logging uses pino; console.* is not used in server code",
-        "App version is extracted from package.json at build time and injected into all observability tools",
-        "Dependencies are kept at latest compatible versions; exact pins are avoided unless a known incompatibility exists",
-        "Non-secret runtime config is exposed via a GET server function and inlined into the document as window.__ENV__ before client JS runs",
-        "Internal navigation uses a project-local Link wrapper that preserves search params by default and renders using the chosen component library's elements",
-        "Shared route gates and expensive reads are implemented on the parent layout route (beforeLoad + loader); child routes avoid duplicating the same work",
-        "TanStack Router, Start, Query, Table, and AI guidance follows the official docs. Always leverage the CLI via `npx @tanstack/cli --help` to check the current docs, rather than relying on memorized APIs.",
-        "Actively ask the skill user for clarifications when needed, especially when making choices about movable pieces or architectural decisions.",
-        "Every enum-ish field exposes a distinct-values AI tool so the assistant grounds filter arguments in real data",
-        "Router configures defaultStaleTime, defaultPreload, defaultPreloadStaleTime, scrollRestoration, and a root notFoundComponent",
-        "Reduce the usage of \"use client\". Rely on Server Components by default. Only use \"use client\" when state, effects, or browser APIs are strictly necessary.",
-        "Prefer schema metadata and introspection over hand-maintained AI metadata. Use Zod/ArkType `.describe()`, route `validateSearch`, tool schemas, router `staticData`, and JSON Schema output wherever possible",
-        "Hand-maintained virtual-field registries are a fallback only for computed fields whose semantics cannot be inferred from schemas",
-        "Request context is a single flat value carried by TanStack middleware. Avoid custom nested `context.context`-style wrappers; destructure `ctx.context` early in handlers",
-        "Avoid unnecessary packages. Add dependencies only when required by the chosen stack, requested capability, or validation contract; when needed, use the latest stable compatible release through the package manager",
-        "Use TanStack Intent and CLI as executable guidance; do not add them as project dependencies unless a generated app explicitly needs them as part of its own tooling",
-        "Generated apps must be validated locally by starting dev mode and pinging `/api/health` when required environment configuration is available"
+        "Domain wire shapes come from Zod/ArkType schemas and z.infer<>; repository interfaces use repository-layer types only",
+        "Tools-layer schemas shared by createServerFn and AI tools; repository interfaces use repository-layer types only; UI and AI never import repository schemas",
+        "Map inbound with RepoInputSchema.parse(fromTools(...)) and outbound with ToolsOutputSchema.parse(fromRepo(...)) so wire shapes never bypass validation",
+        "After parsing keep inferred types end-to-end — avoid any widening to Record string unknown and avoid as except documented third-party boundaries prefer satisfies discriminated unions const tuples narrow guards exhaustive never",
+        "Fetch route data in loaders through server functions; keep route files thin; URL state in validateSearch with loaderDeps",
+        "POST mutations chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`; handlers throw HttpError; callers normalize via processResponse / safeToolHandler / createSafeServerTool",
+        "Expose every repository method as a safe AI tool; distinct-values tools for enum-ish filters",
+        "Use .describe() for human-readable schema text; use .meta() only for structured extras (unit, format, title, …); closed vocabularies via const tuple + z.enum + z.infer<>",
+        "Prefer schema and router introspection over hand-maintained AI manifests; use z.toJSONSchema when exporting metadata to UI",
+        "Shared route gates and expensive reads live on the parent layout route; use a project Link that preserves search params by default",
+        "Router defaults bundle — defaultStaleTime, defaultPreload 'intent', defaultPreloadStaleTime 0, scrollRestoration, notFoundComponent — ship together",
+        "Auth middleware enriches ctx.context with a repository-built ticket (e.g. getReadRepository().getUserAccess(email)); WritableRepository writes accept a TraceabilityContext built from that ticket",
+        "Promptable by default — root loader checks getAIAvailability(); chat input includes browserContext (timezone, locale, path); chat() uses agentLoopStrategy maxIterations(N)",
+        "Verify TanStack Router/Start/AI APIs with npx @tanstack/cli against current docs; use TanStack Intent for package skills — do not add them as project deps unless the app needs them as tooling",
+        "Operational detail — UI library, chat drawer, logging, Sentry, testing, env bridge — follows repo AGENTS.md"
       ],
       "steps": [
-        "Define schemas as source of truth and infer types",
-        "Split schemas by layer: repository input/output schemas and tool-facing schemas",
-        "Define repository interfaces and provide seed + real implementations",
-        "Map repository inputs/outputs to tool schemas at the tools boundary",
-        "Add server functions with GET query and POST mutation conventions",
-        "Register auth + invalidation middleware",
-        "Ask the user which LLM provider they want and install the matching TanStack AI adapter",
-        "Ask the user about their domain and generate a tailored system prompt for chat.ts",
-        "Expose every repository method (reads and writes) as safe AI tools",
-        "Expose a distinct-values server function and AI tool for every enum-ish field",
-        "Wire a public env bridge (GET server function + window.__ENV__ script tag) for non-secret runtime config",
-        "Configure consistent router UX defaults and a root notFoundComponent",
-        "Use a project-local Link wrapper that preserves search by default",
-        "Back the help page, an AI help tool, and the chat's recommended-prompt list from one markdown file",
-        "Keep route state in URL search params with validateSearch",
-        "Model nested URLs with parent layout routes so beforeLoad and shared loaders run once per navigation; children read parent loader data via getRouteApi or useLoaderData from the parent path",
-        "Prefer schema/router introspection over static hand-maintained AI route and field manifests",
-        "For upstream-owned data, model source rows plus sparse override documents and merge them with a pure overlay function",
-        "For bulk edits, store selected IDs in URL search params and persist only changed fields through a batched mutation"
+        "Define repository-layer and tools-layer schemas; implement repository interfaces (seed + production)",
+        "Map between layers with Schema.parse() at boundaries; carry z.infer types through handlers UI tools without erasing to any or untyped records",
+        "Add GET/POST server functions with shared tools-layer input validators",
+        "Register global middleware — auth (enrich ctx.context with a repository-built ticket), invalidation; optional pre-auth redirects",
+        "Configure router defaults bundle and project Link wrapper; add routes with validateSearch, loaderDeps, loaders; nest shared work on parent layouts",
+        "Wire AI — toolDefinition for every server function, safe handlers, client navigate/invalidate tools, buildSystemPrompt fed by the auth ticket and the chat browserContext, agentLoopStrategy maxIterations(N) on chat()",
+        "Gate chat UI on getAIAvailability() in the root loader; add distinct-values read paths for enum-ish filters when applicable",
+        "Validate changes per AGENTS.md; use TanStack CLI/Intent when changing Router/Start/AI behavior"
       ],
       "examples": [
         {
diff --git a/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml b/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
index 1907cfa..f528ac1 100644
--- a/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
+++ b/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
@@ -11,7 +11,7 @@ projectName: TanStack AI-Promptable Full-Stack Template
 projectSummary: >-
   A production-ready TanStack Start template designed to make internal tools AI
   promptable by default.
-version: 1.11.0
+version: 1.16.0
 author:
   name: Carlos Martin-Sanchez
   url: https://github.com/carlosvin
@@ -44,36 +44,18 @@ tags:
   - repository-pattern
   - ai-promptable
 capabilities:
-  - AI promptable application architecture
-  - Promptable-by-default AI chat in a side drawer when credentials are present
-  - Natural language querying through repository-backed AI tools
-  - URL-aware AI prompt context using current location and route patterns
-  - Swappable service implementations behind stable interfaces
-  - Layer-specific schemas with explicit mapping between repository and tool
-    contracts
-  - Thin routes with extracted, testable page components
-  - Structured server-side logging with pino and automatic Sentry error
-    forwarding
-  - Build-time semver version injected into observability tools for release
-    tracking
-  - Public runtime config exposed to the browser via window.__ENV__ without
-    relying on import.meta.env
-  - Consistent router UX defaults for preload, stale time, and scroll restoration
-  - Distinct-value filter discovery tools that ground AI filter values in real
-    data
-  - Single markdown artifact backing the help page, an AI tool, and the chat's
-    recommended-prompt list
-  - Parent layout routes that centralize beforeLoad guards and shared loader
-    data for nested child routes
-  - Dynamic route schema extraction for AI tool-calling and context awareness
-  - Schema metadata and framework introspection used as the primary source for
-    AI-facing field, route, and filter explanations
-  - Optional computed-field explanation registries only for virtual values that
-    schemas cannot describe
-  - Upstream-source overlay repositories with sparse user-owned overrides
-  - URL-driven bulk edit routes with dirty tracking and batched mutation
-    functions
-  - TanStack Intent integration for package-specific skill discovery
+  - Interface-first boundaries with swappable implementations
+  - Three schema layers with mandatory Schema.parse() at every boundary (tool→repo and repo→tool)
+  - Strong TypeScript inside the typed flow — inference preserved with satisfies unions exhaustive checks few casts
+  - Loader-first routes and URL-driven state via validateSearch
+  - Router config bundle (defaults + project Link wrapper preserving search params)
+  - Full AI tool coverage mirroring repository surface + client navigate/invalidate tools
+  - Schema-first AI/UI metadata (.describe + optional .meta for unit/format/title)
+  - Promptable by default — getAIAvailability gating + browserContext + bounded agent loop
+  - Auth ticket built in middleware via repository + TraceabilityContext on writes
+  - Parent layout routes deduplicating shared beforeLoad and loaders
+  - Optional patterns — overlay repo, bulk edit, distinct-values tools, dynamic route introspection
+  - TanStack Intent + CLI as doc-aligned guidance (not duplicated command manuals)
 triggers:
   - fullstack template
   - TanStack Start project
@@ -94,81 +76,30 @@ outputs:
   - Loader-first routes and URL-driven state conventions
 constraints:
   - External services are accessed through interfaces only
-  - Domain types come from schemas and inferred types
-  - Repository and tools use separate schemas with explicit mapping between
-    layers
-  - AI and UI consume tools-layer schemas only, never repository schemas directly
-  - Route data fetching is done in loaders, not effects
-  - Mutations use invalidation middleware; handlers return data or throw,
-    callers normalize errors
-  - Route files are thin; page components are extracted into src/components/ for
-    testability
-  - AI chat is conditionally enabled based on adapter configuration at the root
-    loader level
-  - Server-side logging uses pino; console.* is not used in server code
-  - App version is extracted from package.json at build time and injected into
-    all observability tools
-  - Dependencies are kept at latest compatible versions; exact pins are avoided
-    unless a known incompatibility exists
-  - Non-secret runtime config is exposed via a GET server function and inlined
-    into the document as window.__ENV__ before client JS runs
-  - Internal navigation uses a project-local Link wrapper that preserves search
-    params by default and renders using the chosen component library's elements
-  - Shared route gates and expensive reads are implemented on the parent layout
-    route (beforeLoad + loader); child routes avoid duplicating the same work
-  - TanStack Router, Start, Query, Table, and AI guidance follows the official
-    docs. Always leverage the CLI via `npx @tanstack/cli --help` to check the current docs, rather than relying on memorized APIs.
-  - Actively ask the skill user for clarifications when needed, especially when making choices about movable pieces or architectural decisions.
-  - Every enum-ish field exposes a distinct-values AI tool so the assistant
-    grounds filter arguments in real data
-  - Router configures defaultStaleTime, defaultPreload, defaultPreloadStaleTime,
-    scrollRestoration, and a root notFoundComponent
-  - Reduce the usage of "use client". Rely on Server Components by default. Only use "use client" when state, effects, or browser APIs are strictly necessary.
-  - Prefer schema metadata and introspection over hand-maintained AI metadata.
-    Use Zod/ArkType `.describe()`, route `validateSearch`, tool schemas, router
-    `staticData`, and JSON Schema output wherever possible
-  - Hand-maintained virtual-field registries are a fallback only for computed
-    fields whose semantics cannot be inferred from schemas
-  - Request context is a single flat value carried by TanStack middleware.
-    Avoid custom nested `context.context`-style wrappers; destructure
-    `ctx.context` early in handlers
-  - Avoid unnecessary packages. Add dependencies only when required by the chosen
-    stack, requested capability, or validation contract; when needed, use the
-    latest stable compatible release through the package manager
-  - Use TanStack Intent and CLI as executable guidance; do not add them as project
-    dependencies unless a generated app explicitly needs them as part of its own tooling
-  - Generated apps must be validated locally by starting dev mode and pinging
-    `/api/health` when required environment configuration is available
+  - Domain wire shapes come from Zod/ArkType schemas and z.infer<>; repository interfaces use repository-layer types only
+  - Tools-layer schemas shared by createServerFn and AI tools; repository interfaces use repository-layer types only; UI and AI never import repository schemas
+  - Map inbound with RepoInputSchema.parse(fromTools(...)) and outbound with ToolsOutputSchema.parse(fromRepo(...)) so wire shapes never bypass validation
+  - After parsing keep inferred types end-to-end — avoid any widening to Record string unknown and avoid as except documented third-party boundaries prefer satisfies discriminated unions const tuples narrow guards exhaustive never
+  - Fetch route data in loaders through server functions; keep route files thin; URL state in validateSearch with loaderDeps
+  - "POST mutations chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`; handlers throw HttpError; callers normalize via processResponse / safeToolHandler / createSafeServerTool"
+  - Expose every repository method as a safe AI tool; distinct-values tools for enum-ish filters
+  - Use .describe() for human-readable schema text; use .meta() only for structured extras (unit, format, title, …); closed vocabularies via const tuple + z.enum + z.infer<>
+  - Prefer schema and router introspection over hand-maintained AI manifests; use z.toJSONSchema when exporting metadata to UI
+  - Shared route gates and expensive reads live on the parent layout route; use a project Link that preserves search params by default
+  - "Router defaults bundle — defaultStaleTime, defaultPreload 'intent', defaultPreloadStaleTime 0, scrollRestoration, notFoundComponent — ship together"
+  - Auth middleware enriches ctx.context with a repository-built ticket (e.g. getReadRepository().getUserAccess(email)); WritableRepository writes accept a TraceabilityContext built from that ticket
+  - "Promptable by default — root loader checks getAIAvailability(); chat input includes browserContext (timezone, locale, path); chat() uses agentLoopStrategy maxIterations(N)"
+  - Verify TanStack Router/Start/AI APIs with npx @tanstack/cli against current docs; use TanStack Intent for package skills — do not add them as project deps unless the app needs them as tooling
+  - Operational detail — UI library, chat drawer, logging, Sentry, testing, env bridge — follows repo AGENTS.md
 steps:
-  - Define schemas as source of truth and infer types
-  - "Split schemas by layer: repository input/output schemas and tool-facing
-    schemas"
-  - Define repository interfaces and provide seed + real implementations
-  - Map repository inputs/outputs to tool schemas at the tools boundary
-  - Add server functions with GET query and POST mutation conventions
-  - Register auth + invalidation middleware
-  - Ask the user which LLM provider they want and install the matching TanStack
-    AI adapter
-  - Ask the user about their domain and generate a tailored system prompt for
-    chat.ts
-  - Expose every repository method (reads and writes) as safe AI tools
-  - Expose a distinct-values server function and AI tool for every enum-ish field
-  - Wire a public env bridge (GET server function + window.__ENV__ script tag)
-    for non-secret runtime config
-  - Configure consistent router UX defaults and a root notFoundComponent
-  - Use a project-local Link wrapper that preserves search by default
-  - Back the help page, an AI help tool, and the chat's recommended-prompt list
-    from one markdown file
-  - Keep route state in URL search params with validateSearch
-  - Model nested URLs with parent layout routes so beforeLoad and shared loaders
-    run once per navigation; children read parent loader data via getRouteApi or
-    useLoaderData from the parent path
-  - Prefer schema/router introspection over static hand-maintained AI route and
-    field manifests
-  - For upstream-owned data, model source rows plus sparse override documents and
-    merge them with a pure overlay function
-  - For bulk edits, store selected IDs in URL search params and persist only
-    changed fields through a batched mutation
+  - Define repository-layer and tools-layer schemas; implement repository interfaces (seed + production)
+  - Map between layers with Schema.parse() at boundaries; carry z.infer types through handlers UI tools without erasing to any or untyped records
+  - Add GET/POST server functions with shared tools-layer input validators
+  - Register global middleware — auth (enrich ctx.context with a repository-built ticket), invalidation; optional pre-auth redirects
+  - Configure router defaults bundle and project Link wrapper; add routes with validateSearch, loaderDeps, loaders; nest shared work on parent layouts
+  - Wire AI — toolDefinition for every server function, safe handlers, client navigate/invalidate tools, buildSystemPrompt fed by the auth ticket and the chat browserContext, agentLoopStrategy maxIterations(N) on chat()
+  - Gate chat UI on getAIAvailability() in the root loader; add distinct-values read paths for enum-ish filters when applicable
+  - Validate changes per AGENTS.md; use TanStack CLI/Intent when changing Router/Start/AI behavior
 examples:
   - input: Add a new domain entity to the template
     output: Update schema, repository interfaces, server functions, routes, and AI
@@ -178,82 +109,86 @@ examples:
 content: |
   # TanStack Fullstack Pattern
 
-  An interface-first fullstack architecture built on TanStack Start. The pattern defines clear interface boundaries between layers -- interfaces are rigid, implementations are swappable.
-
-  > **Companion documentation:** In repositories built from this template, [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) holds the project handbook -- file structure, chosen UI-library styling, auth snippets, Biome, testing/E2E commands, and the full validation checklist. This skill focuses on the architectural contract; refer to AGENTS.md for operational detail.
-
-  ## Pattern Overview
-
-  - Zero-config development with seed implementations and swappable service layers
-  - AI promptability by exposing every repository method (reads and writes) as tools
-  - End-to-end type safety from schema-first definitions with explicit layer boundaries
-
-  ## Rigid Rules (Must Follow)
-
-  1. Interface-first services: every external service (database, AI, observability) is accessed through an interface.
-  2. End-to-end type safety via schemas: every boundary uses a Zod/ArkType schema as the type source (`z.infer<>`). Never hand-write `type` for wire data. Service interfaces (`ReadRepository`, `AIAdapterService`, etc.) are hand-written contracts -- they define behaviour, not wire shapes. Prefer schema metadata and introspection (`.describe()`, route `validateSearch`, tool schemas, router `staticData`, JSON Schema output) over hand-maintained AI metadata.
-  3. Three schema layers: repository (DB-shaped), server-function / AI-tool (API-shaped, shared), router search-param (URL-shaped). Mappers translate between layers.
-  4. Repository contracts use repository-layer schemas only.
-  5. Server functions and AI tools share the same tools-layer schemas (`.inputValidator(Schema)` / `toolDefinition({ inputSchema })`). Both parse with `Schema.parse(args)`.
-  6. AI and UI interact only with tools-layer schemas; they must not depend directly on repository schemas.
-  7. Loaders-first data fetching: fetch route data in loaders through server functions.
-  8. URL-as-state: filters, tabs, selections live in URL search params via `validateSearch` (Zod/ArkType). Use `loaderDeps` to feed validated search into loaders.
-  9. Middleware chain: auth is global middleware, invalidation runs on mutation server functions.
-  10. Mutation pattern: POST server functions chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`, return domain data or throw `HttpError`. Callers normalize errors: UI via `processResponse()`, AI tools via `safeToolHandler()` / `createSafeServerTool()`.
-  11. Query pattern: GET server functions throw on failure for centralized error handling. When possible, use static server functions for performance improvements.
-  12. Maximize AI tool coverage: expose **every** repository method (reads and writes) via `createSafeServerTool()` so failures return `{ error, code }`. If a server function exists, it gets a tool.
-  13. Router capabilities as AI client tools: expose `router.navigate()` and `router.invalidate()` as client tools via `toolDefinition()`.
-  14. AI system prompt context: `buildSystemPrompt()` injects context into every AI chat request from the single request context and the client ticket sent by the chat UI. Keep the request context flat (for example `{ ticket, client }` inside TanStack's `ctx.context`) and destructure it early in handlers; do not introduce nested custom context wrappers. Include current user, browser context, and current location. Derive route patterns and search params from live router/schema metadata where possible instead of maintaining static route tables.
-  15. JSDoc on exports: every exported function, interface, type, and constant gets a JSDoc comment stating *what* and *why*.
-  16. AI chat drawer: render the AI chat in the chosen UI library's right-side drawer/panel component mounted at the root layout level so messages persist across navigation. The template's default is a Mantine `Drawer` (`position="right"`, `size="lg"`), but generated apps may swap the component library when the user chooses a different stack.
-  17. AI renders rich markdown: use `react-markdown` + `remark-gfm` for assistant messages. Tables/code are styled through the chat markdown container using the chosen design system's theme tokens or CSS variables. Internal links render as TanStack Router `Link` with `preload="intent"` (client-side navigation without losing chat). External links open in a new tab. The AI uses markdown links in replies (e.g. `[Pending tasks](/tasks?status=pending)`).
-  18. Thin routes: route files contain only route config (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`). Page UI lives in `src/components/PageName/PageName.tsx`.
-  19. Promptable by default: check AI availability at the root loader level via `getAIAvailability()`. Only render the chat trigger and drawer when AI is configured — no disabled-state fallback.
-  20. Icon library: use `lucide-react` as the default icon library. Keep one icon library per project for visual consistency.
-  21. Structured logging: use `pino` for all server-side logging instead of `console.*`. Configure `@sentry/pino-transport` so error-level logs are automatically forwarded to Sentry when `VITE_SENTRY_DSN` is set. The logger singleton lives in `src/services/logger.ts`.
-  22. Build-time app version: extract the semver version from `package.json` at build time via Vite `define` and expose it as `__APP_VERSION__`. Inject it into Sentry (`release`), the pino logger (`version` field), and any other observability tool.
-  23. Dependency discipline: avoid installing unnecessary packages. Prefer existing project dependencies and platform APIs. When a package is truly required by the chosen stack, requested capability, or validation contract, use the latest stable compatible version via the package manager (`pnpm add <pkg>` with no guessed version suffix unless a known incompatibility requires a pin); run `pnpm outdated` and `pnpm update` to align the lockfile.
-  24. Ask for LLM provider: when scaffolding a new project or when the user's LLM preference is unclear, ask which provider they want before writing the adapter. Install only the chosen `@tanstack/ai-*` adapter package and configure matching env vars. Default is `@tanstack/ai-openai`; do not assume OpenAI without asking. See AGENTS.md section 8 for the full provider table.
-  25. Generate the system prompt: when scaffolding a new app, ask the user about their domain — entities, capabilities, and permissions — then generate a tailored `BASE_SYSTEM_PROMPT` in `src/routes/api/chat.ts` with six sections (Capabilities, Data Model, Links and navigation, Mutations and data refresh, Permissions and errors, Guidelines). Do not reuse the template's task-management prompt. `buildSystemPrompt()` composes this base with dynamic context (rule 14) and the navigation manifest. `chat()` from `@tanstack/ai` receives it via `systemPrompts: string[]`. See AGENTS.md section 8 "System Prompt Generation" for the full template.
-  26. Repository-resolved authorization: auth middleware extracts JWT claims **and** calls a repository method (e.g. `getReadRepository().getUserAccess(email)`) to enrich the request context with application-defined access data — roles, group memberships, owned scopes, superuser flags. Prefer a flat access-ticket object with identity, roles, UI-safe predicates, and throwing server guards. Downstream server functions and AI tools read this one ticket so UI and AI see the same permission signals. Authorization checks live **inside** server-function handlers (not only in UI components), so permissions are enforced regardless of caller.
-  27. Write attribution via traceability context: `WritableRepository` methods accept an optional `TraceabilityContext` (`createdBy`, `createdDate`, `lastModifiedBy`, `lastModifiedDate`) built from the authenticated identity. Mutation server-function handlers construct it from the request ticket (for example, `ticket.email`) and pass it to the repository. Seed and production implementations apply it consistently. This gives UI and AI callers the same audit trail without duplicating logic at each call site.
-  28. Explicit agent loop depth: configure `agentLoopStrategy: maxIterations(N)` explicitly on the `chat()` call (default N=10). This caps the number of consecutive tool-calling iterations the AI can run before returning a final answer, which bounds latency, cost, and infinite-loop risk. Tune N only after measuring; do not rely on the framework default.
-  29. Public runtime config bridge: expose non-secret runtime config (Sentry DSN, environment name, feature flags) via a GET server function `getPublicEnv()` and inline the result as `window.__ENV__` in the root `RootDocument` using a small `<script>` tag emitted before client JS runs. Escape `<` in the inlined JSON to avoid breaking the HTML parser. Never rely on `import.meta.env` alone for values that must differ across runtime environments built from the same bundle. See AGENTS.md section "Public Runtime Config" for the template.
-  30. Router UX defaults bundle: in `src/router.tsx`, configure `defaultStaleTime` (long for read-heavy dashboards, short for mutation-heavy apps), `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0` (always-fresh preloads), `scrollRestoration: true` (with a `getScrollRestorationKey` when needed), and a `notFoundComponent` on the root route. These defaults are a single coherent bundle — do not ship a router config without them.
-  31. Link wrapper preserves search & styling: export a project-local `Link` component (e.g. `src/components/Link/Link.tsx`) that wraps TanStack Router's `Link` with `search: true` as the default. Use this wrapper for every internal link so filters, tabs, and other URL state never silently drop on navigation. Ensure that links are still rendered using the chosen component library's corresponding element (e.g., using `createLink` or the `component` prop) so they inherit the correct styling. Reserve raw `<a>` for external URLs.
-  32. Parent layout routes deduplicate subtree work: when several child routes under the same URL prefix need the same redirect, synchronous guard, or expensive read, implement it **once** on the **parent** layout route. Use the parent's `beforeLoad` for navigation gates and synchronous checks; use the parent's `loader` (still via server functions) for shared data that every descendant needs. Child loaders fetch **only** data specific to that segment. Descendants read parent loader output with `getRouteApi('/parent/path').useLoaderData()` or `useLoaderData({ from: '/parent/path' })` — do not copy the parent's `beforeLoad` or re-fetch the parent's loader payload in each child. Structure files to match TanStack Router's layout conventions (e.g. `routes/foo/route.tsx` wrapping `routes/foo/*`).
-  33. Sentry user context + feedback: when Sentry is enabled, bind the signed-in user via `Sentry.setUser({ email, username })` from the shell component as soon as the identity loads (no extra round-trip).
-  34. Single markdown artifact for help + AI + suggested prompts: maintain one `docs/help.md` imported with `?raw`. Back three surfaces from it: (a) a `/help` route that renders it with `react-markdown`; (b) an AI tool that returns the content so the assistant can answer "how do I..." questions; (c) a parser that extracts `- [ ]` / `- [x]` lines as the chat's recommended-question list. Zero duplication between docs, assistant, and suggested prompts.
-  35. Distinct-value filter discovery: for every enum-ish field, the repository exposes a `getDistinctValues(field)` method that flows through a GET server function into a read-only AI tool (`getDistinctStatuses`, `getDistinctCategories`, …). The AI calls these to ground filter values in real data instead of guessing. The root loader can preload the same lists for UI filter bars so UI and AI share one vocabulary.
-  36. Reduce `"use client"` usage: TanStack Start supports full SSR and React Server Components. Rely on Server Components by default. Only use `"use client"` when state (`useState`), effects (`useEffect`), or browser APIs are strictly necessary. Keep client components small and at the leaf level.
-  37. Computed-field explanation fallback: for virtual fields whose semantics cannot be inferred from schema metadata (for example derived status, health, disposition, rollup, or permission fields), keep a small explanation registry next to the computation logic and expose an `explainField(fieldName)` AI tool. Do not duplicate explanations for fields already described by schemas.
-  38. Overlay repository pattern: when upstream systems own base data and users need local annotations, keep a read-only source collection plus a sparse overrides collection. Reads merge both through a pure `applyOverrides(source, override)` function; writes target only overrides and use explicit null/unset semantics to revert to source values.
-  39. URL-driven bulk edit pattern: store selected IDs and edit-category state in validated URL search params, keep dirty tracking local to the edit page, submit only changed fields, authorize per row, persist via a batched mutation, and clear stale selections when closing nested modal/detail routes.
-  40. Pre-auth redirect middleware: for renamed routes or legacy URL schemes, add a narrow middleware before auth that returns a relative `308 Permanent Redirect`. This prevents old links from producing misleading 401s. Keep the allowlist small and retire entries once upstream links migrate.
+  **Purpose:** Capture the **interface-first, schema-layered, AI-promptable** contract for TanStack Start apps from this template. Day-to-day conventions (UI kit, chat wiring, logging, tests) live in the repo’s **AGENTS.md** — use this skill for **architecture**, AGENTS.md for **operations**.
+
+  > **Companion handbook:** [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) — structure, styling, auth snippets, Biome, testing/E2E, validation checklist, AI chat setup.
+
+  ## Core Contract
+
+  1. **Interfaces:** Database, AI, observability (and other externals) sit behind interfaces; implementations are swappable.
+  2. **Schemas as the type source:** Wire and tool shapes use Zod/ArkType + `z.infer<>`. Hand-written interfaces define **behavior** (`ReadRepository`, `AIAdapterService`, …), not ad-hoc JSON types.
+  3. **Three schema layers:** **Repository** (DB-shaped), **tools / server-fn** (API-shaped, shared between `createServerFn` and `toolDefinition`), **router search** (URL-shaped). Translate with `Schema.parse()` at each boundary.
+  4. **TypeScript inside the typed flow:** After schema boundaries, preserve **inferred types end-to-end** — prefer `satisfies`, discriminated unions, `as const` tuples, narrow **type guards**, and **exhaustive `switch`** (e.g. `default` branch calling `assertNever`) over `any`, broad `unknown` plumbing, or `as` casts (only use `as` at documented third-party/library seams per AGENTS.md).
+  5. **Repository vs tools:** Repository implementations use repository-layer schemas only. **Server functions and AI tools share the same tools-layer schemas** (`.inputValidator` / `toolDefinition` inputSchema + `Schema.parse`). UI and AI consume tools-layer types only — never import repository schemas at those edges.
+  6. **Server functions:** GET queries throw on failure; POST mutations chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`; handlers return data or throw `HttpError`; callers normalize with `processResponse` / `safeToolHandler` / `createSafeServerTool`.
+  7. **Routes:** Thin route files (`createFileRoute`, `validateSearch`, `loaderDeps`, `loader`, `component`); page UI in `src/components/`. **Loaders** fetch via server functions — no `useEffect` data fetching for route data.
+  8. **URL-as-state:** Filters, tabs, selections in validated **search** params; use `loaderDeps` so only relevant search fields key the loader cache.
+  9. **Router config bundle:** ship a project-local `Link` wrapper with `search: true` default (use it for every internal link) **and** these router defaults together: `defaultStaleTime`, `defaultPreload: 'intent'`, `defaultPreloadStaleTime: 0`, `scrollRestoration: true`, `notFoundComponent`.
+  10. **Auth ticket built in middleware:** auth middleware enriches `ctx.context` with a repository-built ticket (e.g. `getReadRepository().getUserAccess(email)`) carrying identity, roles, and guards; `WritableRepository` mutations accept a `TraceabilityContext` (`createdBy`, `lastModifiedBy`, …) constructed from that ticket so writes are attributed consistently across UI and AI.
+  11. **AI tool coverage:** expose **every** repository method as a server AI tool via `createSafeServerTool`; add **distinct-values** tools for enum-ish filters; expose `navigate` and `invalidateRouter` as client tools.
+  12. **Promptable by default:** root loader checks `getAIAvailability()` and only mounts chat UI when configured (no disabled state). Chat input includes a `browserContext` (timezone, locale, path) consumed by `buildSystemPrompt` alongside the auth ticket.
+  13. **Bound the agent loop:** every `chat()` call sets `agentLoopStrategy: maxIterations(N)` explicitly (default `N=10`); tune after measuring — do not rely on the framework default.
+  14. **Metadata for AI and UI:** Use `.describe()` for all narrative explanations (JSON Schema `description`). Use `.meta({ ... })` only for **structured extras** — `unit`, `format`, optional `title`, app-specific hints — not as a substitute for `.describe()`. Prefer deriving prompts and UI copy from schemas + `z.toJSONSchema()` and router introspection over parallel hand-maintained maps.
+  15. **Parent layouts:** Shared `beforeLoad`, redirects, and expensive reads belong on the **parent** layout route; children read parent loader data via `getRouteApi` / `useLoaderData({ from })` — do not duplicate parent work.
+
+  Day-to-day operational concerns (UI kit, chat drawer placement, markdown rendering, LLM provider choice, pino/Sentry, icons, RSC vs `"use client"`, full validation commands) follow **AGENTS.md** — see the handbook table below.
+
+  ## Architecture Checklist
+
+  Scan before changing code:
+
+  - **One tools-layer schema per wire shape:** `createServerFn` `.inputValidator(Schema)` and AI `toolDefinition({ inputSchema })` share the same schema — no duplicate hand-written wire types.
+  - **Parse both directions:** tools → repository inputs and repository rows → tools/API outputs each end in the target layer’s `Schema.parse()` (pure mapper functions are fine if the final step is always `.parse()`).
+  - **No type erasure:** after `Schema.parse`, carry **`z.infer`-derived types** through server functions, repos, tools, and components — do not widen back to `Record<string, unknown>` / `any`.
+  - **Repository interfaces = repo-layer types only:** mapping lives beside schemas / mappers — not in React components.
+  - **Auth ticket is repository-backed and server-enforced:** middleware builds the ticket (e.g. `getReadRepository().getUserAccess(email)`); guards run in **server handlers**, never UI-only.
+  - **Writes use `TraceabilityContext`:** pass audit fields from the ticket through a single context object on `WritableRepository` mutations — avoid sprinkling raw `email` arguments.
+  - **Navigation is one decision:** ship the **router defaults bundle** and the **project `Link` wrapper** (`search: true`) together so URL state survives navigation.
+  - **AI stack is complete:** every repo method → server tool + safe handler; client **`navigate`** / **`invalidateRouter`**; root **`getAIAvailability()`**; chat payload includes **`browserContext`**; **`chat({ agentLoopStrategy: maxIterations(N) })`**.
+  - **Routes:** **`validateSearch`** + **`loaderDeps`**; duplicate **`beforeLoad`** / shared loaders only on **parent** layouts.
+  - **Metadata discipline:** `.describe()` for narrative copy; `.meta()` for structured extras; closed vocabularies = `as const` tuple + `z.enum` + `z.infer<>`.
 
   ## Schema Boundaries
 
-  `Route search schema -> loader -> tools schema -> server fn -> mapping -> repo schema -> repo impl`
+  `Route search schema → loader → tools schema → server fn → mapping → repo schema → repo`
 
-  `repo output -> mapping -> tools schema -> AI or UI`
+  `repo output → mapping → tools schema → AI or UI`
 
-  **Layer 1 — Repository schemas (DB-shaped):** internal to the repository, no `.describe()` needed. Define in `src/services/schemas/repository.ts` (target pattern -- currently all schemas live in `schemas.ts`). Infer types with `z.infer<>`.
+  **Layer 1 — Repository (DB-shaped):** define in `src/services/schemas/repository.ts` (target layout; today some apps still colocate in `schemas.ts`). No `.describe()` required here. Infer with `z.infer<>`.
 
-  **Layer 2 — Server-function / AI-tool schemas (API-shaped):** shared by `createServerFn` and `toolDefinition`. Add `.describe()` on every field -- descriptions flow into JSON Schema for the AI. Use these schema descriptions as the first source for field explanations, filter help, and AI tool guidance before adding any separate metadata file.
+  **Layer 2 — Tools / server functions (API-shaped):** one schema for `.inputValidator(Schema)` and `toolDefinition({ inputSchema })`; parse args with `Schema.parse(args)`.
 
   ```typescript
-  // src/services/schemas/schemas.ts
+  // Example: tools-layer object — .describe() for text; .meta() for non-description fields
   const TaskInputSchema = z.object({
     title: z.string().min(1).describe('Short title'),
     status: TaskStatusSchema.default('pending').describe('Current status'),
-    assignee: z.string().optional().describe('Assignee email'),
+    estimateHours: z
+      .number()
+      .optional()
+      .describe('Estimated effort in hours')
+      .meta({ unit: 'h', format: 'decimal' }),
   })
   ```
 
-  **Layer 3 — Router search-param schemas (URL-shaped):** defined locally in route files via `validateSearch`. Fields are always optional. Introspect these schemas, plus route `staticData`, when building AI navigation catalogs and link/filter guidance.
+  **Closed vocabularies (enums, tool categories, filter buckets):** `const VALUES = [...] as const`, then `z.enum(VALUES)`, put prose in `.describe()`, optional `.meta({ title: '...' })`, infer with `z.infer<>`. **Do not** treat `export const LABELS = { id: 'Display Name' } as const` as the authority for the same strings unless it is derived from or validated by that schema.
+
+  ```typescript
+  const TOOL_CATEGORY_VALUES = ['Metadata & Navigation', 'Strategic Objectives'] as const
+
+  export const ToolCategorySchema = z
+    .enum(TOOL_CATEGORY_VALUES)
+    .describe(
+      'Used in toolDefinition metadata.category; groups tools and documents allowed values for the LLM.',
+    )
+    .meta({ title: 'Tool category' })
+
+  export type ToolCategory = z.infer<typeof ToolCategorySchema>
+  ```
+
+  **Layer 3 — Router search (URL-shaped):** local `validateSearch` schemas; fields are usually optional for partial URLs.
 
   ```typescript
-  // src/routes/tasks/index.tsx
   const TasksSearchSchema = z.object({
     status: z.enum(TASK_STATUSES).optional(),
     priority: z.enum(TASK_PRIORITIES).optional(),
@@ -266,31 +201,80 @@ content: |
   })
   ```
 
-  **Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`). Only add a computed-field explanation registry when the field is virtual and cannot be explained by schema metadata or route/tool introspection.
+  **Boundary mapping (mandatory):** layer switches happen only in mapper functions; **inbound** tool payloads become repo inputs with `RepoLayerSchema.parse(...)`, **outbound** repo documents become tools/API shapes with `ToolsLayerSchema.parse(...)`.
+
+  ```typescript
+  // Inbound — tools-layer → repository-layer before calling the repo
+  function toRepoCreateInput(tool: z.infer<typeof TaskCreateToolSchema>): TaskRepoInput {
+    return TaskRepoInputSchema.parse({
+      title: tool.title,
+      status: tool.status,
+    })
+  }
+
+  // Outbound — repository row → tools-layer response for server fn + AI
+  function toToolTask(row: TaskRepo): z.infer<typeof TaskToolSchema> {
+    return TaskToolSchema.parse({
+      id: row.id,
+      title: row.title,
+      status: row.status,
+    })
+  }
+  ```
+
+  **TypeScript discipline (complements Zod):** Zod validates **at boundaries**; TypeScript keeps the interior honest — narrow with guards instead of casting.
+
+  ```typescript
+  type TaskStatus = 'pending' | 'done'
+
+  const STATUS_LABEL = {
+    pending: 'Pending',
+    done: 'Done',
+  } as const satisfies Record<TaskStatus, string>
+
+  function assertNever(x: never): never {
+    throw new Error(`Unexpected ${String(x)}`)
+  }
+
+  function labelForStatus(status: TaskStatus): string {
+    switch (status) {
+      case 'pending':
+        return STATUS_LABEL.pending
+      case 'done':
+        return STATUS_LABEL.done
+      default:
+        return assertNever(status)
+    }
+  }
+  ```
+
+  **Virtual / computed fields:** If semantics cannot live in schema metadata, keep a small registry next to the derivation and expose `explainField` — do not duplicate fields already described by schemas.
 
   ## Request Context
 
-  TanStack server functions expose middleware data at `ctx.context`; keep the app-owned value inside it flat. A good default is `{ ticket, client }`, where `ticket` carries identity, roles, predicates, and server-side guards, and `client` carries browser/runtime context such as timezone, locale, current path, and viewport.
+  Keep middleware payload at `ctx.context` flat — for example `{ ticket, client }`. **`ticket`** must be **repository-enriched** in middleware (identity, roles, predicates, throwing guards), not just raw JWT claims. Enforce authorization in **server handlers** for every mutation and sensitive read — components may hide buttons, but handlers are authoritative.
 
   ```typescript
-  const updateTask = createServerFn({ method: 'POST' })
-    .handler(async ctx => {
-      const { ticket, client } = ctx.context
-      ticket.requireTaskEditor(ctx.data.taskId)
-      return getWritableRepository().updateTask(ctx.data, {
-        actor: ticket.email,
-        timezone: client.timezone,
-      })
+  const updateTask = createServerFn({ method: 'POST' }).handler(async ctx => {
+    const { ticket } = ctx.context
+    ticket.requireTaskEditor(ctx.data.taskId)
+    const repoPatch = TaskRepoPatchSchema.parse(mapToolUpdateToRepo(ctx.data))
+    return getWritableRepository().updateTask(ctx.data.taskId, repoPatch, {
+      lastModifiedBy: ticket.email,
     })
+  })
   ```
 
-  Avoid custom shapes like `{ context: { user, client } }` inside `ctx.context`; they create redundant nested context and make examples harder to copy correctly.
-
   ## Interface Contracts
 
-  Repository interfaces use repository-layer types only (never tools-layer schemas). `AIAdapterService` and `ObservabilityService` follow the same interface-first pattern -- see their `types.ts` files.
+  Repository interfaces reference **repository-layer types** only. **`WritableRepository`** mutations take an optional **`TraceabilityContext`** built from the auth ticket — not ad-hoc optional email parameters at each call site.
 
   ```typescript
+  interface TraceabilityContext {
+    createdBy?: string
+    lastModifiedBy?: string
+  }
+
   interface ReadRepository {
     getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
     getTask(id: string): Promise<TaskRepoOutput | null>
@@ -298,113 +282,54 @@ content: |
     getUserProfile(email: string): Promise<UserProfile | null>
   }
   interface WritableRepository {
-    createTask(input: TaskRepoInput, createdBy?: string): Promise<TaskRepoOutput>
-    updateTask(id: string, input: Partial<TaskRepoInput>): Promise<TaskRepoOutput | null>
+    createTask(input: TaskRepoInput, trace?: TraceabilityContext): Promise<TaskRepoOutput>
+    updateTask(
+      id: string,
+      input: Partial<TaskRepoInput>,
+      trace?: TraceabilityContext,
+    ): Promise<TaskRepoOutput | null>
     deleteTask(id: string): Promise<boolean>
   }
   ```
 
-  ## Overlay Repositories
-
-  Use this when base records come from an upstream system (warehouse export, spreadsheet, vendor API) but the app needs local user-owned annotations.
-
-  - Keep upstream rows in a read-only source collection.
-  - Keep user edits in a sparse overrides collection with audit metadata.
-  - Reads load source rows and overrides, then merge through a pure `applyOverrides(source, override)` function.
-  - Writes target only the overrides collection; explicit `null`/unset values mean "revert to source".
-  - Unit-test the overlay function because it defines the merged view shown to the UI and AI.
-
-  ## URL-Driven Bulk Editing
-
-  For multi-row edits, use a dedicated edit route such as `/tasks/edit?selected=id1&selected=id2`.
-
-  - Selection lives in validated URL search params, preferably repeated keys.
-  - Edit category/tab state also lives in search params.
-  - Dirty tracking stays local to the edit page and submits only changed cells.
-  - The mutation server function validates each row's permission and persists through one batched write.
-  - Closing nested modal/detail routes clears stale selection search params.
-
-  ## Dynamic AI Metadata
-
-  Prefer live sources over static manifests:
-
-  - Route catalog: derive from `router.flatRoutes`, route `staticData`, path params, and `validateSearch` schemas.
-  - Field/tool metadata: derive from Zod/ArkType `.describe()` and generated JSON Schema.
-  - Help content: keep one markdown artifact for user help, AI help, and suggested prompts when the app needs those surfaces.
-  - System prompt: reserve static prompt text for behavior that cannot be discovered from tools, schemas, route metadata, or docs.
-
-  ## Styling, Auth, and Observability
-
-  These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
-
-  - **UI library** -- see AGENTS.md section 3 for the selected component library's styling rules. The default template uses Mantine, but generated apps may choose another library.
-  - **Auth and Middleware** -- see AGENTS.md section 5 (middleware chain, `AuthContext`, guard helpers, code samples). Rigid rules 9--10 above are the normative summary.
-  - **Observability** -- see AGENTS.md section 9 (interface, Sentry/no-op, swap steps).
+  ## Implementation Flow
 
-  ## Migration / Build Workflow
+  1. **Schemas:** repo + tools layers; mappers with `Schema.parse()`.
+  2. **Repository:** interfaces in `types.ts`; seed + production implementations.
+  3. **Server functions:** `serverFns.ts` — GET queries, POST mutations with shared validators.
+  4. **AI tools:** each server function → `toolDefinition` + `createSafeServerTool`; wire client tools in the chat shell (see AGENTS.md §8).
+  5. **Middleware:** `start.ts` — auth, invalidation, optional pre-auth `308` redirects for legacy paths.
+  6. **Routes:** `validateSearch`, `loaderDeps`, loaders; parent layouts for shared `beforeLoad`/data.
+  7. **Chat:** adapter, `chat()`, `buildSystemPrompt`, tool list — details in AGENTS.md §8.
 
-  1. **Schemas**: repo-layer schemas in `repository.ts`, tools-layer in `schemas.ts` (with `.describe()`), mappers via `Schema.parse()`.
-  2. **Repository**: interfaces in `types.ts` (repo-layer types only), seed + production implementations.
-  3. **Server functions**: GET queries + POST mutations in `serverFns.ts` with `.inputValidator(ToolSchema)`.
-  4. **AI tools**: every server function gets a `toolDefinition` + `createSafeServerTool()`; client tools (`navigate`, `invalidateRouter`) wired in `ChatDrawer.tsx`. Reuse schema metadata for tool descriptions before adding hand-maintained explanatory text.
-  5. **Middleware + route catalog**: register pre-auth redirects (if needed), auth, and invalidation in `start.ts`; derive the AI route catalog from router/schema metadata instead of duplicating route tables.
-  6. **Routes**: `validateSearch` (Zod/ArkType), `loaderDeps`, loaders calling server functions; nest under layout parents when children share `beforeLoad` or loader data (rule 33).
-  7. **Chat + tests**: pass client/browser context to `/api/chat`; E2E specs in `e2e/` against seed repository. For scaffold/setup work, finish by running the app in dev mode and checking `/api/health`.
+  ## Special Patterns (use when the feature applies)
 
-  ## TanStack Intent and CLI Workflow
-  
-  Use `tanstack intent` and `tanstack cli` as executable guidance during development. Do not add them as project dependencies unless the generated app explicitly needs them.
+  - **Overlay repository:** read-only upstream source + sparse user overrides; pure `applyOverrides`; writes only to overrides.
+  - **URL bulk edit:** selection and category tabs in search params; batched mutation; per-row auth.
+  - **Help surface:** single `docs/help.md` can back `/help`, an AI tool, and suggested prompts (see AGENTS.md).
+  - **Distinct values:** `getDistinctValues` → GET server fn → read-only AI tool so filters match real data.
+  - **Dynamic AI navigation:** derive route/help context from `router.flatRoutes` + `validateSearch` introspection where possible.
 
-  ### TanStack Intent (Package Skills)
-  Intent answers "which version-matched package skill should the agent follow?"
-  - Setup: Run `npx @tanstack/intent@latest install` when configuring agent instructions in a generated app.
-  - Discover: Before substantial TanStack work, run `npx @tanstack/intent@latest list` or use skills already listed in context.
-  - Load: Load a matching package skill with `npx @tanstack/intent@latest load <package>#<skill>` and follow the returned `SKILL.md`.
-  - Check staleness: Use `npx @tanstack/intent@latest stale` to detect outdated source documentation references.
+  ## TanStack Intent, CLI, and AI
 
-  ### TanStack CLI
-  CLI docs search answers "what do the current TanStack docs say about this API or pattern?"
-  - The CLI provides docs search, MCP support, modular integrations, Builder, and deployment/scaffold support.
-  - See `npx @tanstack/cli --help` for available commands.
+  - **Intent:** `npx @tanstack/intent@latest list | load <pkg>#<skill> | stale` — pick version-matched package skills before deep TanStack work.
+  - **CLI (prefer current docs over memory):** `npx @tanstack/cli --help` → `libraries`, `search-docs "<query>" --library router|start|ai`, `doc <library> <path>`.
+  - **AI stack:** `@tanstack/ai`, `@tanstack/ai-react`, `/api/chat` — provider table, SSE wiring, system prompt sections, and chat endpoint anatomy are spelled out in **AGENTS.md §8**.
 
-  ## TanStack documentation (official CLI)
+  ## Use the handbook (AGENTS.md)
 
-  Prefer **current** TanStack guidance over training-data recall. The TanStack team ships a CLI that mirrors the docs site.
-
-  - Run `npx @tanstack/cli --help` first to see the command surface; use `npx @tanstack/cli help <command>` (e.g. `help search-docs`) for flags and arguments on the machine you are using.
-  - `npx @tanstack/cli libraries` — list library **IDs** and versions (use these IDs with `doc` and `search-docs --library`).
-  - `npx @tanstack/cli search-docs "<query>" [--library router|start|ai|query|table|...] [--framework <name>] [--limit N]` — find doc sections before changing router, Start, or AI code.
-  - `npx @tanstack/cli doc <library> <path> [--docs-version latest]` — fetch a full doc page (library examples: `router`, `start`, `ai`, `query`; path examples mirror the docs tree, e.g. `framework/react/guide/data-loading` — confirm the exact path via `search-docs` when unsure).
-
-  **Quick reference**
-
-  | Need | Starting point |
-  |------|----------------|
-  | Correct loader / `beforeLoad` / layout behavior | `search-docs` with `--library router` (or `start` for TanStack Start) |
-  | Exact chat / tool / adapter API | `search-docs` / `doc` with `--library ai` |
-  | Unknown CLI flag | `npx @tanstack/cli --help` and command-specific `--help` |
-
-  ## AI Architecture
-
-  The AI stack uses three packages from `@tanstack/ai`:
-
-  - **Server** (`@tanstack/ai`): `chat()`, `toolDefinition()`, `convertMessagesToModelMessages()`, `toServerSentEventsResponse()`, `maxIterations()`. Adapter packages: `@tanstack/ai-openai`, `@tanstack/ai-anthropic`, `@tanstack/ai-gemini`, `@tanstack/ai-ollama`, `@tanstack/ai-openrouter`, `@tanstack/ai-groq`, `@tanstack/ai-grok`. See AGENTS.md section 8 for the provider table, env vars, and adapter factory pattern.
-  - **Client** (`@tanstack/ai-react` + `@tanstack/ai-client`): `useChat()`, `fetchServerSentEvents()`, `clientTools()`, `createChatClientOptions()`. Client tools execute automatically — no `onToolCall` callback. See AGENTS.md section 8 "Chat Client Setup" for the wiring example.
-  - **Endpoint** (`src/routes/api/chat.ts`): the wiring point connecting adapter, system prompt, tools, and auth. See below and AGENTS.md section 8 "Chat Endpoint" for the full anatomy.
-
-  ### Chat Endpoint (`src/routes/api/chat.ts`)
-
-  A TanStack Start file-based route at `/api/chat` with two handlers:
-
-  - **GET** — returns `{ available: boolean }` so the root loader can decide whether to show the chat UI (rule 19).
-  - **POST** — check adapter → parse `{ messages, browserContext }` → read the request ticket from middleware context → validate client context schema → `buildSystemPrompt()` → assemble tools array → `chat({ adapter, messages, systemPrompts, tools, agentLoopStrategy })` → `toServerSentEventsResponse(stream)`.
-
-  `buildSystemPrompt()` composes `BASE_SYSTEM_PROMPT` (rule 25) + navigation manifest + dynamic context (rule 14). When modifying: add tools to the array, update `BASE_SYSTEM_PROMPT` when the data model changes, add pattern-matching for new dynamic route segments. See AGENTS.md section 8 "System Prompt Generation" for the six-section prompt template.
-
-  ## Dynamic Route Schema Extraction for AI
-
-  To help the AI navigate accurately using client tools, dynamically extract your TanStack Router configuration from `router.flatRoutes`. Map this array to extract `fullPath`, `staticData.description` (for page context), path params (from segments starting with `$`), and search params by introspecting `validateSearch` schemas where possible. Passing this structured map in the system prompt allows the AI to discover available routes and required parameters without hallucinating URLs. Fall back to hand-maintained metadata only when the framework/schema surface cannot expose the needed description.
+  | Need | Where |
+  |------|--------|
+  | UI kit (default Mantine), styling | §3 |
+  | Auth, middleware, guards | §5 |
+  | AI adapters, chat client, tools, prompts | §8 |
+  | Observability (Sentry, pino, `__APP_VERSION__`) | §9 |
+  | Vitest, Playwright, E2E fixtures | §10 |
+  | Full validation checklist (format, lint, test, build) | §17 |
+  | Public runtime `window.__ENV__` | §13 |
 
   ## Verification
 
-  Testing setup (Vitest, Playwright, auth fixtures) and the full validation checklist are in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) sections 10 and 12. Quick smoke test: `pnpm format && pnpm lint && pnpm knip && pnpm test && pnpm build`. If the project has not wired Knip yet, add the latest stable `knip` dev dependency or explicitly document why unused-code validation is deferred. After scaffolding or setup changes, also start dev mode and ping `/api/health`; if required credentials are missing, state which prerequisite blocked the health check and what was verified instead.
+  **This template repo (skill authors):** after editing YAML, run `pnpm skills:build` and `pnpm skills:check`.
+
+  **Apps built from the template:** follow **AGENTS.md** §17 — e.g. `pnpm format && pnpm lint && pnpm test && pnpm build`; smoke with dev server and `/api/health` when configuration allows.

From 12ede51daa0d4a634d2ee07fd1b7938416c775d2 Mon Sep 17 00:00:00 2001
From: Carlos <carlos.martin-sanchez@mongodb.com>
Date: Sun, 10 May 2026 13:17:12 +0200
Subject: [PATCH 3/5] chore(skills): bump version to 1.17.0 and update
 documentation

- Update the skill version to 1.17.0 to reflect recent enhancements and clarifications.
- Revise capabilities in SKILL.md, registry.json, and YAML files to improve clarity on TypeScript usage and architectural patterns.
- Add new authoring guidelines in AUTHORING.md to streamline skill development and ensure consistency across generated outputs.
- Enhance README.md and skills/README.md with installation instructions and usage examples for better user guidance.

This update aims to refine the skill's functionality and provide clearer documentation for developers implementing the TanStack Fullstack Pattern.
---
 .gitignore                                    |   2 +
 README.md                                     | 113 ++++++------------
 skills/AUTHORING.md                           |  43 +++++++
 skills/README.md                              |  66 +++++-----
 skills/registry.json                          |  13 +-
 ...omptable-fullstack-app-template.skill.yaml |  42 +++++--
 6 files changed, 161 insertions(+), 118 deletions(-)
 create mode 100644 skills/AUTHORING.md

diff --git a/.gitignore b/.gitignore
index b94d3b7..ce8c270 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,5 @@ test-results/
 .netlify
 # Local skill plugin config (machine-specific)
 skills/plugin.local.json
+skills/dist
+skills/dist/tanstack-promptable-fullstack-app-template.md
diff --git a/README.md b/README.md
index 7957916..8d0d707 100644
--- a/README.md
+++ b/README.md
@@ -24,28 +24,52 @@ pnpm dev
 
 Open [http://localhost:3000](http://localhost:3000). The app works immediately with seed data — no database, no API keys, no configuration needed.
 
-## Install The Skill (npx skills)
+## Use the Agent Skill
 
-You can install this repository's generated Agent Skill directly from GitHub:
+The **TanStack Promptable Fullstack** skill is an [Agent Skill](https://agentskills.io) that teaches coding assistants the template’s **architecture contract**: interface-first boundaries, three schema layers with `Schema.parse()` at each boundary, thin routes + loaders (no `useEffect` data fetching for route data), URL state via `validateSearch`, repository interfaces, AI tools aligned with server functions, auth + invalidation on mutations, and TypeScript discipline inside the typed flow. **[AGENTS.md](./AGENTS.md)** stays the **handbook** (UI, auth snippets, chat, tests, checklist); the skill is the **rules agents must not break**.
 
-```bash
-# List skills available in this repository
-npx skills add carlosvin/tanstack-fullstack-ai-template --list
+**Why it helps:** fewer regressions when scaffolding features, migrating code, or refactoring routes — agents follow the same non-obvious invariants the template depends on.
 
-# Install the TanStack fullstack pattern skill
-npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
+**When to use it:** starting from this template, adding entities or AI tools, adopting the pattern in another TanStack Start app, or fixing duplicated parent/child route work.
 
-# Optional: install globally (available across projects)
-npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template -g
+### Super quick install
 
-# Optional: verify installed skills
-npx skills list
+```bash
+npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
 ```
 
-The skill is published in the standard location used by the CLI:
+Optional: `-g` installs globally; `npx skills add carlosvin/tanstack-fullstack-ai-template --list` lists skills from this repo; `npx skills list` verifies installed skills.
+
+The published skill document in this repository is:
 
 - `.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md`
 
+### Other ways to install
+
+- **Shell installer** (Cursor / Windsurf / Claude Code global dirs):  
+  `curl -sL https://raw.githubusercontent.com/carlosvin/tanstack-fullstack-ai-template/main/scripts/skills/install.sh | bash -s -- --force`
+- **Manual copy:** copy `.agents/skills/tanstack-promptable-fullstack-app-template/` to `~/.cursor/skills/`, `~/.claude/skills/`, or your editor’s documented skills path.
+- **Using this repo as-is:** Windsurf and compatible tools can read `.agents/skills/` directly — no extra step.
+
+More user-focused detail: **[skills/README.md](./skills/README.md)** · Editing/regenerating the skill (YAML, CI): **[skills/AUTHORING.md](./skills/AUTHORING.md)**.
+
+### Try it
+
+Ask your agent:
+
+- "What are the core contract items in the TanStack fullstack skill I must not violate?"
+- "Add a new domain entity following this template’s schema layers, repository, server functions, routes, and AI tools."
+- "Should any of my nested routes move shared `beforeLoad` or loader work to a parent layout?"
+
+### What the skill enforces (outcomes)
+
+- **One tools-layer schema** for both server functions and AI tools; **parse both ways** (tools ↔ repo) at mapper boundaries.
+- **Thin routes**; **loaders** fetch data; **URL search params** hold filters/tabs/selections with `loaderDeps` for cache keys.
+- **POST mutations** use auth + invalidation middleware; callers normalize errors consistently for UI and AI.
+- **AI:** expose repository capabilities as tools; client **navigate** / **invalidateRouter**; gate chat on availability; bounded agent loop in `chat()`.
+- **Parent layouts** own shared guards and expensive reads; children read parent loader data instead of duplicating work.
+- **TypeScript** after parsing: preserve inference — prefer `satisfies`, exhaustive handling, and guards over `any` and loose `as` casts.
+
 ## Architecture
 
 The architecture is organized in layers with clear interface boundaries. The interfaces are the contract — the implementations are your choice.
@@ -328,70 +352,9 @@ Then follow the end-to-end workflow:
 6. Create file-based routes under `src/routes/` (data in loaders, state in URL search params)
 7. When ready for real data, implement `mongoRepository.ts` and set `MONGODB_URI`
 
-### Option B: AI-Assisted via Generated Skill (New or Existing Project)
-
-The skill is defined once in a canonical YAML source and generated into the [agentskills.io](https://agentskills.io) standard at `.agents/skills/tanstack-promptable-fullstack-app-template/`. Windsurf and other compatible tools read this path directly.
-
-The generated outputs are committed intentionally so you can copy the skill into another project or tool without running the build pipeline first. The machine-readable metadata lives in `skills/registry.json`, and the portable markdown copy lives in `skills/dist/`.
-
-**Use the skill in this repo:** clone the template — the skill is at `.agents/skills/tanstack-promptable-fullstack-app-template/`.
-
-**Install the skill globally** (available in all your projects):
-
-Run this one-liner in your terminal to automatically download and install the skill into the global directories for Cursor, Windsurf, and Claude Code:
-
-```bash
-curl -sL https://raw.githubusercontent.com/carlosvin/tanstack-fullstack-ai-template/main/scripts/skills/install.sh | bash -s -- --force
-```
-
-To manually install instead:
-
-```bash
-# Windsurf (reads .agents/skills/ when in repo; for global copy)
-cp -r .agents/skills/tanstack-promptable-fullstack-app-template ~/.codeium/windsurf/skills/
-
-# Cursor (copy from shared standard)
-cp -r .agents/skills/tanstack-promptable-fullstack-app-template ~/.cursor/skills/
-
-# Claude Code (copy from shared standard)
-cp -r .agents/skills/tanstack-promptable-fullstack-app-template ~/.claude/skills/
-```
-
-To regenerate after editing the canonical source:
-
-```bash
-pnpm skills:build
-```
-
-To verify the generated outputs are current:
-
-```bash
-pnpm skills:check
-pnpm test:skills
-```
-
-To verify that your editor actually loaded the skill, ask the agent a direct pattern question such as:
-
-- *"What are the rigid rules in the TanStack fullstack pattern?"*
-- *"How should this project structure repository and observability services?"*
-
-If the skill loaded correctly, the response should mention the interface-first boundaries, loaders-first data fetching, URL-as-state, and mutation invalidation conventions.
-
-Once active, ask the agent to apply the pattern:
-
-- *"Set up this project using the TanStack fullstack pattern"*
-- *"Add the repository pattern to this existing app"*
-- *"Migrate this project to use interface-first architecture"*
-
-The skill covers:
-
-- The 6 architectural layers and their boundaries
-- All 4 interface contracts (`ReadRepository`/`WritableRepository`, `AIAdapterService`, `ObservabilityService`, `AuthContext`)
-- Rigid rules (loaders-first, URL-as-state, schema-first types, invalidation middleware)
-- Implementation choices (swap any layer: database, AI, UI, observability, schema library)
-- A validation checklist to verify the pattern is correctly applied
+### Option B: AI-assisted (skill)
 
-Tool support note: the canonical metadata now tracks support targets and install mode per tool. The current target tools are Windsurf (`native`) plus Cursor and Claude Code (`copy`). Use `skills/registry.json` as the source of truth for current support status.
+See **[Use the Agent Skill](#use-the-agent-skill)** above for install commands, quick prompts, and what the skill enforces. Contributor workflow (edit YAML, regenerate): **[skills/AUTHORING.md](./skills/AUTHORING.md)**.
 
 ### Option C: Adopt Incrementally (Existing Project)
 
diff --git a/skills/AUTHORING.md b/skills/AUTHORING.md
new file mode 100644
index 0000000..8f32501
--- /dev/null
+++ b/skills/AUTHORING.md
@@ -0,0 +1,43 @@
+# Skills authoring (contributors)
+
+This project stores skills in a vendor-agnostic canonical format and generates platform-specific outputs.
+
+## Canonical source
+
+- Canonical schema: `skills/spec/skill.schema.json`
+- Canonical skill files: `skills/src/*.skill.yaml`
+
+Each canonical file contains:
+
+- Portable metadata (`id`, `title`, `summary`, `version`, `tags`, `triggers`)
+- Publication metadata (`author`, `license`, `homepage`, `repository`, `documentationUrl`, `status`, `supportedTools`)
+- Structured execution hints (`inputs`, `outputs`, `constraints`, `steps`, `examples`)
+- Canonical markdown body in `content`
+
+## Generated outputs
+
+Generated files are derived from canonical source and should not be edited manually.
+
+| Path | Purpose |
+| --- | --- |
+| `.agents/skills/<id>/SKILL.md` | [agentskills.io](https://agentskills.io) standard — read natively by Windsurf and any compatible tool |
+| `skills/dist/<id>.md` | Portable docs (GitHub, wikis, copy-paste) |
+| `skills/registry.json` | Machine-readable manifest for discovery |
+
+Generated outputs are committed on purpose so other projects can consume the skill without running the build pipeline first.
+
+Tools that don't yet read `.agents/skills/` (for example Cursor, Claude Code) can use the same `SKILL.md` by copying the skill folder into their tool's directory (for example `~/.cursor/skills/` or `.claude/skills/`).
+
+## Commands
+
+```bash
+pnpm skills:build   # Validate + generate all outputs
+pnpm skills:check   # Validate + fail if generated files drift
+```
+
+## Workflow
+
+1. Edit or add a canonical file under `skills/src/`.
+2. Run `pnpm skills:build`.
+3. Commit both canonical and generated outputs.
+4. CI/lint should run `pnpm skills:check` to prevent drift.
diff --git a/skills/README.md b/skills/README.md
index 1bbe1ae..1b91cab 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -1,43 +1,51 @@
-# Skills Authoring Guide
+# TanStack Promptable Fullstack skill
 
-This project stores skills in a vendor-agnostic canonical format and generates platform-specific outputs.
+This repo ships an **[Agent Skill](https://agentskills.io)** that teaches coding agents the **architecture contract** for this template: interface-first services, three schema layers with explicit parsing at boundaries, loader-first routes, URL-as-state, AI tool coverage, and strong TypeScript inside the typed flow. Operational detail (UI kit, auth snippets, chat wiring, tests) stays in the repo's **[AGENTS.md](../AGENTS.md)** — the skill focuses on **what to enforce**, not every implementation recipe.
 
-## Canonical Source
+**Use it when** you scaffold or extend a TanStack Start app from this pattern, migrate an existing app, or need agents to follow current TanStack docs instead of guessing.
 
-- Canonical schema: `skills/spec/skill.schema.json`
-- Canonical skill files: `skills/src/*.skill.yaml`
+## Super quick install
 
-Each canonical file contains:
+From any machine with Node/npm:
 
-- Portable metadata (`id`, `title`, `summary`, `version`, `tags`, `triggers`)
-- Publication metadata (`author`, `license`, `homepage`, `repository`, `documentationUrl`, `status`, `supportedTools`)
-- Structured execution hints (`inputs`, `outputs`, `constraints`, `steps`, `examples`)
-- Canonical markdown body in `content`
+```bash
+npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
+```
 
-## Generated Outputs
+Optional: install **globally** so the skill is available in every project:
 
-Generated files are derived from canonical source and should not be edited manually.
+```bash
+npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template -g
+```
 
-| Path | Purpose |
-| --- | --- |
-| `.agents/skills/<id>/SKILL.md` | [agentskills.io](https://agentskills.io) standard — read natively by Windsurf and any compatible tool |
-| `skills/dist/<id>.md` | Portable docs (GitHub, wikis, copy-paste) |
-| `skills/registry.json` | Machine-readable manifest for discovery |
+List what this repo publishes, then confirm:
 
-Generated outputs are committed on purpose so other projects can consume the skill without running the build pipeline first.
+```bash
+npx skills add carlosvin/tanstack-fullstack-ai-template --list
+npx skills list
+```
 
-Tools that don't yet read `.agents/skills/` (e.g. Cursor, Claude Code) can use the same `SKILL.md` by copying the skill folder into their tool's directory (e.g. `~/.cursor/skills/` or `.claude/skills/`).
+## Skill files in this repository
 
-## Commands
+After clone, the generated skill lives here (committed on purpose):
 
-```bash
-pnpm skills:build   # Validate + generate all outputs
-pnpm skills:check   # Validate + fail if generated files drift
-```
+- `.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md` — standard skill document agents load
+- `skills/dist/tanstack-promptable-fullstack-app-template.md` — portable copy for docs or paste
+- `skills/registry.json` — machine-readable manifest
+
+## Other install options
+
+- **One-shot installer** (Cursor, Windsurf, Claude Code global dirs): see the root [README.md](../README.md#use-the-agent-skill).
+- **Manual copy**: copy the folder `.agents/skills/tanstack-promptable-fullstack-app-template/` into your tool's skills directory (for example `~/.cursor/skills/`).
+
+## Try it
+
+Paste one of these into your agent after install:
+
+- "Follow this repo's TanStack fullstack skill: what are the core contract items I must not violate?"
+- "Add a new domain entity using the template's schema layers, repository, server functions, routes, and AI tools."
+- "Review my nested routes: shared `beforeLoad` / loaders should live on the parent layout — what should move?"
 
-## Workflow
+## Contributors
 
-1. Edit or add a canonical file under `skills/src/`.
-2. Run `pnpm skills:build`.
-3. Commit both canonical and generated outputs.
-4. CI/lint should run `pnpm skills:check` to prevent drift.
+To edit or regenerate the skill from YAML, see **[AUTHORING.md](./AUTHORING.md)**.
diff --git a/skills/registry.json b/skills/registry.json
index 2e41575..5cd8f5b 100644
--- a/skills/registry.json
+++ b/skills/registry.json
@@ -7,7 +7,7 @@
       "summary": "Use when scaffolding a new TanStack Start project, adding domain entities to the fullstack template, or implementing the interface-first repository pattern with AI-promptable tools, or nested layout routes duplicate beforeLoad checks or loaders that should live on a parent route, or TanStack Router, Start, or AI behavior must be verified against current documentation instead of training data.",
       "projectName": "TanStack AI-Promptable Full-Stack Template",
       "projectSummary": "A production-ready TanStack Start template designed to make internal tools AI promptable by default.",
-      "version": "1.16.0",
+      "version": "1.17.0",
       "author": {
         "name": "Carlos Martin-Sanchez",
         "url": "https://github.com/carlosvin"
@@ -51,7 +51,7 @@
       "capabilities": [
         "Interface-first boundaries with swappable implementations",
         "Three schema layers with mandatory Schema.parse() at every boundary (tool→repo and repo→tool)",
-        "Strong TypeScript inside the typed flow — inference preserved with satisfies unions exhaustive checks few casts",
+        "Strong TypeScript in the typed flow — inference preserved via satisfies, unions, exhaustive switches; casts minimized",
         "Loader-first routes and URL-driven state via validateSearch",
         "Router config bundle (defaults + project Link wrapper preserving search params)",
         "Full AI tool coverage mirroring repository surface + client navigate/invalidate tools",
@@ -60,7 +60,8 @@
         "Auth ticket built in middleware via repository + TraceabilityContext on writes",
         "Parent layout routes deduplicating shared beforeLoad and loaders",
         "Optional patterns — overlay repo, bulk edit, distinct-values tools, dynamic route introspection",
-        "TanStack Intent + CLI as doc-aligned guidance (not duplicated command manuals)"
+        "TanStack Intent + CLI as doc-aligned guidance (not duplicated command manuals)",
+        "Assistant chat renders Markdown (GFM) — lists, tables, code blocks; internal links stay navigable"
       ],
       "triggers": [
         "fullstack template",
@@ -88,7 +89,7 @@
         "Domain wire shapes come from Zod/ArkType schemas and z.infer<>; repository interfaces use repository-layer types only",
         "Tools-layer schemas shared by createServerFn and AI tools; repository interfaces use repository-layer types only; UI and AI never import repository schemas",
         "Map inbound with RepoInputSchema.parse(fromTools(...)) and outbound with ToolsOutputSchema.parse(fromRepo(...)) so wire shapes never bypass validation",
-        "After parsing keep inferred types end-to-end — avoid any widening to Record string unknown and avoid as except documented third-party boundaries prefer satisfies discriminated unions const tuples narrow guards exhaustive never",
+        "After Schema.parse, preserve inferred types end-to-end — avoid widening to any or Record<string, unknown>; avoid as casts except at documented third-party boundaries; prefer satisfies, discriminated unions, const tuples, type guards, and exhaustive handling",
         "Fetch route data in loaders through server functions; keep route files thin; URL state in validateSearch with loaderDeps",
         "POST mutations chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`; handlers throw HttpError; callers normalize via processResponse / safeToolHandler / createSafeServerTool",
         "Expose every repository method as a safe AI tool; distinct-values tools for enum-ish filters",
@@ -99,7 +100,7 @@
         "Auth middleware enriches ctx.context with a repository-built ticket (e.g. getReadRepository().getUserAccess(email)); WritableRepository writes accept a TraceabilityContext built from that ticket",
         "Promptable by default — root loader checks getAIAvailability(); chat input includes browserContext (timezone, locale, path); chat() uses agentLoopStrategy maxIterations(N)",
         "Verify TanStack Router/Start/AI APIs with npx @tanstack/cli against current docs; use TanStack Intent for package skills — do not add them as project deps unless the app needs them as tooling",
-        "Operational detail — UI library, chat drawer, logging, Sentry, testing, env bridge — follows repo AGENTS.md"
+        "Operational detail — UI library, chat Markdown rendering (implementation in AGENTS.md §8), logging, Sentry, testing, env bridge — follows repo AGENTS.md"
       ],
       "steps": [
         "Define repository-layer and tools-layer schemas; implement repository interfaces (seed + production)",
@@ -107,7 +108,7 @@
         "Add GET/POST server functions with shared tools-layer input validators",
         "Register global middleware — auth (enrich ctx.context with a repository-built ticket), invalidation; optional pre-auth redirects",
         "Configure router defaults bundle and project Link wrapper; add routes with validateSearch, loaderDeps, loaders; nest shared work on parent layouts",
-        "Wire AI — toolDefinition for every server function, safe handlers, client navigate/invalidate tools, buildSystemPrompt fed by the auth ticket and the chat browserContext, agentLoopStrategy maxIterations(N) on chat()",
+        "Wire AI — toolDefinition for every server function, safe handlers, client navigate/invalidate tools, buildSystemPrompt fed by the auth ticket and chat browserContext, agentLoopStrategy maxIterations(N) on chat(); ensure assistant messages render as Markdown per AGENTS.md §8",
         "Gate chat UI on getAIAvailability() in the root loader; add distinct-values read paths for enum-ish filters when applicable",
         "Validate changes per AGENTS.md; use TanStack CLI/Intent when changing Router/Start/AI behavior"
       ],
diff --git a/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml b/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
index f528ac1..d1cbb48 100644
--- a/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
+++ b/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
@@ -11,7 +11,7 @@ projectName: TanStack AI-Promptable Full-Stack Template
 projectSummary: >-
   A production-ready TanStack Start template designed to make internal tools AI
   promptable by default.
-version: 1.16.0
+version: 1.17.0
 author:
   name: Carlos Martin-Sanchez
   url: https://github.com/carlosvin
@@ -46,7 +46,7 @@ tags:
 capabilities:
   - Interface-first boundaries with swappable implementations
   - Three schema layers with mandatory Schema.parse() at every boundary (tool→repo and repo→tool)
-  - Strong TypeScript inside the typed flow — inference preserved with satisfies unions exhaustive checks few casts
+  - Strong TypeScript in the typed flow — inference preserved via satisfies, unions, exhaustive switches; casts minimized
   - Loader-first routes and URL-driven state via validateSearch
   - Router config bundle (defaults + project Link wrapper preserving search params)
   - Full AI tool coverage mirroring repository surface + client navigate/invalidate tools
@@ -56,6 +56,7 @@ capabilities:
   - Parent layout routes deduplicating shared beforeLoad and loaders
   - Optional patterns — overlay repo, bulk edit, distinct-values tools, dynamic route introspection
   - TanStack Intent + CLI as doc-aligned guidance (not duplicated command manuals)
+  - Assistant chat renders Markdown (GFM) — lists, tables, code blocks; internal links stay navigable
 triggers:
   - fullstack template
   - TanStack Start project
@@ -79,7 +80,10 @@ constraints:
   - Domain wire shapes come from Zod/ArkType schemas and z.infer<>; repository interfaces use repository-layer types only
   - Tools-layer schemas shared by createServerFn and AI tools; repository interfaces use repository-layer types only; UI and AI never import repository schemas
   - Map inbound with RepoInputSchema.parse(fromTools(...)) and outbound with ToolsOutputSchema.parse(fromRepo(...)) so wire shapes never bypass validation
-  - After parsing keep inferred types end-to-end — avoid any widening to Record string unknown and avoid as except documented third-party boundaries prefer satisfies discriminated unions const tuples narrow guards exhaustive never
+  - >-
+    After Schema.parse, preserve inferred types end-to-end — avoid widening to any or Record<string, unknown>;
+    avoid as casts except at documented third-party boundaries; prefer satisfies, discriminated unions, const tuples,
+    type guards, and exhaustive handling
   - Fetch route data in loaders through server functions; keep route files thin; URL state in validateSearch with loaderDeps
   - "POST mutations chain `.middleware([requireAuthMiddleware, invalidateMiddleware])`; handlers throw HttpError; callers normalize via processResponse / safeToolHandler / createSafeServerTool"
   - Expose every repository method as a safe AI tool; distinct-values tools for enum-ish filters
@@ -90,14 +94,17 @@ constraints:
   - Auth middleware enriches ctx.context with a repository-built ticket (e.g. getReadRepository().getUserAccess(email)); WritableRepository writes accept a TraceabilityContext built from that ticket
   - "Promptable by default — root loader checks getAIAvailability(); chat input includes browserContext (timezone, locale, path); chat() uses agentLoopStrategy maxIterations(N)"
   - Verify TanStack Router/Start/AI APIs with npx @tanstack/cli against current docs; use TanStack Intent for package skills — do not add them as project deps unless the app needs them as tooling
-  - Operational detail — UI library, chat drawer, logging, Sentry, testing, env bridge — follows repo AGENTS.md
+  - Operational detail — UI library, chat Markdown rendering (implementation in AGENTS.md §8), logging, Sentry, testing, env bridge — follows repo AGENTS.md
 steps:
   - Define repository-layer and tools-layer schemas; implement repository interfaces (seed + production)
   - Map between layers with Schema.parse() at boundaries; carry z.infer types through handlers UI tools without erasing to any or untyped records
   - Add GET/POST server functions with shared tools-layer input validators
   - Register global middleware — auth (enrich ctx.context with a repository-built ticket), invalidation; optional pre-auth redirects
   - Configure router defaults bundle and project Link wrapper; add routes with validateSearch, loaderDeps, loaders; nest shared work on parent layouts
-  - Wire AI — toolDefinition for every server function, safe handlers, client navigate/invalidate tools, buildSystemPrompt fed by the auth ticket and the chat browserContext, agentLoopStrategy maxIterations(N) on chat()
+  - >-
+    Wire AI — toolDefinition for every server function, safe handlers, client navigate/invalidate tools,
+    buildSystemPrompt fed by the auth ticket and chat browserContext, agentLoopStrategy maxIterations(N) on chat();
+    ensure assistant messages render as Markdown per AGENTS.md §8
   - Gate chat UI on getAIAvailability() in the root loader; add distinct-values read paths for enum-ish filters when applicable
   - Validate changes per AGENTS.md; use TanStack CLI/Intent when changing Router/Start/AI behavior
 examples:
@@ -113,6 +120,23 @@ content: |
 
   > **Companion handbook:** [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) — structure, styling, auth snippets, Biome, testing/E2E, validation checklist, AI chat setup.
 
+  ## How to use this skill
+
+  1. Read **Core Contract** first — it is the non-negotiable architecture.
+  2. Run the **Architecture Checklist** before every non-trivial change.
+  3. Jump to **Schema Boundaries**, **Request Context**, or **Special Patterns** only when that concern applies.
+  4. Use **[AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md)** for operational how-to (UI kit, chat wiring, logging, tests, validation commands) — not for inventing alternate architecture.
+
+  ## Common failure modes (avoid these)
+
+  - **Route state in React state:** filters, tabs, or selections in `useState` instead of validated URL search params + `loaderDeps`.
+  - **Repository schemas at the wrong edge:** importing repository-layer schemas into UI, tools, or AI tool inputs — use tools-layer schemas only.
+  - **Server function without a tool:** adding `createServerFn` but skipping `toolDefinition` + `createSafeServerTool` for the same capability.
+  - **Parse only half the boundary:** validating inbound tools input but returning raw repo rows to UI/AI without tools-layer `Schema.parse` on the way out.
+  - **UI-only auth:** hiding buttons in components but skipping guards in server handlers.
+  - **Type escape hatches:** `any`, loose `Record<string, unknown>`, or `as` after `Schema.parse` — narrow, guard, or fix types instead.
+  - **Duplicated parent work:** copying a parent layout’s `beforeLoad`, loader, or expensive read into each child route.
+
   ## Core Contract
 
   1. **Interfaces:** Database, AI, observability (and other externals) sit behind interfaces; implementations are swappable.
@@ -131,8 +155,6 @@ content: |
   14. **Metadata for AI and UI:** Use `.describe()` for all narrative explanations (JSON Schema `description`). Use `.meta({ ... })` only for **structured extras** — `unit`, `format`, optional `title`, app-specific hints — not as a substitute for `.describe()`. Prefer deriving prompts and UI copy from schemas + `z.toJSONSchema()` and router introspection over parallel hand-maintained maps.
   15. **Parent layouts:** Shared `beforeLoad`, redirects, and expensive reads belong on the **parent** layout route; children read parent loader data via `getRouteApi` / `useLoaderData({ from })` — do not duplicate parent work.
 
-  Day-to-day operational concerns (UI kit, chat drawer placement, markdown rendering, LLM provider choice, pino/Sentry, icons, RSC vs `"use client"`, full validation commands) follow **AGENTS.md** — see the handbook table below.
-
   ## Architecture Checklist
 
   Scan before changing code:
@@ -148,6 +170,10 @@ content: |
   - **Routes:** **`validateSearch`** + **`loaderDeps`**; duplicate **`beforeLoad`** / shared loaders only on **parent** layouts.
   - **Metadata discipline:** `.describe()` for narrative copy; `.meta()` for structured extras; closed vocabularies = `as const` tuple + `z.enum` + `z.infer<>`.
 
+  ## Markdown assistant replies (UX contract)
+
+  Assistant messages in the chat UI must **render as Markdown** (including GFM): lists, **tables**, fenced and inline code blocks, and links. Internal paths like `[Tasks](/tasks)` should remain **client-navigable** where the app implements markdown links (do not flatten assistant output to plain text for display). Concrete stack (`react-markdown`, `remark-gfm`, styling, `MarkdownLink` behavior) lives in **AGENTS.md §8** — agents changing chat rendering must follow that section.
+
   ## Schema Boundaries
 
   `Route search schema → loader → tools schema → server fn → mapping → repo schema → repo`
@@ -322,7 +348,7 @@ content: |
   |------|--------|
   | UI kit (default Mantine), styling | §3 |
   | Auth, middleware, guards | §5 |
-  | AI adapters, chat client, tools, prompts | §8 |
+  | AI adapters, chat client, tools, prompts, Markdown (GFM) rendering | §8 |
   | Observability (Sentry, pino, `__APP_VERSION__`) | §9 |
   | Vitest, Playwright, E2E fixtures | §10 |
   | Full validation checklist (format, lint, test, build) | §17 |

From 2783912013406e95a3c90b50bc3c1dca16136ed2 Mon Sep 17 00:00:00 2001
From: Carlos <carlos.martin-sanchez@mongodb.com>
Date: Sun, 10 May 2026 13:27:06 +0200
Subject: [PATCH 4/5] chore(skills): update documentation and add evaluation
 scenarios for TanStack Promptable Fullstack App Template

- Remove unnecessary entries from .gitignore for better clarity.
- Revise README.md to focus on using the Agent Skill, streamline installation instructions, and enhance the generated example section.
- Add new evaluation scenarios in skills/evals/tanstack-promptable-fullstack-app-template.md to guide users on common tasks and expectations when using the skill.
- Update SKILL.md to include detailed usage instructions and common failure modes to improve developer understanding.

This update aims to enhance the usability and clarity of the documentation for developers implementing the TanStack Fullstack Pattern.
---
 .../SKILL.md                                  | 25 +++++++-
 .gitignore                                    |  1 -
 README.md                                     | 62 +++++++++----------
 ...stack-promptable-fullstack-app-template.md | 27 ++++++++
 4 files changed, 78 insertions(+), 37 deletions(-)
 create mode 100644 skills/evals/tanstack-promptable-fullstack-app-template.md

diff --git a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
index e7efd49..cbf5dad 100644
--- a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
+++ b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
@@ -18,6 +18,23 @@ description: 'Use when scaffolding a new TanStack Start project, adding domain
 
 > **Companion handbook:** [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) — structure, styling, auth snippets, Biome, testing/E2E, validation checklist, AI chat setup.
 
+## How to use this skill
+
+1. Read **Core Contract** first — it is the non-negotiable architecture.
+2. Run the **Architecture Checklist** before every non-trivial change.
+3. Jump to **Schema Boundaries**, **Request Context**, or **Special Patterns** only when that concern applies.
+4. Use **[AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md)** for operational how-to (UI kit, chat wiring, logging, tests, validation commands) — not for inventing alternate architecture.
+
+## Common failure modes (avoid these)
+
+- **Route state in React state:** filters, tabs, or selections in `useState` instead of validated URL search params + `loaderDeps`.
+- **Repository schemas at the wrong edge:** importing repository-layer schemas into UI, tools, or AI tool inputs — use tools-layer schemas only.
+- **Server function without a tool:** adding `createServerFn` but skipping `toolDefinition` + `createSafeServerTool` for the same capability.
+- **Parse only half the boundary:** validating inbound tools input but returning raw repo rows to UI/AI without tools-layer `Schema.parse` on the way out.
+- **UI-only auth:** hiding buttons in components but skipping guards in server handlers.
+- **Type escape hatches:** `any`, loose `Record<string, unknown>`, or `as` after `Schema.parse` — narrow, guard, or fix types instead.
+- **Duplicated parent work:** copying a parent layout’s `beforeLoad`, loader, or expensive read into each child route.
+
 ## Core Contract
 
 1. **Interfaces:** Database, AI, observability (and other externals) sit behind interfaces; implementations are swappable.
@@ -36,8 +53,6 @@ description: 'Use when scaffolding a new TanStack Start project, adding domain
 14. **Metadata for AI and UI:** Use `.describe()` for all narrative explanations (JSON Schema `description`). Use `.meta({ ... })` only for **structured extras** — `unit`, `format`, optional `title`, app-specific hints — not as a substitute for `.describe()`. Prefer deriving prompts and UI copy from schemas + `z.toJSONSchema()` and router introspection over parallel hand-maintained maps.
 15. **Parent layouts:** Shared `beforeLoad`, redirects, and expensive reads belong on the **parent** layout route; children read parent loader data via `getRouteApi` / `useLoaderData({ from })` — do not duplicate parent work.
 
-Day-to-day operational concerns (UI kit, chat drawer placement, markdown rendering, LLM provider choice, pino/Sentry, icons, RSC vs `"use client"`, full validation commands) follow **AGENTS.md** — see the handbook table below.
-
 ## Architecture Checklist
 
 Scan before changing code:
@@ -53,6 +68,10 @@ Scan before changing code:
 - **Routes:** **`validateSearch`** + **`loaderDeps`**; duplicate **`beforeLoad`** / shared loaders only on **parent** layouts.
 - **Metadata discipline:** `.describe()` for narrative copy; `.meta()` for structured extras; closed vocabularies = `as const` tuple + `z.enum` + `z.infer<>`.
 
+## Markdown assistant replies (UX contract)
+
+Assistant messages in the chat UI must **render as Markdown** (including GFM): lists, **tables**, fenced and inline code blocks, and links. Internal paths like `[Tasks](/tasks)` should remain **client-navigable** where the app implements markdown links (do not flatten assistant output to plain text for display). Concrete stack (`react-markdown`, `remark-gfm`, styling, `MarkdownLink` behavior) lives in **AGENTS.md §8** — agents changing chat rendering must follow that section.
+
 ## Schema Boundaries
 
 `Route search schema → loader → tools schema → server fn → mapping → repo schema → repo`
@@ -227,7 +246,7 @@ interface WritableRepository {
 |------|--------|
 | UI kit (default Mantine), styling | §3 |
 | Auth, middleware, guards | §5 |
-| AI adapters, chat client, tools, prompts | §8 |
+| AI adapters, chat client, tools, prompts, Markdown (GFM) rendering | §8 |
 | Observability (Sentry, pino, `__APP_VERSION__`) | §9 |
 | Vitest, Playwright, E2E fixtures | §10 |
 | Full validation checklist (format, lint, test, build) | §17 |
diff --git a/.gitignore b/.gitignore
index ce8c270..284a4b0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,4 +16,3 @@ test-results/
 # Local skill plugin config (machine-specific)
 skills/plugin.local.json
 skills/dist
-skills/dist/tanstack-promptable-fullstack-app-template.md
diff --git a/README.md b/README.md
index 8d0d707..f383747 100644
--- a/README.md
+++ b/README.md
@@ -8,23 +8,13 @@ Built with [TanStack Start](https://tanstack.com/start) — with every external
 
 **[Live Demo](https://leafy-manatee-16b96c.netlify.app)** | **[Blog Post](building-ai-promptable-fullstack-apps.md)**
 
-## Quick Start
+## Use the Agent Skill
 
 ```bash
-# Clone the template
-git clone https://github.com/carlosvin/tanstack-fullstack-ai-template.git
-cd tanstack-fullstack-ai-template
-
-# Install dependencies
-pnpm install
-
-# Start the dev server (uses in-memory seed data, no DB required)
-pnpm dev
+npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
 ```
 
-Open [http://localhost:3000](http://localhost:3000). The app works immediately with seed data — no database, no API keys, no configuration needed.
-
-## Use the Agent Skill
+Optional: `-g` installs globally; `npx skills add carlosvin/tanstack-fullstack-ai-template --list` lists skills from this repo; `npx skills list` verifies installed skills.
 
 The **TanStack Promptable Fullstack** skill is an [Agent Skill](https://agentskills.io) that teaches coding assistants the template’s **architecture contract**: interface-first boundaries, three schema layers with `Schema.parse()` at each boundary, thin routes + loaders (no `useEffect` data fetching for route data), URL state via `validateSearch`, repository interfaces, AI tools aligned with server functions, auth + invalidation on mutations, and TypeScript discipline inside the typed flow. **[AGENTS.md](./AGENTS.md)** stays the **handbook** (UI, auth snippets, chat, tests, checklist); the skill is the **rules agents must not break**.
 
@@ -32,18 +22,6 @@ The **TanStack Promptable Fullstack** skill is an [Agent Skill](https://agentski
 
 **When to use it:** starting from this template, adding entities or AI tools, adopting the pattern in another TanStack Start app, or fixing duplicated parent/child route work.
 
-### Super quick install
-
-```bash
-npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
-```
-
-Optional: `-g` installs globally; `npx skills add carlosvin/tanstack-fullstack-ai-template --list` lists skills from this repo; `npx skills list` verifies installed skills.
-
-The published skill document in this repository is:
-
-- `.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md`
-
 ### Other ways to install
 
 - **Shell installer** (Cursor / Windsurf / Claude Code global dirs):  
@@ -295,9 +273,32 @@ Create a new class implementing `AIAdapterService` from `src/services/ai/types.t
 
 Replace Mantine imports in components. The architectural layers (repository, server functions, middleware) are unaffected.
 
-## Scripts
+## Generated Example
+
+You can easily run it just by.
 
 ```bash
+
+# Install dependencies
+pnpm install
+
+# Start the dev server (uses in-memory seed data, no DB required)
+pnpm dev
+```
+
+Open [http://localhost:3000](http://localhost:3000). The app works immediately with seed data — no database, no API keys, no configuration needed.
+
+### Run it with Docker
+
+```bash
+docker build -t my-app .
+docker run --rm -p 3000:3000 my-app
+```
+
+### Scripts
+
+```bash
+# commands for the app generated by the skill
 pnpm dev        # Start dev server on port 3000
 pnpm build      # Production build
 pnpm start      # Run production server
@@ -305,17 +306,12 @@ pnpm test       # Run unit tests (Vitest)
 pnpm test:e2e   # Run E2E tests (Playwright, uses seed data)
 pnpm lint       # Lint + typecheck (Biome)
 pnpm format     # Auto-format (Biome)
+
+# skill dev commands
 pnpm skills:build  # Generate Cursor + markdown skill artifacts
 pnpm skills:check  # Validate canonical skills and check for drift
 ```
 
-## Docker
-
-```bash
-docker build -t my-app .
-docker run --rm -p 3000:3000 my-app
-```
-
 ## Tech Stack
 
 - **Framework**: [TanStack Start](https://tanstack.com/start) (full-stack React with SSR)
diff --git a/skills/evals/tanstack-promptable-fullstack-app-template.md b/skills/evals/tanstack-promptable-fullstack-app-template.md
new file mode 100644
index 0000000..21f5304
--- /dev/null
+++ b/skills/evals/tanstack-promptable-fullstack-app-template.md
@@ -0,0 +1,27 @@
+# Pressure scenarios — TanStack Promptable Fullstack App Template skill
+
+Lightweight prompts for manual review or future automation. A compliant agent should satisfy **Core Contract + Architecture Checklist** without contradicting **AGENTS.md** operational detail.
+
+## 1. Entity scaffold
+
+**Prompt:** Add a new domain entity quickly (e.g. `Project`) with list + detail routes.
+
+**Expect:** Tools-layer + repository-layer schemas; repository interface + seed + Mongo implementations; GET/POST server functions with correct middleware on mutations; AI tools mirroring repo/server surface; thin routes + page components; at least smoke/unit coverage where the template expects tests.
+
+## 2. Route refactor
+
+**Prompt:** Nested routes repeat the same `beforeLoad` auth check and re-fetch the same parent data in each child loader — fix it.
+
+**Expect:** Shared `beforeLoad` / loader / expensive reads on the **parent** layout route; children use `getRouteApi` / `useLoaderData({ from: ... })` instead of duplicating parent work.
+
+## 3. Metadata / type-safety
+
+**Prompt:** Add a filter enum (e.g. task view) and expose consistent labels/metadata for the AI and UI table.
+
+**Expect:** Closed vocabulary via `z.enum` (often backed by a `const` tuple), `.describe()` on fields, `.meta()` where structured extras are needed, `z.infer<>` — avoid treating loose `as const` object maps as the single source of truth without schema alignment.
+
+## 4. Markdown response surface
+
+**Prompt:** Ensure the assistant can answer with a short summary **table**, a **code snippet**, and **internal markdown links** that navigate inside the app.
+
+**Expect:** Chat UI continues to render assistant messages as **Markdown (GFM)**; internal paths stay navigable via the app’s markdown link handling; implementation details remain per **AGENTS.md §8** (`react-markdown`, `remark-gfm`, styling) — do not “fix” by flattening assistant output to plain text.

From 94172137506051fb67cf58be237e9cc27b3c522c Mon Sep 17 00:00:00 2001
From: Carlos <carlos.martin-sanchez@mongodb.com>
Date: Mon, 11 May 2026 09:07:13 +0200
Subject: [PATCH 5/5] chore(skills): refine .gitignore and enhance
 documentation for TanStack Promptable Fullstack App Template

- Remove the 'skills/dist' entry from .gitignore for improved clarity.
- Update capabilities in the template documentation to include Markdown rendering features and common failure modes.
- Bump the version to 1.17.0 to reflect the latest enhancements.

This update aims to streamline the development process and improve the usability of the documentation for developers using the TanStack Fullstack Pattern.
---
 .gitignore                                    |  1 -
 ...stack-promptable-fullstack-app-template.md | 29 +++++++++++++++----
 2 files changed, 24 insertions(+), 6 deletions(-)

diff --git a/.gitignore b/.gitignore
index 284a4b0..b94d3b7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,4 +15,3 @@ test-results/
 .netlify
 # Local skill plugin config (machine-specific)
 skills/plugin.local.json
-skills/dist
diff --git a/skills/dist/tanstack-promptable-fullstack-app-template.md b/skills/dist/tanstack-promptable-fullstack-app-template.md
index 31d54d5..525765a 100644
--- a/skills/dist/tanstack-promptable-fullstack-app-template.md
+++ b/skills/dist/tanstack-promptable-fullstack-app-template.md
@@ -9,9 +9,9 @@
 - Documentation: https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/skills/README.md
 - Status: stable
 - Supported tools: Windsurf [native, tested], Cursor [copy, tested], Claude Code [copy, tested]
-- Capabilities: Interface-first boundaries with swappable implementations, Three schema layers with mandatory Schema.parse() at every boundary (tool→repo and repo→tool), Strong TypeScript inside the typed flow — inference preserved with satisfies unions exhaustive checks few casts, Loader-first routes and URL-driven state via validateSearch, Router config bundle (defaults + project Link wrapper preserving search params), Full AI tool coverage mirroring repository surface + client navigate/invalidate tools, Schema-first AI/UI metadata (.describe + optional .meta for unit/format/title), Promptable by default — getAIAvailability gating + browserContext + bounded agent loop, Auth ticket built in middleware via repository + TraceabilityContext on writes, Parent layout routes deduplicating shared beforeLoad and loaders, Optional patterns — overlay repo, bulk edit, distinct-values tools, dynamic route introspection, TanStack Intent + CLI as doc-aligned guidance (not duplicated command manuals)
+- Capabilities: Interface-first boundaries with swappable implementations, Three schema layers with mandatory Schema.parse() at every boundary (tool→repo and repo→tool), Strong TypeScript in the typed flow — inference preserved via satisfies, unions, exhaustive switches; casts minimized, Loader-first routes and URL-driven state via validateSearch, Router config bundle (defaults + project Link wrapper preserving search params), Full AI tool coverage mirroring repository surface + client navigate/invalidate tools, Schema-first AI/UI metadata (.describe + optional .meta for unit/format/title), Promptable by default — getAIAvailability gating + browserContext + bounded agent loop, Auth ticket built in middleware via repository + TraceabilityContext on writes, Parent layout routes deduplicating shared beforeLoad and loaders, Optional patterns — overlay repo, bulk edit, distinct-values tools, dynamic route introspection, TanStack Intent + CLI as doc-aligned guidance (not duplicated command manuals), Assistant chat renders Markdown (GFM) — lists, tables, code blocks; internal links stay navigable
 - ID: `tanstack-promptable-fullstack-app-template`
-- Version: `1.16.0`
+- Version: `1.17.0`
 - Tags: tanstack-start, fullstack, architecture, interface-first, repository-pattern, ai-promptable
 
 ## Summary
@@ -39,6 +39,23 @@ Use when scaffolding a new TanStack Start project, adding domain entities to the
 
 > **Companion handbook:** [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) — structure, styling, auth snippets, Biome, testing/E2E, validation checklist, AI chat setup.
 
+## How to use this skill
+
+1. Read **Core Contract** first — it is the non-negotiable architecture.
+2. Run the **Architecture Checklist** before every non-trivial change.
+3. Jump to **Schema Boundaries**, **Request Context**, or **Special Patterns** only when that concern applies.
+4. Use **[AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md)** for operational how-to (UI kit, chat wiring, logging, tests, validation commands) — not for inventing alternate architecture.
+
+## Common failure modes (avoid these)
+
+- **Route state in React state:** filters, tabs, or selections in `useState` instead of validated URL search params + `loaderDeps`.
+- **Repository schemas at the wrong edge:** importing repository-layer schemas into UI, tools, or AI tool inputs — use tools-layer schemas only.
+- **Server function without a tool:** adding `createServerFn` but skipping `toolDefinition` + `createSafeServerTool` for the same capability.
+- **Parse only half the boundary:** validating inbound tools input but returning raw repo rows to UI/AI without tools-layer `Schema.parse` on the way out.
+- **UI-only auth:** hiding buttons in components but skipping guards in server handlers.
+- **Type escape hatches:** `any`, loose `Record<string, unknown>`, or `as` after `Schema.parse` — narrow, guard, or fix types instead.
+- **Duplicated parent work:** copying a parent layout’s `beforeLoad`, loader, or expensive read into each child route.
+
 ## Core Contract
 
 1. **Interfaces:** Database, AI, observability (and other externals) sit behind interfaces; implementations are swappable.
@@ -57,8 +74,6 @@ Use when scaffolding a new TanStack Start project, adding domain entities to the
 14. **Metadata for AI and UI:** Use `.describe()` for all narrative explanations (JSON Schema `description`). Use `.meta({ ... })` only for **structured extras** — `unit`, `format`, optional `title`, app-specific hints — not as a substitute for `.describe()`. Prefer deriving prompts and UI copy from schemas + `z.toJSONSchema()` and router introspection over parallel hand-maintained maps.
 15. **Parent layouts:** Shared `beforeLoad`, redirects, and expensive reads belong on the **parent** layout route; children read parent loader data via `getRouteApi` / `useLoaderData({ from })` — do not duplicate parent work.
 
-Day-to-day operational concerns (UI kit, chat drawer placement, markdown rendering, LLM provider choice, pino/Sentry, icons, RSC vs `"use client"`, full validation commands) follow **AGENTS.md** — see the handbook table below.
-
 ## Architecture Checklist
 
 Scan before changing code:
@@ -74,6 +89,10 @@ Scan before changing code:
 - **Routes:** **`validateSearch`** + **`loaderDeps`**; duplicate **`beforeLoad`** / shared loaders only on **parent** layouts.
 - **Metadata discipline:** `.describe()` for narrative copy; `.meta()` for structured extras; closed vocabularies = `as const` tuple + `z.enum` + `z.infer<>`.
 
+## Markdown assistant replies (UX contract)
+
+Assistant messages in the chat UI must **render as Markdown** (including GFM): lists, **tables**, fenced and inline code blocks, and links. Internal paths like `[Tasks](/tasks)` should remain **client-navigable** where the app implements markdown links (do not flatten assistant output to plain text for display). Concrete stack (`react-markdown`, `remark-gfm`, styling, `MarkdownLink` behavior) lives in **AGENTS.md §8** — agents changing chat rendering must follow that section.
+
 ## Schema Boundaries
 
 `Route search schema → loader → tools schema → server fn → mapping → repo schema → repo`
@@ -248,7 +267,7 @@ interface WritableRepository {
 |------|--------|
 | UI kit (default Mantine), styling | §3 |
 | Auth, middleware, guards | §5 |
-| AI adapters, chat client, tools, prompts | §8 |
+| AI adapters, chat client, tools, prompts, Markdown (GFM) rendering | §8 |
 | Observability (Sentry, pino, `__APP_VERSION__`) | §9 |
 | Vitest, Playwright, E2E fixtures | §10 |
 | Full validation checklist (format, lint, test, build) | §17 |