From cfdd15c771f277fa0cf36541c9875569a7dfafce Mon Sep 17 00:00:00 2001
From: Carlos <carlos.martin-sanchez@mongodb.com>
Date: Sun, 19 Apr 2026 18:50:51 +0200
Subject: [PATCH 1/3] docs: extract cross-app patterns into skill v1.9 and
 AGENTS.md

Ports rules 26-29 back into the canonical YAML source (they had drifted
into the generated SKILL.md only) and adds rules 30-36 capturing generic
patterns observed across multiple downstream apps: public env bridge,
router UX defaults, Link wrapper preserving search, public-route
allowlist, Sentry user+feedback binding, single markdown artifact for
help/AI/prompts, and distinct-value filter discovery tools.

AGENTS.md gains inline amendments (hydration-safe color scheme, satisfies
over as, pre-auth redirect middleware, loaderDeps cache keying,
virtual-field explainer, fluent prompt builder, Zod round-trip factories,
dual Playwright webServer) and new top-level sections for Public Runtime
Config, Bulk Edit Pattern, Override/Overlay Repository Pattern, Sortable
Tables, and Autosave Forms with concurrency guards.

Made-with: Cursor
---
 .../tanstack-fullstack-pattern/SKILL.md       |  11 ++
 AGENTS.md                                     | 142 +++++++++++++++++-
 skills/dist/tanstack-fullstack-pattern.md     |  15 +-
 skills/registry.json                          |  22 ++-
 .../src/tanstack-fullstack-pattern.skill.yaml |  82 ++++++++--
 5 files changed, 251 insertions(+), 21 deletions(-)

diff --git a/.agents/skills/tanstack-fullstack-pattern/SKILL.md b/.agents/skills/tanstack-fullstack-pattern/SKILL.md
index 7586b43..12ef857 100644
--- a/.agents/skills/tanstack-fullstack-pattern/SKILL.md
+++ b/.agents/skills/tanstack-fullstack-pattern/SKILL.md
@@ -47,6 +47,17 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 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.
+28. JSON-only server functions and tools; HTTP file routes for everything else: `createServerFn` (and therefore AI tools) handles JSON queries and mutations only. Non-JSON responses — file downloads (CSV/JSON exports, PDFs), uploads, webhooks, and streaming — go through TanStack Start HTTP file routes using `server.handlers.GET|POST` under `src/routes/api/*.ts`. The `/api/chat` SSE endpoint (rule 14) is the canonical example. These file routes still reuse server-function wrappers or repository methods internally so the data path stays unified, but the transport layer is explicit about its shape.
+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: 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. Reserve raw `<a>` for external URLs.
+33. Public-route allowlist in auth middleware: `authMiddleware` declares a `PUBLIC_ROUTES` set (health checks, `.well-known`, static asset paths) for which it returns a synthetic anonymous `AuthContext` (user/userProfile set to an `Anonymous` sentinel) instead of throwing 401. Keeps the `AuthContext` shape consistent so downstream code, typings, and AI tools never branch on "maybe no user".
+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). Add `feedbackIntegration({ autoInject: false })` and expose a header button that calls `openFeedback()`, giving users a controlled way to report issues with automatic user attribution.
+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.
 
 ## Schema Boundaries
 
diff --git a/AGENTS.md b/AGENTS.md
index 3bde91b..a71e571 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -77,6 +77,7 @@ This project uses [Mantine](https://mantine.dev/) as the primary UI framework.
 - **Avoid inline styles**: Use Mantine props or CSS Modules instead.
 - **Avoid `!important`**: Minimize its use.
 - **Dark mode**: All components must work in both light and dark color schemes.
+- **Hydration-safe color scheme reads**: When a component's rendered output depends on the active color scheme (e.g. swapping a logo variant, icon, or chart palette), read it with `useComputedColorScheme('light', { getInitialValueInEffect: true })` and gate any derived value behind a `useIsMounted()` (or `useHasHydrated()`) check. `useMantineColorScheme()` returns `'auto'` on the server and on the first client render; using it directly for render-affecting values produces hydration mismatches and a flash of the wrong asset.
 
 ### Icons
 
@@ -98,6 +99,9 @@ If your team prefers [`@tabler/icons-react`](https://tabler.io/icons) (the Manti
   - **Correct**: `const { filter } = Route.useSearch()` — state comes from the URL.
   - **Incorrect**: `const [filter, setFilter] = useState('all')` — state trapped in component.
 - **Internal Links**: Use TanStack Router's `Link` component for internal navigation.
+- **`satisfies` over `as`**: Do not use `as` to bypass type checking (`as never`, `as Record<string, unknown>`, `as SomeProps`). Prefer `as const satisfies SomeSchema` to validate a literal against a type without widening it, or fix the root type (update the interface, add a proper adapter, narrow with `in`/type guards). The **only** acceptable `as` casts are at clearly documented library boundaries where a third-party type is provably too strict, and each such cast must have an adjacent comment explaining why. For error inspection in `catch` blocks, use the `in` operator instead of casting `unknown` errors.
+  - **Good**: `if (typeof err === 'object' && err !== null && 'status' in err && typeof err.status === 'number') { … }`
+  - **Bad**: `const raw = err as Record<string, unknown>; const status = raw.status as number`
 
 ## 5. Middleware and Auth
 
@@ -147,6 +151,14 @@ For one-off auth in other handlers, use `requireAuth(context)` or `requireGroup(
 
 Create composable middleware that chains `authMiddleware` for context typing (see `src/middleware/requireAuth.ts` for the pattern). Chain it with `invalidateMiddleware` on POST server functions.
 
+### Public-Route Allowlist
+
+`authMiddleware` maintains a `PUBLIC_ROUTES` set (health checks, `.well-known`, static asset paths, public config endpoints) for which it returns a synthetic anonymous `AuthContext` instead of throwing `401`. Anonymous users have `user` and `userProfile` set to explicit `Anonymous` sentinels so the context shape is always uniform — downstream code, typings, and AI tools never need to branch on "maybe no user". Keep the allowlist small and specific; every other path requires authentication.
+
+### Pre-Auth Redirect Middleware (Legacy Path Compatibility)
+
+When a URL scheme changes (renaming a route segment, collapsing multiple paths into one, moving from hash-based to path-based routing), register a **pre-auth** middleware that short-circuits the request with a `308 Permanent Redirect` **before** `authMiddleware` runs. This avoids spurious `401` responses on old links shared in emails, bookmarks, or external systems. Implement the redirect via `new Response(null, { status: 308, headers: { Location: newPath } })` using a **relative** `Location` so it works across dev, staging, and production without hard-coded origins. Keep the allowlist of legacy paths small and retire entries once upstream consumers have migrated.
+
 ## 6. Server Functions and Data Access
 
 This is a full-stack TanStack Start application. There is no separate backend API. The [skill](.agents/skills/tanstack-fullstack-pattern/SKILL.md) defines the rigid layering rules and the "every repo method gets a tool" policy.
@@ -193,7 +205,10 @@ const result = await processResponse(() => myMutation({ data: input }))
 - **File-Based Routing**: Routes are defined as files in `src/routes/`. The route tree is auto-generated.
 - **Nested Routes**: Use nested routes for modals and lazy-loaded UI.
 - **Loaders over useEffect**: Data fetching belongs in `loader`, not in component effects. See section 6.1.
-- **Preserve Search Params**: `navigate({ to: '/path', search: prev => ({ ...prev, newParam: 'value' }) })`.
+- **Preserve Search Params**: `navigate({ to: '/path', search: prev => ({ ...prev, newParam: 'value' }) })` — always use the functional form so the router diffs prior search params instead of requiring the caller to read them via `useSearch()` first. Reading `useSearch()` only to spread it into a `navigate` call re-subscribes the component to search changes and is the most common source of unnecessary re-renders.
+- **`loaderDeps` for cache keying**: When a loader's output depends on `validateSearch` params (filters, pagination, search text), use `loaderDeps: ({ search }) => search` and pull from `deps` inside the loader. Do not read `useSearch()` inside the loader — only `deps` participates in the router's cache key. Use `loaderDeps` to pick *only* the search fields that affect the fetch; unrelated fields (e.g. an "expanded" flag that affects UI only) should be excluded so they do not invalidate the cache.
+- **Link wrapper**: Prefer the project-local `Link` wrapper (see rule 32 in the skill) over raw `@tanstack/react-router` `Link` so internal navigation preserves search params by default.
+- **Child routes read from parent loaders**: Deep components access already-loaded parent data via `getRouteApi('/parent-path').useLoaderData()` or `useLoaderData({ from: '/parent-path' })` rather than re-fetching. Loader-derived values (permissions, feature flags, the active user) flow into client hooks as stable snapshots — no `useEffect` + `useState` for data the loader already has.
 
 ## 8. AI Chat and Tools
 
@@ -237,6 +252,27 @@ The default implementation uses `@tanstack/ai-openai` with plain OpenAI. Set `OP
 - When adding new repository methods (reads and writes), expose them as AI tools.
 - **getCurrentUserContext** returns who is logged in and a permissions summary. **createTask**, **updateTask**, **deleteTask** call the same server functions as the UI; auth and creator checks run inside the server function handlers.
 
+### Virtual-Field Explanation Registry
+
+Some fields the AI surfaces are **computed**, not stored (e.g. a `status` derived from dates, a `health` score computed from a mix of columns, a `priority` inferred from SLA distance). The AI should not be asked to invent the rule each time. Instead, keep a single `fieldMetadata.ts` module that maps each virtual field to a short, stable explanation string, and expose an `explainField(fieldName)` AI tool plus a JSDoc-visible `VIRTUAL_FIELDS` constant consumed by the system prompt. When you add or change a derivation in the repository / mapping layer, update the registry in the same commit. This prevents the AI from answering "why is this Pending?" with a plausible-sounding guess that drifts from the actual rule.
+
+### Fluent System Prompt Builder
+
+For apps whose `buildSystemPrompt()` starts composing many conditional blocks (permissions, feature flags, location, time, navigation manifest, entity summaries), extract a tiny fluent builder in `src/services/ai/promptBuilder.ts`:
+
+```tsx
+// Pseudocode — keep the API small
+const prompt = new SystemPromptBuilder()
+  .section('Capabilities', capabilitiesText)
+  .sectionIf(user.isAdmin, 'Admin-only tools', adminToolsText)
+  .section('Current User', renderCurrentUser(user))
+  .section('Browser Context', renderBrowserContext(ctx))
+  .section('Navigation', getNavigationPromptSection())
+  .build()
+```
+
+The builder's only responsibility is: ordered sections, conditional inclusion, consistent `## Heading` / blank-line framing, and a final `.build(): string`. It must not know domain details. Prefer this once a `buildSystemPrompt()` function exceeds ~5 appended strings.
+
 ### Client Tools
 
 Client tools execute in the browser and are defined in `src/services/ai/tools.ts` (definition-only, no `.server()` call) with implementations in [ChatDrawer](src/components/ChatDrawer/ChatDrawer.tsx) using `clientTools()` from `@tanstack/ai-client`:
@@ -498,6 +534,10 @@ When `VITE_SENTRY_DSN` is set, the Sentry transport receives error-level logs al
 - **Rendering**: `renderWithProviders()` in `src/test-utils/renderWithRouter.tsx` wraps with MantineProvider.
 - **Convention**: Test files co-located as `*.test.ts` or `*.test.tsx`.
 
+### Test Factories (Zod Round-Trip)
+
+Define test factories (`makeTask()`, `makeUser()`, …) in `src/test-utils/factories.ts`. Every factory accepts a `Partial<T>` overrides bag, merges it with sensible defaults, and then **runs the result through `Schema.parse()`** before returning. This guarantees fixtures always match the schema — adding a required field or changing a validation rule surfaces as a failing factory call rather than a runtime crash deep in a test. Factories should not inline business logic (e.g. computing `healthStatus`); call the same pure helpers the repository uses, so fixture data and production data derive from one source of truth.
+
 ### E2E Tests (Playwright)
 
 - **Framework**: Playwright with Chromium.
@@ -506,6 +546,10 @@ When `VITE_SENTRY_DSN` is set, the Sentry transport receives error-level logs al
 - **Convention**: Spec files in `e2e/` as `*.spec.ts`.
 - **Running**: `pnpm test:e2e` (reuses existing dev server or starts one with seed data).
 
+#### Dual `webServer` with in-process mock backend
+
+When the app calls an external service that is not part of the repository (a third-party API, a search service, a feature-flag backend), run two Playwright `webServer` entries side by side: (1) the app itself, (2) an in-process HTTP mock server that the app is pointed at via env var. The mock server exposes an internal `/__reset` endpoint that each test calls in `beforeEach` to clear recorded requests and restore default responses — this gives deterministic, isolated tests without Docker or external processes. Keep the mock server's fixtures typed against the same schemas the real client consumes so contract drift surfaces as a type error.
+
 ## 11. Linting and Formatting
 
 This project uses [Biome](https://biomejs.dev/) as the default linter and formatter — **not** ESLint or Prettier. The configuration lives in `biome.json` with `recommended` rules and minimal overrides. When adding new rules, prefer Biome's built-in `recommended` set and keep custom overrides to a minimum.
@@ -517,7 +561,101 @@ This project uses [Biome](https://biomejs.dev/) as the default linter and format
 - **Major version upgrades are conscious decisions**: When `pnpm outdated` shows a major version bump, upgrade explicitly with `pnpm add <pkg>@latest`, then verify with `pnpm lint && pnpm test && pnpm build` before committing.
 - **After any dependency change**, run the full validation checklist (section 13) to catch regressions.
 
-## 13. Validate Changes
+## 13. Public Runtime Config
+
+Some config values differ per deployment (Sentry DSN, environment name, feature flags) but are **not secrets** and the client needs them immediately. Do not bake them into the Vite bundle via `import.meta.env` — that ties the built artifact to one environment. Instead, expose them through a GET server function and inline the result into the HTML document as `window.__ENV__` so the client can read them synchronously before any module runs.
+
+### Server function
+
+```tsx
+// src/services/api/serverFns.ts
+export const getPublicEnv = createServerFn({ method: 'GET' }).handler(async () => {
+  return {
+    sentryDsn: process.env.VITE_SENTRY_DSN ?? null,
+    environment: process.env.ENV ?? 'development',
+    featureFlags: {
+      /* flags that are safe to expose */
+    },
+  }
+})
+```
+
+### Inline into the document
+
+Call `getPublicEnv()` in the root loader and inject the result via a `<script>` tag in `RootDocument` (`src/routes/__root.tsx`). Use `JSON.stringify(...).replace(/</g, '\\u003c')` so the payload cannot break out of the `<script>` tag:
+
+```tsx
+const envJson = JSON.stringify(publicEnv).replace(/</g, '\\u003c')
+// In RootDocument <head>:
+<script
+  // biome-ignore lint/security/noDangerouslySetInnerHtml: seeds window.__ENV__ before client JS runs
+  dangerouslySetInnerHTML={{ __html: `window.__ENV__ = ${envJson};` }}
+/>
+```
+
+### Declare the global type
+
+```ts
+// src/vite-env.d.ts
+declare global {
+  interface Window {
+    __ENV__: {
+      sentryDsn: string | null
+      environment: string
+      featureFlags: Record<string, boolean>
+    }
+  }
+}
+export {}
+```
+
+Client-side SDK initialization (Sentry, analytics, etc.) reads `window.__ENV__` at the top of its init module. Because the script tag is emitted before client JS, reads are always synchronous and well-typed.
+
+## 14. Bulk Edit Pattern
+
+For lists where users need to change many rows at once (multi-row updates of status, priority, ownership), use a dedicated `/entity/edit?selected=id1&selected=id2` route driven entirely by URL state:
+
+1. **Selection** lives in the parent list's URL search param as a repeated key (`selected=...`). A small `useMultiEditSelection()` hook reads it via `useSearch()` and provides `toggle`, `clear`, `isSelected`.
+2. **Edit route** validates `selected: z.array(z.string()).default([])` in `validateSearch` and fetches those rows in a single loader call.
+3. **Category tabs** group editable fields (e.g. "Base", "Ownership", "Details") via a Mantine `SegmentedControl` backed by another URL search param so switching categories never loses progress.
+4. **Dirty tracking** keeps a cross-tab `Map<rowId, Partial<Fields>>` so only changed cells are included in the save payload.
+5. **An "Apply all" row** lets the user set a single value for a column across every selected row; clicking it writes that value into every row's dirty map.
+6. **Batch server function** uses MongoDB `bulkWrite` (or the equivalent) for a single round-trip, validates permissions per row, and chains `invalidateMiddleware` so the list refetches on success.
+7. **Close/cancel** clears the `selected` search param on the parent list so stale selections don't leak across navigations.
+
+Keep the multi-edit form layout agnostic of entity specifics by defining column metadata (label, editor type, permission check, read-only flag) in a single table so new fields plug in without touching the form component.
+
+## 15. Override / Overlay Repository Pattern
+
+Some entities are sourced from upstream systems (a data warehouse export, a Google Sheet, a vendor API) but users need to annotate them with app-local fields (notes, custom categorization, manual corrections). The clean way to model this is an **overrides overlay**:
+
+- **Source collection** (read-only, refreshed by a pipeline) holds the upstream rows.
+- **Overrides collection** holds sparse per-entity documents with only the user-edited fields plus audit metadata (`lastModifiedBy`, `lastModifiedDate`).
+- **Read path**: repository loads source rows and overrides in parallel, then runs a **pure `applyOverrides(source, override)`** function that shallow-merges override values over source values, treating `null` as "revert to source". The merged view is what the UI and AI see.
+- **Write path**: mutations target the overrides collection with `$set` for provided fields and `$unset` for explicit `null`s, using `upsert: true` via `bulkWrite` so concurrent edits are resilient.
+- **UI affordance**: the form renders the current (merged) value and shows a subtle "Revert to source" affordance next to overridden fields. Clicking it sets the field to `null` on the next save, which `$unset`s it and restores the source value on next read.
+
+Keep the overlay function pure and unit-tested — it is the single place where "what does the user see" is defined.
+
+## 16. Sortable Tables (Controlled Mode)
+
+The reusable `ApplicationListTable`-style component exposes both **uncontrolled** and **controlled** sort modes:
+
+- **Uncontrolled** (default): the component manages its own sort state internally. Use for simple lists where sort does not need to persist.
+- **Controlled**: the consumer passes `sortBy`, `sortDirection`, and `onSortChange`. Use when sort state must live in the URL (deep-linking, shareable views) or when multiple tables need to share a sort.
+
+Sort logic lives in a pure `sortRows(rows, sortBy, direction)` function, unit-tested independently of React. Date columns sort chronologically; rows where the sort field is `null`/`undefined` always sink to the bottom regardless of direction so they don't interleave with valid data. Avoid ad-hoc per-column sort comparators — centralize them in one typed map keyed by column id.
+
+## 17. Autosave Forms with Concurrency Guards
+
+For detail panels that persist changes via PATCH as the user edits, two failure modes must be defended against:
+
+1. **Spurious mount PATCH**: A `useEffect` that "corrects" the initial value (e.g. clamps a number, normalizes a string) will fire on mount and trigger a PATCH before the user has done anything. Guard with a `hasMounted` ref that is `false` on the first run; only run the correction logic on subsequent runs. An even simpler approach is to make the initial state already-correct so no correction is needed.
+2. **Concurrent PATCH collisions**: A fast typist can produce two debounced PATCHes in flight at once, where the second overwrites the first. Track an `isPatching` ref; at the top of the debounced handler, bail out if `isPatching.current` is true (the pending patch bag still holds the changes). When the in-flight PATCH resolves, call `flushPatch.flush()` if the pending bag is non-empty so the next request fires immediately without an extra debounce wait. This gives "at most one PATCH in flight, immediate retry" semantics.
+
+Encapsulate both behaviors in a `useEntityPatch(id, options)` hook so form components only deal with "merge these fields"; the hook owns debouncing, in-flight tracking, pending-change coalescing, and toast feedback.
+
+## 18. Validate Changes
 
 Always verify changes with:
 
diff --git a/skills/dist/tanstack-fullstack-pattern.md b/skills/dist/tanstack-fullstack-pattern.md
index bd79984..8f9e43f 100644
--- a/skills/dist/tanstack-fullstack-pattern.md
+++ b/skills/dist/tanstack-fullstack-pattern.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, not yet verified], Cursor [copy, not yet verified], Claude Code [copy, not yet verified]
-- 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
+- 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, Public-route allowlist on the auth middleware that returns a synthetic anonymous context for health checks and well-known paths
 - ID: `tanstack-fullstack-pattern`
-- Version: `1.8.0`
+- Version: `1.9.0`
 - Tags: tanstack-start, fullstack, architecture, interface-first, repository-pattern, ai-promptable
 
 ## Summary
@@ -66,6 +66,17 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 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.
+28. JSON-only server functions and tools; HTTP file routes for everything else: `createServerFn` (and therefore AI tools) handles JSON queries and mutations only. Non-JSON responses — file downloads (CSV/JSON exports, PDFs), uploads, webhooks, and streaming — go through TanStack Start HTTP file routes using `server.handlers.GET|POST` under `src/routes/api/*.ts`. The `/api/chat` SSE endpoint (rule 14) is the canonical example. These file routes still reuse server-function wrappers or repository methods internally so the data path stays unified, but the transport layer is explicit about its shape.
+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: 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. Reserve raw `<a>` for external URLs.
+33. Public-route allowlist in auth middleware: `authMiddleware` declares a `PUBLIC_ROUTES` set (health checks, `.well-known`, static asset paths) for which it returns a synthetic anonymous `AuthContext` (user/userProfile set to an `Anonymous` sentinel) instead of throwing 401. Keeps the `AuthContext` shape consistent so downstream code, typings, and AI tools never branch on "maybe no user".
+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). Add `feedbackIntegration({ autoInject: false })` and expose a header button that calls `openFeedback()`, giving users a controlled way to report issues with automatic user attribution.
+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.
 
 ## Schema Boundaries
 
diff --git a/skills/registry.json b/skills/registry.json
index c144cc1..a771c1d 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.",
       "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.8.0",
+      "version": "1.9.0",
       "author": {
         "name": "Carlos Martin-Sanchez",
         "url": "https://github.com/carlosvin"
@@ -57,7 +57,12 @@
         "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"
+        "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",
+        "Public-route allowlist on the auth middleware that returns a synthetic anonymous context for health checks and well-known paths"
       ],
       "triggers": [
         "fullstack template",
@@ -85,7 +90,12 @@
         "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"
+        "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",
+        "Auth middleware declares an explicit public-route allowlist that returns a synthetic anonymous AuthContext",
+        "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"
       ],
       "steps": [
         "Define schemas as source of truth and infer types",
@@ -97,6 +107,12 @@
         "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",
+        "Allowlist public routes in the auth middleware with a synthetic anonymous context",
+        "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"
       ],
       "examples": [
diff --git a/skills/src/tanstack-fullstack-pattern.skill.yaml b/skills/src/tanstack-fullstack-pattern.skill.yaml
index 481360b..df3a595 100644
--- a/skills/src/tanstack-fullstack-pattern.skill.yaml
+++ b/skills/src/tanstack-fullstack-pattern.skill.yaml
@@ -8,7 +8,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.8.0
+version: 1.9.0
 author:
   name: Carlos Martin-Sanchez
   url: https://github.com/carlosvin
@@ -46,10 +46,23 @@ capabilities:
   - 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
+  - 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
+  - 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
+  - Public-route allowlist on the auth middleware that returns a synthetic
+    anonymous context for health checks and well-known paths
 triggers:
   - fullstack template
   - TanStack Start project
@@ -65,29 +78,59 @@ outputs:
 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
+  - 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
+  - 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
+  - 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
+  - Auth middleware declares an explicit public-route allowlist that returns a
+    synthetic anonymous AuthContext
+  - 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
 steps:
   - Define schemas as source of truth and infer types
-  - "Split schemas by layer: repository input/output schemas and tool-facing schemas"
+  - "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
+  - 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
+  - Allowlist public routes in the auth middleware with a synthetic anonymous
+    context
+  - 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
 examples:
   - input: Add a new domain entity to the template
-    output: Update schema, repository interfaces, server functions, routes, and AI tools
+    output: Update schema, repository interfaces, server functions, routes, and AI
+      tools
   - input: Swap MongoDB to Postgres
     output: Implement repository interface and switch factory without app-level changes
 content: |
@@ -130,6 +173,17 @@ content: |
   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.
+  28. JSON-only server functions and tools; HTTP file routes for everything else: `createServerFn` (and therefore AI tools) handles JSON queries and mutations only. Non-JSON responses — file downloads (CSV/JSON exports, PDFs), uploads, webhooks, and streaming — go through TanStack Start HTTP file routes using `server.handlers.GET|POST` under `src/routes/api/*.ts`. The `/api/chat` SSE endpoint (rule 14) is the canonical example. These file routes still reuse server-function wrappers or repository methods internally so the data path stays unified, but the transport layer is explicit about its shape.
+  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: 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. Reserve raw `<a>` for external URLs.
+  33. Public-route allowlist in auth middleware: `authMiddleware` declares a `PUBLIC_ROUTES` set (health checks, `.well-known`, static asset paths) for which it returns a synthetic anonymous `AuthContext` (user/userProfile set to an `Anonymous` sentinel) instead of throwing 401. Keeps the `AuthContext` shape consistent so downstream code, typings, and AI tools never branch on "maybe no user".
+  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). Add `feedbackIntegration({ autoInject: false })` and expose a header button that calls `openFeedback()`, giving users a controlled way to report issues with automatic user attribution.
+  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.
 
   ## Schema Boundaries
 

From f1889b05bfe6603772586838644e7d3d406ae0aa Mon Sep 17 00:00:00 2001
From: Carlos <carlos.martin-sanchez@mongodb.com>
Date: Wed, 22 Apr 2026 09:34:48 +0200
Subject: [PATCH 2/3] address PR review comments: remove rules 28 & 33, shorten
 rule 34, clean AGENTS.md

---
 .agents/skills/tanstack-fullstack-pattern/SKILL.md |  4 +---
 AGENTS.md                                          | 11 +----------
 skills/dist/tanstack-fullstack-pattern.md          |  6 ++----
 skills/registry.json                               |  5 +----
 skills/src/tanstack-fullstack-pattern.skill.yaml   | 10 +---------
 5 files changed, 6 insertions(+), 30 deletions(-)

diff --git a/.agents/skills/tanstack-fullstack-pattern/SKILL.md b/.agents/skills/tanstack-fullstack-pattern/SKILL.md
index 12ef857..1bfcd82 100644
--- a/.agents/skills/tanstack-fullstack-pattern/SKILL.md
+++ b/.agents/skills/tanstack-fullstack-pattern/SKILL.md
@@ -49,13 +49,11 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 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.
-28. JSON-only server functions and tools; HTTP file routes for everything else: `createServerFn` (and therefore AI tools) handles JSON queries and mutations only. Non-JSON responses — file downloads (CSV/JSON exports, PDFs), uploads, webhooks, and streaming — go through TanStack Start HTTP file routes using `server.handlers.GET|POST` under `src/routes/api/*.ts`. The `/api/chat` SSE endpoint (rule 14) is the canonical example. These file routes still reuse server-function wrappers or repository methods internally so the data path stays unified, but the transport layer is explicit about its shape.
 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: 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. Reserve raw `<a>` for external URLs.
-33. Public-route allowlist in auth middleware: `authMiddleware` declares a `PUBLIC_ROUTES` set (health checks, `.well-known`, static asset paths) for which it returns a synthetic anonymous `AuthContext` (user/userProfile set to an `Anonymous` sentinel) instead of throwing 401. Keeps the `AuthContext` shape consistent so downstream code, typings, and AI tools never branch on "maybe no user".
-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). Add `feedbackIntegration({ autoInject: false })` and expose a header button that calls `openFeedback()`, giving users a controlled way to report issues with automatic user attribution.
+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.
 
diff --git a/AGENTS.md b/AGENTS.md
index a71e571..9504419 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -77,7 +77,6 @@ This project uses [Mantine](https://mantine.dev/) as the primary UI framework.
 - **Avoid inline styles**: Use Mantine props or CSS Modules instead.
 - **Avoid `!important`**: Minimize its use.
 - **Dark mode**: All components must work in both light and dark color schemes.
-- **Hydration-safe color scheme reads**: When a component's rendered output depends on the active color scheme (e.g. swapping a logo variant, icon, or chart palette), read it with `useComputedColorScheme('light', { getInitialValueInEffect: true })` and gate any derived value behind a `useIsMounted()` (or `useHasHydrated()`) check. `useMantineColorScheme()` returns `'auto'` on the server and on the first client render; using it directly for render-affecting values produces hydration mismatches and a flash of the wrong asset.
 
 ### Icons
 
@@ -534,10 +533,6 @@ When `VITE_SENTRY_DSN` is set, the Sentry transport receives error-level logs al
 - **Rendering**: `renderWithProviders()` in `src/test-utils/renderWithRouter.tsx` wraps with MantineProvider.
 - **Convention**: Test files co-located as `*.test.ts` or `*.test.tsx`.
 
-### Test Factories (Zod Round-Trip)
-
-Define test factories (`makeTask()`, `makeUser()`, …) in `src/test-utils/factories.ts`. Every factory accepts a `Partial<T>` overrides bag, merges it with sensible defaults, and then **runs the result through `Schema.parse()`** before returning. This guarantees fixtures always match the schema — adding a required field or changing a validation rule surfaces as a failing factory call rather than a runtime crash deep in a test. Factories should not inline business logic (e.g. computing `healthStatus`); call the same pure helpers the repository uses, so fixture data and production data derive from one source of truth.
-
 ### E2E Tests (Playwright)
 
 - **Framework**: Playwright with Chromium.
@@ -546,10 +541,6 @@ Define test factories (`makeTask()`, `makeUser()`, …) in `src/test-utils/facto
 - **Convention**: Spec files in `e2e/` as `*.spec.ts`.
 - **Running**: `pnpm test:e2e` (reuses existing dev server or starts one with seed data).
 
-#### Dual `webServer` with in-process mock backend
-
-When the app calls an external service that is not part of the repository (a third-party API, a search service, a feature-flag backend), run two Playwright `webServer` entries side by side: (1) the app itself, (2) an in-process HTTP mock server that the app is pointed at via env var. The mock server exposes an internal `/__reset` endpoint that each test calls in `beforeEach` to clear recorded requests and restore default responses — this gives deterministic, isolated tests without Docker or external processes. Keep the mock server's fixtures typed against the same schemas the real client consumes so contract drift surfaces as a type error.
-
 ## 11. Linting and Formatting
 
 This project uses [Biome](https://biomejs.dev/) as the default linter and formatter — **not** ESLint or Prettier. The configuration lives in `biome.json` with `recommended` rules and minimal overrides. When adding new rules, prefer Biome's built-in `recommended` set and keep custom overrides to a minimum.
@@ -559,7 +550,7 @@ This project uses [Biome](https://biomejs.dev/) as the default linter and format
 - **Always use latest versions**: When adding dependencies, run `pnpm add <pkg>` without a version suffix so the package manager resolves the newest release. Never pin exact versions unless there is a known incompatibility.
 - **Keep dependencies up to date**: Run `pnpm outdated` to check for stale packages and `pnpm update` to align the lockfile with the latest compatible versions within current ranges.
 - **Major version upgrades are conscious decisions**: When `pnpm outdated` shows a major version bump, upgrade explicitly with `pnpm add <pkg>@latest`, then verify with `pnpm lint && pnpm test && pnpm build` before committing.
-- **After any dependency change**, run the full validation checklist (section 13) to catch regressions.
+- **After any dependency change**, run the full validation checklist (section 18) to catch regressions.
 
 ## 13. Public Runtime Config
 
diff --git a/skills/dist/tanstack-fullstack-pattern.md b/skills/dist/tanstack-fullstack-pattern.md
index 8f9e43f..7e56b0b 100644
--- a/skills/dist/tanstack-fullstack-pattern.md
+++ b/skills/dist/tanstack-fullstack-pattern.md
@@ -9,7 +9,7 @@
 - Documentation: https://github.com/carlosvin/tanstack-fullstack-ai-template/blob/main/skills/README.md
 - Status: stable
 - Supported tools: Windsurf [native, not yet verified], Cursor [copy, not yet verified], Claude Code [copy, not yet verified]
-- 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, Public-route allowlist on the auth middleware that returns a synthetic anonymous context for health checks and well-known paths
+- 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
 - ID: `tanstack-fullstack-pattern`
 - Version: `1.9.0`
 - Tags: tanstack-start, fullstack, architecture, interface-first, repository-pattern, ai-promptable
@@ -68,13 +68,11 @@ An interface-first fullstack architecture built on TanStack Start. The pattern d
 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.
-28. JSON-only server functions and tools; HTTP file routes for everything else: `createServerFn` (and therefore AI tools) handles JSON queries and mutations only. Non-JSON responses — file downloads (CSV/JSON exports, PDFs), uploads, webhooks, and streaming — go through TanStack Start HTTP file routes using `server.handlers.GET|POST` under `src/routes/api/*.ts`. The `/api/chat` SSE endpoint (rule 14) is the canonical example. These file routes still reuse server-function wrappers or repository methods internally so the data path stays unified, but the transport layer is explicit about its shape.
 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: 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. Reserve raw `<a>` for external URLs.
-33. Public-route allowlist in auth middleware: `authMiddleware` declares a `PUBLIC_ROUTES` set (health checks, `.well-known`, static asset paths) for which it returns a synthetic anonymous `AuthContext` (user/userProfile set to an `Anonymous` sentinel) instead of throwing 401. Keeps the `AuthContext` shape consistent so downstream code, typings, and AI tools never branch on "maybe no user".
-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). Add `feedbackIntegration({ autoInject: false })` and expose a header button that calls `openFeedback()`, giving users a controlled way to report issues with automatic user attribution.
+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.
 
diff --git a/skills/registry.json b/skills/registry.json
index a771c1d..be6e20e 100644
--- a/skills/registry.json
+++ b/skills/registry.json
@@ -61,8 +61,7 @@
         "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",
-        "Public-route allowlist on the auth middleware that returns a synthetic anonymous context for health checks and well-known paths"
+        "Single markdown artifact backing the help page, an AI tool, and the chat's recommended-prompt list"
       ],
       "triggers": [
         "fullstack template",
@@ -93,7 +92,6 @@
         "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",
-        "Auth middleware declares an explicit public-route allowlist that returns a synthetic anonymous AuthContext",
         "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"
       ],
@@ -111,7 +109,6 @@
         "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",
-        "Allowlist public routes in the auth middleware with a synthetic anonymous context",
         "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"
       ],
diff --git a/skills/src/tanstack-fullstack-pattern.skill.yaml b/skills/src/tanstack-fullstack-pattern.skill.yaml
index df3a595..80da4dd 100644
--- a/skills/src/tanstack-fullstack-pattern.skill.yaml
+++ b/skills/src/tanstack-fullstack-pattern.skill.yaml
@@ -61,8 +61,6 @@ capabilities:
     data
   - Single markdown artifact backing the help page, an AI tool, and the chat's
     recommended-prompt list
-  - Public-route allowlist on the auth middleware that returns a synthetic
-    anonymous context for health checks and well-known paths
 triggers:
   - fullstack template
   - TanStack Start project
@@ -97,8 +95,6 @@ constraints:
     into the document as window.__ENV__ before client JS runs
   - Internal navigation uses a project-local Link wrapper that preserves search
     params by default
-  - Auth middleware declares an explicit public-route allowlist that returns a
-    synthetic anonymous AuthContext
   - Every enum-ish field exposes a distinct-values AI tool so the assistant
     grounds filter arguments in real data
   - Router configures defaultStaleTime, defaultPreload, defaultPreloadStaleTime,
@@ -122,8 +118,6 @@ steps:
     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
-  - Allowlist public routes in the auth middleware with a synthetic anonymous
-    context
   - 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
@@ -175,13 +169,11 @@ content: |
   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.
-  28. JSON-only server functions and tools; HTTP file routes for everything else: `createServerFn` (and therefore AI tools) handles JSON queries and mutations only. Non-JSON responses — file downloads (CSV/JSON exports, PDFs), uploads, webhooks, and streaming — go through TanStack Start HTTP file routes using `server.handlers.GET|POST` under `src/routes/api/*.ts`. The `/api/chat` SSE endpoint (rule 14) is the canonical example. These file routes still reuse server-function wrappers or repository methods internally so the data path stays unified, but the transport layer is explicit about its shape.
   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: 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. Reserve raw `<a>` for external URLs.
-  33. Public-route allowlist in auth middleware: `authMiddleware` declares a `PUBLIC_ROUTES` set (health checks, `.well-known`, static asset paths) for which it returns a synthetic anonymous `AuthContext` (user/userProfile set to an `Anonymous` sentinel) instead of throwing 401. Keeps the `AuthContext` shape consistent so downstream code, typings, and AI tools never branch on "maybe no user".
-  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). Add `feedbackIntegration({ autoInject: false })` and expose a header button that calls `openFeedback()`, giving users a controlled way to report issues with automatic user attribution.
+  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.
 

From 1d1a7f0814bcfbfc3d0a6266ef8727785c73467c Mon Sep 17 00:00:00 2001
From: Carlos <carlos.martin-sanchez@mongodb.com>
Date: Wed, 22 Apr 2026 10:02:32 +0200
Subject: [PATCH 3/3] refine AGENTS guidance for controlled components and
 typing

---
 AGENTS.md | 27 +++++++++------------------
 1 file changed, 9 insertions(+), 18 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 9504419..d37c799 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -98,7 +98,7 @@ If your team prefers [`@tabler/icons-react`](https://tabler.io/icons) (the Manti
   - **Correct**: `const { filter } = Route.useSearch()` — state comes from the URL.
   - **Incorrect**: `const [filter, setFilter] = useState('all')` — state trapped in component.
 - **Internal Links**: Use TanStack Router's `Link` component for internal navigation.
-- **`satisfies` over `as`**: Do not use `as` to bypass type checking (`as never`, `as Record<string, unknown>`, `as SomeProps`). Prefer `as const satisfies SomeSchema` to validate a literal against a type without widening it, or fix the root type (update the interface, add a proper adapter, narrow with `in`/type guards). The **only** acceptable `as` casts are at clearly documented library boundaries where a third-party type is provably too strict, and each such cast must have an adjacent comment explaining why. For error inspection in `catch` blocks, use the `in` operator instead of casting `unknown` errors.
+- **`satisfies` over `as`**: Do not use `as` to bypass type checking (`as never`, `as Record<string, unknown>`, `as SomeProps`). Prefer `as const satisfies SomeSchema` for literals, and prefer schema runtime parsing (`Schema.parse`/`safeParse`) at boundaries where data comes from outside our type-safe system. Once data is inside our typed flow, preserve and propagate types end-to-end instead of re-casting or widening. The **only** acceptable `as` casts are at clearly documented library boundaries where a third-party type is provably too strict, and each such cast must have an adjacent comment explaining why. For error inspection in `catch` blocks, use the `in` operator instead of casting `unknown` errors.
   - **Good**: `if (typeof err === 'object' && err !== null && 'status' in err && typeof err.status === 'number') { … }`
   - **Bad**: `const raw = err as Record<string, unknown>; const status = raw.status as number`
 
@@ -550,7 +550,7 @@ This project uses [Biome](https://biomejs.dev/) as the default linter and format
 - **Always use latest versions**: When adding dependencies, run `pnpm add <pkg>` without a version suffix so the package manager resolves the newest release. Never pin exact versions unless there is a known incompatibility.
 - **Keep dependencies up to date**: Run `pnpm outdated` to check for stale packages and `pnpm update` to align the lockfile with the latest compatible versions within current ranges.
 - **Major version upgrades are conscious decisions**: When `pnpm outdated` shows a major version bump, upgrade explicitly with `pnpm add <pkg>@latest`, then verify with `pnpm lint && pnpm test && pnpm build` before committing.
-- **After any dependency change**, run the full validation checklist (section 18) to catch regressions.
+- **After any dependency change**, run the full validation checklist (section 17) to catch regressions.
 
 ## 13. Public Runtime Config
 
@@ -628,25 +628,16 @@ Some entities are sourced from upstream systems (a data warehouse export, a Goog
 
 Keep the overlay function pure and unit-tested — it is the single place where "what does the user see" is defined.
 
-## 16. Sortable Tables (Controlled Mode)
+## 16. Prefer Controlled Components
 
-The reusable `ApplicationListTable`-style component exposes both **uncontrolled** and **controlled** sort modes:
+Prefer controlled components in general. Keep data and state orchestration at the route level, and keep UI components focused on rendering and events.
 
-- **Uncontrolled** (default): the component manages its own sort state internally. Use for simple lists where sort does not need to persist.
-- **Controlled**: the consumer passes `sortBy`, `sortDirection`, and `onSortChange`. Use when sort state must live in the URL (deep-linking, shareable views) or when multiple tables need to share a sort.
+- **Loaders fetch data, components receive props**: Route loaders own data fetching and pass data down to page/components. Avoid embedding read-fetch lifecycle logic in reusable UI components.
+- **State lives in route search params**: Filters, sorting, pagination, active tabs, and modal state belong in validated route search params so URLs remain shareable and restorable.
+- **Controlled inputs are easier to test**: Components that receive value/state via props and emit callbacks (`value` + `onChange`) are simpler to unit test, easier to reuse, and easier to reason about than components with hidden internal state.
+- **Use uncontrolled only with clear justification**: Keep uncontrolled state for isolated UX details that are intentionally local and not part of route/application state.
 
-Sort logic lives in a pure `sortRows(rows, sortBy, direction)` function, unit-tested independently of React. Date columns sort chronologically; rows where the sort field is `null`/`undefined` always sink to the bottom regardless of direction so they don't interleave with valid data. Avoid ad-hoc per-column sort comparators — centralize them in one typed map keyed by column id.
-
-## 17. Autosave Forms with Concurrency Guards
-
-For detail panels that persist changes via PATCH as the user edits, two failure modes must be defended against:
-
-1. **Spurious mount PATCH**: A `useEffect` that "corrects" the initial value (e.g. clamps a number, normalizes a string) will fire on mount and trigger a PATCH before the user has done anything. Guard with a `hasMounted` ref that is `false` on the first run; only run the correction logic on subsequent runs. An even simpler approach is to make the initial state already-correct so no correction is needed.
-2. **Concurrent PATCH collisions**: A fast typist can produce two debounced PATCHes in flight at once, where the second overwrites the first. Track an `isPatching` ref; at the top of the debounced handler, bail out if `isPatching.current` is true (the pending patch bag still holds the changes). When the in-flight PATCH resolves, call `flushPatch.flush()` if the pending bag is non-empty so the next request fires immediately without an extra debounce wait. This gives "at most one PATCH in flight, immediate retry" semantics.
-
-Encapsulate both behaviors in a `useEntityPatch(id, options)` hook so form components only deal with "merge these fields"; the hook owns debouncing, in-flight tracking, pending-change coalescing, and toast feedback.
-
-## 18. Validate Changes
+## 17. Validate Changes
 
 Always verify changes with: