diff --git a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
index 6cccc5d..cbf5dad 100644
--- a/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
+++ b/.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md
@@ -8,84 +8,111 @@ 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.
 # 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.
-
-## 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.
-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 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.
-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)`).
-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.
-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.
+**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.
+
+## 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.
+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.
+
+## 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<>`.
+
+## 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 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.
+**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.
+**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(),
@@ -98,82 +125,135 @@ export const Route = createFileRoute('/tasks/')({
 })
 ```
 
-**Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`).
-
-## 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.
+**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
-interface ReadRepository {
-  getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
-  getTask(id: string): Promise<TaskRepoOutput | null>
-  getDistinctValues(field: string): Promise<string[]>
-  getUserProfile(email: string): Promise<UserProfile | null>
+// 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,
+  })
 }
-interface WritableRepository {
-  createTask(input: TaskRepoInput, createdBy?: string): Promise<TaskRepoOutput>
-  updateTask(id: string, input: Partial<TaskRepoInput>): Promise<TaskRepoOutput | null>
-  deleteTask(id: string): Promise<boolean>
+
+// 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,
+  })
 }
 ```
 
-## Styling, Auth, and Observability
+**TypeScript discipline (complements Zod):** Zod validates **at boundaries**; TypeScript keeps the interior honest — narrow with guards instead of casting.
 
-These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
+```typescript
+type TaskStatus = 'pending' | 'done'
 
-- **Mantine UI** -- see AGENTS.md section 3 (component-first styling, CSS Modules, dark mode).
-- **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).
+const STATUS_LABEL = {
+  pending: 'Pending',
+  done: 'Done',
+} as const satisfies Record<TaskStatus, string>
 
-## Migration / Build Workflow
+function assertNever(x: never): never {
+  throw new Error(`Unexpected ${String(x)}`)
+}
 
-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.
-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.
+function labelForStatus(status: TaskStatus): string {
+  switch (status) {
+    case 'pending':
+      return STATUS_LABEL.pending
+    case 'done':
+      return STATUS_LABEL.done
+    default:
+      return assertNever(status)
+  }
+}
+```
 
-## TanStack documentation (official CLI)
+**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.
 
-Prefer **current** TanStack guidance over training-data recall. The TanStack team ships a CLI that mirrors the docs site.
+## Request Context
 
-- 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).
+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 } = ctx.context
+  ticket.requireTaskEditor(ctx.data.taskId)
+  const repoPatch = TaskRepoPatchSchema.parse(mapToolUpdateToRepo(ctx.data))
+  return getWritableRepository().updateTask(ctx.data.taskId, repoPatch, {
+    lastModifiedBy: ticket.email,
+  })
+})
+```
+
+## Interface Contracts
 
-**Quick reference**
+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.
 
-| 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` |
+```typescript
+interface TraceabilityContext {
+  createdBy?: string
+  lastModifiedBy?: string
+}
 
-## AI Architecture
+interface ReadRepository {
+  getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
+  getTask(id: string): Promise<TaskRepoOutput | null>
+  getDistinctValues(field: string): Promise<string[]>
+  getUserProfile(email: string): Promise<UserProfile | null>
+}
+interface WritableRepository {
+  createTask(input: TaskRepoInput, trace?: TraceabilityContext): Promise<TaskRepoOutput>
+  updateTask(
+    id: string,
+    input: Partial<TaskRepoInput>,
+    trace?: TraceabilityContext,
+  ): Promise<TaskRepoOutput | null>
+  deleteTask(id: string): Promise<boolean>
+}
+```
 
-The AI stack uses three packages from `@tanstack/ai`:
+## Implementation Flow
 
-- **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.
+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.
 
-### Chat Endpoint (`src/routes/api/chat.ts`)
+## Special Patterns (use when the feature applies)
 
-A TanStack Start file-based route at `/api/chat` with two handlers:
+- **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.
 
-- **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)`.
+## TanStack Intent, CLI, and AI
 
-`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.
+- **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**.
 
-## Dynamic Route Schema Extraction for AI
+## Use the handbook (AGENTS.md)
 
-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.
+| Need | Where |
+|------|--------|
+| UI kit (default Mantine), styling | §3 |
+| Auth, middleware, guards | §5 |
+| 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 |
+| 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 test && pnpm build`.
+**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/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/README.md b/README.md
index 7957916..f383747 100644
--- a/README.md
+++ b/README.md
@@ -8,43 +8,45 @@ 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
+npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
+```
 
-# Install dependencies
-pnpm install
+Optional: `-g` installs globally; `npx skills add carlosvin/tanstack-fullstack-ai-template --list` lists skills from this repo; `npx skills list` verifies installed skills.
 
-# Start the dev server (uses in-memory seed data, no DB required)
-pnpm dev
-```
+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**.
 
-Open [http://localhost:3000](http://localhost:3000). The app works immediately with seed data — no database, no API keys, no configuration needed.
+**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 Skill (npx skills)
+**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.
 
-You can install this repository's generated Agent Skill directly from GitHub:
+### Other ways to install
 
-```bash
-# List skills available in this repository
-npx skills add carlosvin/tanstack-fullstack-ai-template --list
+- **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.
 
-# Install the TanStack fullstack pattern skill
-npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template
+More user-focused detail: **[skills/README.md](./skills/README.md)** · Editing/regenerating the skill (YAML, CI): **[skills/AUTHORING.md](./skills/AUTHORING.md)**.
 
-# Optional: install globally (available across projects)
-npx skills add carlosvin/tanstack-fullstack-ai-template --skill tanstack-promptable-fullstack-app-template -g
+### Try it
 
-# Optional: verify installed skills
-npx skills list
-```
+Ask your agent:
 
-The skill is published in the standard location used by the CLI:
+- "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?"
 
-- `.agents/skills/tanstack-promptable-fullstack-app-template/SKILL.md`
+### 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
 
@@ -271,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
@@ -281,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)
@@ -328,70 +348,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/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/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/dist/tanstack-promptable-fullstack-app-template.md b/skills/dist/tanstack-promptable-fullstack-app-template.md
index a115caa..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: 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: 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.10.0`
+- Version: `1.17.0`
 - Tags: tanstack-start, fullstack, architecture, interface-first, repository-pattern, ai-promptable
 
 ## Summary
@@ -29,82 +29,111 @@ 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.
-
-## 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.
-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 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.
-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)`).
-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.
-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.
+**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.
+
+## 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.
+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.
+
+## 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<>`.
+
+## 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 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.
+**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.
+**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(),
@@ -117,82 +146,135 @@ export const Route = createFileRoute('/tasks/')({
 })
 ```
 
-**Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`).
-
-## 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.
+**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
-interface ReadRepository {
-  getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
-  getTask(id: string): Promise<TaskRepoOutput | null>
-  getDistinctValues(field: string): Promise<string[]>
-  getUserProfile(email: string): Promise<UserProfile | null>
+// 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,
+  })
 }
-interface WritableRepository {
-  createTask(input: TaskRepoInput, createdBy?: string): Promise<TaskRepoOutput>
-  updateTask(id: string, input: Partial<TaskRepoInput>): Promise<TaskRepoOutput | null>
-  deleteTask(id: string): Promise<boolean>
+
+// 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,
+  })
 }
 ```
 
-## Styling, Auth, and Observability
+**TypeScript discipline (complements Zod):** Zod validates **at boundaries**; TypeScript keeps the interior honest — narrow with guards instead of casting.
 
-These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
+```typescript
+type TaskStatus = 'pending' | 'done'
 
-- **Mantine UI** -- see AGENTS.md section 3 (component-first styling, CSS Modules, dark mode).
-- **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).
+const STATUS_LABEL = {
+  pending: 'Pending',
+  done: 'Done',
+} as const satisfies Record<TaskStatus, string>
 
-## Migration / Build Workflow
+function assertNever(x: never): never {
+  throw new Error(`Unexpected ${String(x)}`)
+}
 
-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.
-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.
+function labelForStatus(status: TaskStatus): string {
+  switch (status) {
+    case 'pending':
+      return STATUS_LABEL.pending
+    case 'done':
+      return STATUS_LABEL.done
+    default:
+      return assertNever(status)
+  }
+}
+```
 
-## TanStack documentation (official CLI)
+**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.
 
-Prefer **current** TanStack guidance over training-data recall. The TanStack team ships a CLI that mirrors the docs site.
+## Request Context
 
-- 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).
+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 } = ctx.context
+  ticket.requireTaskEditor(ctx.data.taskId)
+  const repoPatch = TaskRepoPatchSchema.parse(mapToolUpdateToRepo(ctx.data))
+  return getWritableRepository().updateTask(ctx.data.taskId, repoPatch, {
+    lastModifiedBy: ticket.email,
+  })
+})
+```
+
+## Interface Contracts
 
-**Quick reference**
+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.
 
-| 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` |
+```typescript
+interface TraceabilityContext {
+  createdBy?: string
+  lastModifiedBy?: string
+}
 
-## AI Architecture
+interface ReadRepository {
+  getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
+  getTask(id: string): Promise<TaskRepoOutput | null>
+  getDistinctValues(field: string): Promise<string[]>
+  getUserProfile(email: string): Promise<UserProfile | null>
+}
+interface WritableRepository {
+  createTask(input: TaskRepoInput, trace?: TraceabilityContext): Promise<TaskRepoOutput>
+  updateTask(
+    id: string,
+    input: Partial<TaskRepoInput>,
+    trace?: TraceabilityContext,
+  ): Promise<TaskRepoOutput | null>
+  deleteTask(id: string): Promise<boolean>
+}
+```
 
-The AI stack uses three packages from `@tanstack/ai`:
+## Implementation Flow
 
-- **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.
+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.
 
-### Chat Endpoint (`src/routes/api/chat.ts`)
+## Special Patterns (use when the feature applies)
 
-A TanStack Start file-based route at `/api/chat` with two handlers:
+- **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.
 
-- **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)`.
+## TanStack Intent, CLI, and AI
 
-`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.
+- **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**.
 
-## Dynamic Route Schema Extraction for AI
+## Use the handbook (AGENTS.md)
 
-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.
+| Need | Where |
+|------|--------|
+| UI kit (default Mantine), styling | §3 |
+| Auth, middleware, guards | §5 |
+| 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 |
+| 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 test && pnpm build`.
+**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/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.
diff --git a/skills/registry.json b/skills/registry.json
index 80b87a0..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.10.0",
+      "version": "1.17.0",
       "author": {
         "name": "Carlos Martin-Sanchez",
         "url": "https://github.com/carlosvin"
@@ -49,21 +49,19 @@
         "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"
+        "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"
       ],
       "triggers": [
         "fullstack template",
@@ -74,7 +72,9 @@
         "nested routes",
         "layout route",
         "beforeLoad",
-        "tanstack cli"
+        "tanstack cli",
+        "tanstack intent",
+        "package skills"
       ],
       "inputs": [
         "Existing or new TanStack Start codebase",
@@ -86,42 +86,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."
+        "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 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",
+        "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 Markdown rendering (implementation in AGENTS.md §8), 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"
+        "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 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": [
         {
diff --git a/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml b/skills/src/tanstack-promptable-fullstack-app-template.skill.yaml
index 492eb6e..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.10.0
+version: 1.17.0
 author:
   name: Carlos Martin-Sanchez
   url: https://github.com/carlosvin
@@ -44,28 +44,19 @@ 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
+  - 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
 triggers:
   - fullstack template
   - TanStack Start project
@@ -76,6 +67,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
@@ -84,60 +77,36 @@ 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.
+  - 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 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
+  - 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 Markdown rendering (implementation in AGENTS.md §8), 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
+  - 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 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:
   - input: Add a new domain entity to the template
     output: Update schema, repository interfaces, server functions, routes, and AI
@@ -147,78 +116,105 @@ 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, 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.
-
-  ## 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.
-  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 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.
-  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)`).
-  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.
-  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.
+  **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.
+
+  ## 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.
+  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.
+
+  ## 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<>`.
+
+  ## 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 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.
+  **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.
+  **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(),
@@ -231,82 +227,135 @@ content: |
   })
   ```
 
-  **Type-safe mapping:** use `Schema.parse()` between layers so mismatches are caught at runtime (e.g. `TaskRepoInputSchema.parse(toolInput)`).
-
-  ## 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.
+  **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
-  interface ReadRepository {
-    getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
-    getTask(id: string): Promise<TaskRepoOutput | null>
-    getDistinctValues(field: string): Promise<string[]>
-    getUserProfile(email: string): Promise<UserProfile | null>
+  // 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,
+    })
   }
-  interface WritableRepository {
-    createTask(input: TaskRepoInput, createdBy?: string): Promise<TaskRepoOutput>
-    updateTask(id: string, input: Partial<TaskRepoInput>): Promise<TaskRepoOutput | null>
-    deleteTask(id: string): Promise<boolean>
+
+  // 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,
+    })
   }
   ```
 
-  ## Styling, Auth, and Observability
+  **TypeScript discipline (complements Zod):** Zod validates **at boundaries**; TypeScript keeps the interior honest — narrow with guards instead of casting.
 
-  These topics are documented once in [AGENTS.md](https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/AGENTS.md) to avoid drift:
+  ```typescript
+  type TaskStatus = 'pending' | 'done'
 
-  - **Mantine UI** -- see AGENTS.md section 3 (component-first styling, CSS Modules, dark mode).
-  - **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).
+  const STATUS_LABEL = {
+    pending: 'Pending',
+    done: 'Done',
+  } as const satisfies Record<TaskStatus, string>
 
-  ## Migration / Build Workflow
+  function assertNever(x: never): never {
+    throw new Error(`Unexpected ${String(x)}`)
+  }
 
-  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.
-  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.
+  function labelForStatus(status: TaskStatus): string {
+    switch (status) {
+      case 'pending':
+        return STATUS_LABEL.pending
+      case 'done':
+        return STATUS_LABEL.done
+      default:
+        return assertNever(status)
+    }
+  }
+  ```
 
-  ## TanStack documentation (official CLI)
+  **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.
 
-  Prefer **current** TanStack guidance over training-data recall. The TanStack team ships a CLI that mirrors the docs site.
+  ## Request Context
 
-  - 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).
+  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 } = ctx.context
+    ticket.requireTaskEditor(ctx.data.taskId)
+    const repoPatch = TaskRepoPatchSchema.parse(mapToolUpdateToRepo(ctx.data))
+    return getWritableRepository().updateTask(ctx.data.taskId, repoPatch, {
+      lastModifiedBy: ticket.email,
+    })
+  })
+  ```
+
+  ## Interface Contracts
 
-  **Quick reference**
+  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.
 
-  | 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` |
+  ```typescript
+  interface TraceabilityContext {
+    createdBy?: string
+    lastModifiedBy?: string
+  }
 
-  ## AI Architecture
+  interface ReadRepository {
+    getTasks(filter?: TaskRepoFilter): Promise<TaskRepoOutput[]>
+    getTask(id: string): Promise<TaskRepoOutput | null>
+    getDistinctValues(field: string): Promise<string[]>
+    getUserProfile(email: string): Promise<UserProfile | null>
+  }
+  interface WritableRepository {
+    createTask(input: TaskRepoInput, trace?: TraceabilityContext): Promise<TaskRepoOutput>
+    updateTask(
+      id: string,
+      input: Partial<TaskRepoInput>,
+      trace?: TraceabilityContext,
+    ): Promise<TaskRepoOutput | null>
+    deleteTask(id: string): Promise<boolean>
+  }
+  ```
 
-  The AI stack uses three packages from `@tanstack/ai`:
+  ## Implementation Flow
 
-  - **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.
+  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.
 
-  ### Chat Endpoint (`src/routes/api/chat.ts`)
+  ## Special Patterns (use when the feature applies)
 
-  A TanStack Start file-based route at `/api/chat` with two handlers:
+  - **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.
 
-  - **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)`.
+  ## TanStack Intent, CLI, and AI
 
-  `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.
+  - **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**.
 
-  ## Dynamic Route Schema Extraction for AI
+  ## Use the handbook (AGENTS.md)
 
-  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.
+  | Need | Where |
+  |------|--------|
+  | UI kit (default Mantine), styling | §3 |
+  | Auth, middleware, guards | §5 |
+  | 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 |
+  | 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 test && pnpm build`.
+  **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.