How every page tells Atlas what it is — with no hand-kept list

🛰️ Satellite — why a hand-maintained route list is a slow leak

The stakes: the product bet is many agents across many surfaces. For Atlas to navigate ("take me to firm members") and for the right scoped agent to mount ("this is a matter page → the Matter agent"), something must know every page exists and what each is for. The obvious move — keep a routes.ts array by hand — is a leak with a slow drip: a developer adds /settings/firm/billing, forgets the array, and Atlas is now confidently blind to a page that exists. Nothing fails. The map silently lies, and the agent's flagship power (hop to any page) quietly rots one route at a time.

The naive fix — "we'll grep the router at build time" — detonates on the second requirement: a route string tells Atlas a page exists, but not what it is for. /settings/firm/team is not self-evidently "where you invite people". So the map needs a natural-language description per page, written for the model — and the only place that can't drift from the page is the page itself. The real design makes the page the source of truth about itself: each page.tsx exports a co-located agentSurface descriptor, a codegen statically reads those exports into a complete manifest, and CI fails the build if a page forgets. Add a page → it registers itself → CI enforces it. The list can no longer drift, because there is no list — only the pages.

✈️ Airplane — two layers, never conflated

One analogy: the registry is the building directory in the lobby — complete, static, every floor and what's on it. The Current Page Context is the "you are here" dot — one location, live, useless once you move. Mixing them is the classic mistake; PRAMAAN keeps them apart by their nature: static + describes-everything → a generated module; live + current-only + holds functions → Zustand.

Layer 1 — the static manifest (build-time, complete)

Every workspace page.tsx exports an agentSurface: a durable key, which agent mounts, an i18n presenceKey for UI copy, a model-facing description, capabilities, and a kind (route / modal / drawer). A codegen walks the App Router and emits route-registry.ts. WHY by AST static extraction and never import: a page module pulls Clerk, env, data fetchers, and server-only code; importing it to read one constant would run all of that. The scanner reads the syntax tree — serializable data only.

Layer 2 — the Current Page Context (runtime, the active page only)

A Zustand store holds the active surface, the live view (filters / search / selection), a digest of what's visible, and the client-side tool handles Atlas can run on this page (set_filter, focus_matter). WHY never persisted: it holds functions, and HR-23 forbids writing functions or derived state to localStorage. It is ephemeral, per-tab, rebuilt on every mount — that is the whole point of a "live" layer.

The seam — a per-turn provider bag

Each turn the frontend serializes manifest + CPC digest + tool names + permissions into AgentSessionContext. WHY an open, versioned bag ({ version, providers }) and not a closed struct: that closed struct is the single rewrite-class failure the RFC flagged — tomorrow's deadlines provider would become a cross-repo contract rewrite. As a bag, it is a new key.

🔬 Microscope — the parts and the WHY on each

The page is the source of truth — one export

// src/app/[locale]/(workspace)/matters/page.tsx
export const agentSurface = {
  key: "matters",
  agent: "atlas",
  presenceKey: "AgentSurfaces.matters",
  description:
    "The matters list: every matter in the firm. Browse, search, filter " +
    "by status or type, open a matter, and start a new matter.",
  capabilities: ["browse matters", "filter by status or type", "start a new matter"],
  kind: "route",
  children: [{ key: "matters.add", agent: "atlas", kind: "modal", /* … */ }],
};

Auth / system / catch-all pages opt out explicitly: export const agentSurface = null; // no-agent: auth: Clerk sign-in. CI requires the reason comment so a null is a decision, not a forgotten export.

The freshness gate — drift becomes a red build

pnpm gen:routes writes the manifest; pnpm check:routes re-runs the extractor and fails if the committed file is stale, a key is duplicated, or a page is unclassified. It runs in CI and as a vitest test, so pnpm test catches drift locally before a push (LI-6). WHY both: a generator only prevents drift if its output is checked — an uncommitted regeneration is the same silent lie a hand-list was.

Orientation, not data

// What rides to the brain per turn — a digest, capped, no rows:
visible: { ids: ["M-0005","M-0006", …], count: 250, labels: ["Acme v State", …] }

The brain learns there are 250 matters and sees the first hundred ids — then fetches any detail through an authz-checked server tool that re-resolves permission on access. WHY a digest: the visible ids are already what the page authorized this user to see; shipping full rows would duplicate data the brain must re-authorize anyway, and balloon every turn.

Acceptance criteria → evidence

Verification

• pnpm check:routes → 26 surfaces fresh
• pnpm test → 695 passed (incl. 32 new: registry freshness, navigation, digest caps, session bag, store ownership)
• pnpm lint → 0 errors · pnpm exec tsc --noEmit → clean · pnpm build → success

One-sentence recall: the page describes itself, codegen makes the description complete, CI makes it honest, and the live store says where "here" is — the agent never reads a hand-kept list and never sees a full row.

Files changed

58 file(s), +2214 / -0 lines