diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index cef9903d..39a5f75f 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,130 +1,6 @@
 Status: Active
-Last updated: 2026-01-03
+Last updated: 2026-09-22
 
-# Cherry • AI Agent Playbook
+# Cherry • AI Agent Instructions
 
-Read this alongside `AGENTS.md`, `docs/legal-constraints.md`, `docs/cherry-vision.md`, `docs/cherry-vine.md`, `docs/wallet-pass.md`, and `docs/api.md`. Never frame Cherry as a payment card/terminal; `/api/scan` is advisory with telemetry; `/api/wallet/cherry-pass` returns 501 until certs and the feature flag exist.
-
-## GitHub / PR Operating Rule
-From now on, the agent must not treat direct commits to `main` as the normal workflow.
-
-The default development flow is:
-
-1. Start from updated `main`.
-2. Create a focused branch.
-3. Implement the requested change on that branch.
-4. Run the relevant verification commands.
-5. Commit the change with a clear conventional commit message.
-6. Push the branch.
-7. Open or prepare a pull request into `main`.
-8. Do not merge unless explicitly instructed.
-
-Canonical command flow:
-
-```bash
-git checkout main
-git pull --ff-only
-git checkout -b <type>/<short-description>
-
-# implement changes
-
-git status --short
-npm run check
-npm test
-npm run build
-
-git add .
-git commit -m "<type>: <summary>"
-git push -u origin <type>/<short-description>
-```
-
-The pull request must include:
-
-```md
-## Summary
-- what changed
-
-## Testing
-- commands run
-- results
-
-## Risk
-- changed domains
-- possible regressions
-```
-
-Hard rules:
-
-- Never commit directly to `main` unless the user explicitly says to.
-- Never merge a PR unless the user explicitly says to.
-- Never skip verification silently.
-- If verification fails, stop and report the failure.
-- If the working tree is dirty before starting, inspect it first and do not overwrite unrelated user changes.
-- If a branch already exists, reuse it only if it matches the requested task; otherwise create a new branch.
-- Each PR should represent one coherent change. Do not bundle unrelated fixes.
-- Prefer `squash and merge` when the user later asks to merge.
-
-This is now the default operating model for all future repo work.
-
-## Current behavior (enforced / in code)
-- Engine decisions run through `safeSolveDecisionForUser` / `safeSolveDecisionForWorld` with deterministic inputs and explicit `nowMs`.
-- `/api/scan` logs `DecisionEvent` telemetry but does not create sessions or ledger entries.
-- Zod schemas live in `lib/schemas/*` and are parsed via `parseJsonBody` from `lib/validation.ts`.
-- Prisma is instantiated only in `lib/prisma.ts` and consumed via runtime adapters.
-
-## Runtime & Layout
-- Next.js 16 App Router + React 19 (React Compiler). Default to server components; place interactive hooks in `app/<route>/client.tsx` gated with `'use client'`.
-- Tailwind v4 tokens live in `app/globals.css`. Prefer semantic CSS vars and canonical utilities.
-- `app/layout.tsx` is the shell: Geist fonts, `AuthProvider`, `SidebarNav`, `UserMenu`.
-
-## Auth & Session Flow
-- NextAuth config: `app/api/auth/[...nextauth]/route.ts` (PrismaAdapter + Email/Google + dev credentials). Session callback stamps `session.user.id`.
-- Server handlers must import `withUser` from `lib/with-user.ts` to enforce auth and surface `userId`. Never read cookies directly.
-- Client code uses `useSession()` and reacts to `401` by calling `signIn()`.
-
-## Data & Money Rules (see `docs/legal-constraints.md`)
-- Prisma models: `prisma/schema.prisma` (Bucket/Card/RewardRule/RecommendationSession/CherryPointLedger/etc.). Run `npx prisma migrate dev --name <tag>` then `npx prisma generate` after schema edits.
-- Monetary values are integer cents. Convert from dollars before hitting APIs; render via `formatCents` helpers.
-- Buckets: `spentCents` is incremented once on session confirm after `ensureBucketFresh`; `currentAmount` is legacy and unused post-create.
-- Bucket balances must be derived via canonical runtime helpers; do not recompute remaining amounts ad-hoc.
-- `currentAmount` is legacy-only and must not be treated as authoritative input.
-- Bucket mutation must occur only after freshness is ensured.
-- Always import Prisma from `@/lib/prisma`; never create ad-hoc clients.
-
-## Simulation Engine & APIs
-- Engine: `lib/engine.ts` is canonical (MCC-aware); invariants in `lib/engine-invariants.ts`. Do not fork logic in routes.
-- All decision-making surfaces must route through `safeSolveDecisionForUser` / `safeSolveDecisionForWorld`; no route may implement decision logic inline.
-- Validation: All engine-touching APIs (`/api/simulate`, `/api/scan`, `/api/sessions`, `/api/vine/order`) must use Zod schemas in `lib/schemas/*` plus `parseJsonBody`.
-- Core APIs:
-  - `/api/simulate` — one-off simulation: returns verdict + card/bucket suggestion, records a `SimulatedTransaction`, does **not** mutate buckets.
-  - `/api/scan` — advisory “scan before pay”: runs the engine, MCC-aware, allows zero-amount snapshots; logs `DecisionEvent` telemetry but does not create sessions/ledger rows.
-  - `/api/sessions` — creates a `RecommendationSession` (source `APP_SCAN`) with orderToken/expiry and offered points.
-  - `/api/sessions/[id]/confirm` — blocks expired/duplicate claims, freshens bucket, increments `spentCents` once, writes PENDING ledger rows, flags anomalies (amount/time/card).
-  - `/api/sessions/[id]/verify` — simulated verification: flips ledger rows to POSTED/REVOKED, updates anomalies.
-  - `/api/vine/order` — Vine ingest (dev-only): accepts terminal events or `OrderContext`, enforces freshness window, runs engine, creates session with orderToken, returns decision.
-  - `/api/wallet/cherry-pass` — gated by `CHERRY_WALLET_PASS_ENABLED` + Apple env; returns 501 JSON when disabled; generates `storeCard` pass when fully configured.
-
-## Seed, MCC ingest, and Admin flows
-- MCC ingest: `npm run ingest:mcc [path]` → `scripts/ingest-mcc.mts`.
-- Demo seeding: `npm run seed:demo` → `scripts/seed-demo.mts` (also via `/api/seed-demo`).
-- Admin tools (local-only): `/admin` links to `/api/admin/health`, `/api/health`, and dev-only seed/diagnostic surfaces.
-- Integrity: `scripts/audit-integrity.mts` flags session/ledger anomalies.
-
-## UI Conventions
-- Server components fetching data should use `{ cache: 'no-store' }` and await async `params`.
-- Client forms: uppercase categories, confirm destructive actions, convert dollars to cents, call `router.refresh()`.
-- Vine simulator: clearly mark “simulated Vine device” vs “manual scan”; hide confirm flows when verdict is `INSUFFICIENT_DATA`.
-
-## Product & Hardware Context
-- `docs/cherry-vision.md` + `docs/legal-constraints.md`: Cherry is a spending copilot, not a card/terminal.
-- `docs/cherry-vine.md`: Vine is a context beacon (merchant + amount), never a payment device.
-- Recommendation sessions + verification glue Cherry Pass, Vine, and any future bank/receipt integrations—reuse them rather than inventing new reward trackers.
-RecommendationSession + CherryPointLedger form the single spine for all reward and verification flows; do not introduce parallel tracking systems.
-
-## Future/Target behavior (explicitly speculative)
-- Add new API surfaces only after updating `docs/api.md` and relevant guardrails.
-
-## Related docs
-- `AGENTS.md`
-- `docs/api.md`
-- `docs/ci-and-guardrails.md`
+Read `AGENTS.md` at the repo root. It is the single operating contract (legal framing, invariants, verification, branch/PR flow). Architecture navigation starts at `docs/architecture/index.md`. This file intentionally adds nothing.
diff --git a/.gitignore b/.gitignore
index f91f76bf..0035da53 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,7 +23,6 @@ workspace/
 
 # misc
 .DS_Store
-*.pem
 cookies.txt
 
 # editor settings
@@ -56,6 +55,9 @@ certs/
 *.pem
 *.pkpass
 
+.evidence/*
+!.evidence/.gitkeep
+
 # Local temp + Node compile cache
 .tmp/
 .cherry-tmp/
@@ -68,6 +70,5 @@ paste.txt
 abandoned_subsystems.md
 api_inventory.md
 architecture_map.md
-scripts/audit/full-checkout-audit.mts
 workspace_audit.md
 repo_index.json
diff --git a/AGENTS.md b/AGENTS.md
index d39e113d..aaddebc8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,190 +1,113 @@
 Status: Active
-Last updated: 2026-01-29
+Last updated: 2026-09-22
 
-# Cherry Agents — Canonical Operating Guide
+# Cherry Agents — Operating Contract
 
-This file is the operating contract for humans and agents working in this repo. It is authoritative after CI/workflows and guardrail registries. If something conflicts, fix the lower authority, not the higher.
+The single operating contract for humans and agents working in this repo. It is navigational: it tells you what must never change, where things live, how to verify, and how to hand off. Detail lives in the linked docs, never duplicated here.
 This guide defers to docs/doctrine.md for all execution invariants and enforcement rules.
 
-## Authority Ladder (highest to lowest)
+## Authority ladder (highest to lowest)
 1. `package.json` scripts + `.github/workflows/*` (actual behavior)
-2. Guardrail registries and tests (`scripts/guardrails/*`, `tests/guardrails/*`)
-3. `AGENTS.md` (this file)
-4. `docs/*` (specs and explanations)
-5. Everything else (notes, drafts, marketing)
-
-## Product Identity and Legal Guardrails (non-negotiable)
-- Cherry is a real-time spending copilot, not a card, proxy, processor, or payment terminal.
-- Cherry never fronts transactions, holds funds, or touches payment rails.
-- Cherry Vine is a context beacon (merchant + amount + timestamp), not a reader or terminal.
-- Cherry Pass is a storeCard-style advisory pass; it is not a payment instrument.
-- Recommendation sessions and Cherry Points are advisory and sandboxed.
-
-Forbidden framings: “fronting card,” “proxy BIN,” “tap to pay with Cherry,” “Cherry terminal,” “payment card.”
-
-## Current behavior (enforced / in code)
-- Core loop: Observe → Evaluate → Recommend → Reward.
-- `/api/scan` runs the engine and logs a `DecisionEvent` for telemetry; it does not create sessions or ledger rows.
-- Sessions + ledger persistence happen via `/api/sessions` and confirm/verify flows.
-- Vine ingest (`/api/vine/order`) is dev-only and context-only; no payment rails.
-- Wallet pass (`/api/wallet/cherry-pass`) returns 501 unless fully configured and explicitly enabled.
-- Engine is deterministic and pure: it consumes `EngineState` + `EngineContext` and emits ranked decisions.
-
-## Determinism and Time Injection
-- Do not call `Date.now()` or `new Date()` in `lib/engine/*` or `lib/authority/*`.
-- Time enters at boundaries (API routes, adapters) and is passed in as `nowMs`.
-- Guardrails enforce deterministic core behavior.
-
-## SSR / Rendering Determinism
-- Server components must not call `Date.now()`, `Math.random()`, or locale-dependent formatting.
-- Pages must render from a single data snapshot; no structural changes on hydration.
-- Empty/data states must share a stable outer container.
-
-## Data and DB Boundaries
-- Prisma client must only be instantiated in `lib/prisma.ts` and consumed by runtime adapters.
-- Engine and authority logic must not import Prisma or `@prisma/client`.
-- Zod schemas live in `lib/schemas/*`; parse via `parseJsonBody` from `lib/validation.ts`.
-- Stateful API routes must use `withUser` and return `401` for unauthenticated requests.
-- Bank ingest invariants:
-  - `BankTransaction.id` is internal and never set from ingest data.
-  - Idempotency key is `(userId, externalId)` only.
-  - All ingest writes go through `upsertBankTransactions`.
-
-## Bucket Runtime Invariants
-- Bucket math must flow through `lib/buckets-runtime.ts`.
-- Authoritative fields: `budgetAmount`, `spentCents`.
-- Derived only: `committedCents`, `remainingCents`.
-- `currentAmount` is legacy-mirror only; never authoritative.
-
-## Offline Evaluator (hard boundary)
-- Evaluator code is read-only with respect to Sessions, Ledger, Buckets.
-- Outputs are diagnostic only and must never affect user-facing decisions.
-- Must call `assertOfflineEvaluatorModelsReady()` before DB access.
-- Gate execution behind `CHERRY_OFFLINE_EVALUATOR_ENABLED`.
-- Never hard-code runIds; derive via `defaultRunIdForUser(userId, now)`.
-
-## Guardrails Policy
-- Guardrails are registered in `scripts/guardrails/registry.mts` and must run via `npm run check`.
-- Guardrails are unaddressable by path; run them only via `npm run check`.
-- Guardrails must be deterministic and side-effect free; no network or DB I/O.
-- Do not weaken guardrail severity or bypass guardrail tests.
-
-## DB Truth Surface (hard boundary)
-- DB truth scripts and DB tests may assert only: existence, impossibility, conservation.
-- Allowed: constraint exists, duplicate key fails, FK missing parent fails, NOT NULL fails, count stays 1.
-- Forbidden: preferred outcomes, query plans, performance targets, business logic behaviors, ordering.
-- Rule of thumb: if the DB could allow multiple valid outcomes, do not assert a preference in DB truth.
-
-## Script Runner Contract
-- Repo is ESM by extension. `.mts` is allowed only under `scripts/`.
-- `.mts` scripts must be run via `npm run ts:esm -- <script>`.
-- `.ts` files under `scripts/` must not use ESM syntax.
-- Script imports must use runtime extensions (`.js`/`.mjs`/`.cjs`); no `@/` aliases.
-
-## CI Truth and DB Posture
-- `.github/workflows/ci.yml` runs `npm ci` then `npm run ci:verify`.
-- Tests run with Prisma mocked; CI green does not fully prove DB behavior.
-- `.github/workflows/env-checks.yml` provisions Postgres and runs `check:env` plus `test:db`.
-
-## Change Protocol
-- Keep API handlers thin; move domain logic into `lib/`.
-- Use `safeSolveDecisionForWorld` / `safeSolveDecisionForUser` for engine decisions.
-- For schema changes:
-  - `npx prisma format`
-  - `npx prisma migrate dev --name <desc>`
-  - `npx prisma generate`
-  - Run `npm run check`, `npm test`, and `npm run build`.
-- For docs: add `Status` + `Last updated`, split Current vs Future, add Related docs.
-
-## GitHub / PR Operating Rule
-From now on, the agent must not treat direct commits to `main` as the normal workflow.
-
-The default development flow is:
-
-1. Start from updated `main`.
-2. Create a focused branch.
-3. Implement the requested change on that branch.
-4. Run the relevant verification commands.
-5. Commit the change with a clear conventional commit message.
-6. Push the branch.
-7. Open or prepare a pull request into `main`.
-8. Do not merge unless explicitly instructed.
-
-Canonical command flow:
+2. Guardrail registries and tests (`scripts/guardrails/*`, `tests/node/guardrails/*`)
+3. `AGENTS.md` (this file) and the scoped `AGENTS.md` files in `lib/engine/`, `app/api/`, `scripts/`
+4. `docs/doctrine.md`, then `docs/architecture/*`, then the rest of `docs/*`
+5. Everything else
+
+If two levels conflict, fix the lower one. `CLAUDE.md`, `.github/copilot-instructions.md`, and `CONTRIBUTING.md` point here and add nothing.
+
+## What Cherry is (never changes)
+- Cherry is a real-time spending copilot: Observe → Evaluate → Recommend → Reward. It is not a card, proxy, processor, or payment terminal, and never fronts transactions, holds funds, or touches payment rails.
+- Cherry Vine is a context beacon (merchant + amount + timestamp). Cherry Pass is a storeCard-style advisory pass. Recommendation sessions and Cherry Points are advisory and sandboxed.
+- Forbidden framings: "fronting card", "proxy BIN", "tap to pay with Cherry", "Cherry terminal", "payment card". Full text: `docs/legal-constraints.md`, `docs/cherry-vision.md`.
+
+## Where things live
+Read `docs/architecture/index.md` (2 minutes), then the one page you need. The map is machine-readable in `scripts/guardrails/domains.manifest.json` and enforced by `check:domain-boundaries`.
 
 ```bash
-git checkout main
-git pull --ff-only
-git checkout -b <type>/<short-description>
+npm run report:domain-impact -- <path...>   # owner domain, allowed imports, dependents, tests, docs, invariants
+npm run report:domain-impact                # same for everything changed vs main
+```
+
+Layers, top to bottom, imports flow downward only (`docs/architecture/dependency-rules.md`):
+- surface: `app/(user)`, `app/(dev)`, `components/`
+- service: `app/api/<x>/route.ts` + `lib/<x>/` per capability (sessions, evaluation, autopilot, vine, wallet, buckets, cards, bank, income, daily-state, evaluator, identity, observability)
+- runtime: `lib/adapters/runtime/` (the `World`), `lib/prisma.ts`
+- core: `lib/engine/`, `lib/authority/`, `lib/accounting/`, `lib/adapters/*.ts`, `lib/schemas/`, `lib/config/`, shared helpers
+
+## Hard invariants (enforced by guardrails unless marked "documented")
+- Engine and authority are pure: no `Date`, no Prisma, no HTTP. Time enters at routes as `nowMs`. `EngineInput` (`lib/engine/input/EngineInput.ts`) is the only input contract. Engine-sensitive changes need a version bump in `lib/engine/version.ts` plus a separate `chore(engine-freeze)` commit; an engine feature freeze is active (`docs/engine-roadmap.md`). See `lib/engine/AGENTS.md`.
+- Guardrail scripts never import `lib/**`; they read source text.
+- Prisma is instantiated only in `lib/prisma.ts`. Engine/authority may not import it. Services may import it directly today; runtime adapters are the target (documented).
+- Money is integer cents. Bucket math flows through `lib/buckets-runtime.ts`; `budgetAmount` and `spentCents` are authoritative, `committedCents`/`remainingCents` derived, `currentAmount` legacy mirror (documented).
+- Routes: auth via `resolveUserContext` (or the `withUser` wrapper, used by 9 routes), body via `parseJsonBody` + a `lib/schemas/*` Zod schema, then one service call. `/api/scan` is stateless (engine + `DecisionEvent` only). Sessions and ledger persist only via `/api/sessions` and its confirm/verify. See `app/api/AGENTS.md`.
+- Bank ingest: `BankTransaction.id` never comes from input; idempotency key is `(userId, externalId)`; all writes go through `upsertBankTransactions` (documented).
+- Offline evaluator is read-only over Sessions/Ledger/Buckets, gated by `CHERRY_OFFLINE_EVALUATOR_ENABLED`, must call `assertOfflineEvaluatorModelsReady()`, derives runIds via `defaultRunIdForUser` (documented).
+- DB truth tests assert only existence, impossibility, conservation. Never preferred outcomes, ordering, or performance.
+- Server components: no `Date.now()`, `Math.random()`, or locale formatting; one data snapshot per render.
+- Scripts: `.mts` only under `scripts/`, run via `npm run ts:esm -- <script>`, registered in `scripts/execution/registry.mts` or `scripts/guardrails/registry.mts`. See `scripts/AGENTS.md`.
+- Never weaken a guardrail, its severity, or its fixtures without changing the matching test in `tests/node/guardrails/` on purpose.
+
+## Bootstrap
+```bash
+nvm use                               # Node 24.15.0 (.nvmrc); engine-strict is on
+npm ci                                # postinstall: patch-package + prisma generate
+export CHERRY_TMP_ROOT="$HOME/.cherry-tmp"; mkdir -p "$CHERRY_TMP_ROOT"; chmod 700 "$CHERRY_TMP_ROOT"
+export CHERRY_VINE_SIGNATURE_MODE=enforce   # build asserts production config without it
+```
+`rg`, `git`, `node` must be on PATH. `npm run dev` needs `DATABASE_URL` (predev runs `check:db-ready`). Env contract: `.env.example`, `docs/env-policy.md`; never commit `.env*`.
 
-# implement changes
+## Verification levels
+| Level | Command | Use |
+| --- | --- | --- |
+| FAST | one test file (command in `docs/architecture/testing.md`) | while editing |
+| DOMAIN | `npm run report:domain-impact`, then `npm run check:tests:node -- --filter=<globs>` / `npm run check:tests:next -- --filter=<globs>` | before the full gate; output is labelled FILTERED and is not evidence of correctness |
+| FULL | `npm run check && npm test && npm run build` | required before every commit you push; identical to `npm run ci:verify` |
+| DB | `npm run test:db` (real Postgres) | schema or migration changes |
 
-git status --short
-npm run check
-npm test
-npm run build
+`check` = core guardrails + lint + typecheck + `tests/node` + `tests/next`. `npm test` runs every `tests/**/*.test.*` except `tests/db`. Tests run with Prisma mocked; CI green does not prove DB behavior. CI (`.github/workflows/ci.yml`) runs `check:guardrails`, `check:tests:node`, `check:tests:next`, then `ci:verify`; `env-checks.yml` adds Postgres, migrations, `check:env`, `test:db`.
 
-git add .
-git commit -m "<type>: <summary>"
+## Schema changes
+`npx prisma format && npx prisma migrate dev --name <desc> && npx prisma generate`, then FULL and DB levels. Follow `docs/schema-evolution.md` (`check:schema-evolution`, `check:schema-breaking-plan`). Coordinate migrations; two agents must not add migrations in parallel.
+
+## Workflow (default for all repo work)
+```bash
+git checkout main && git pull --ff-only
+git checkout -b <type>/<short-description>      # feat/ fix/ chore/ docs/
+# implement; keep to one coherent change; no unrelated cleanup
+npm run check && npm test && npm run build
+git add . && git commit -m "<type>(<scope>): <summary>"
 git push -u origin <type>/<short-description>
 ```
+- Never commit to `main`. Never merge unless explicitly told; prefer squash and merge when asked.
+- If the tree is dirty before you start, inspect it and do not overwrite unrelated changes.
+- Reuse an existing branch only if it matches the task.
+- Never skip verification silently. If it fails, stop and report the failure with output.
+- Commit message prefixes with meaning to guardrails: `engine:`, `guardrails:`, `docs:`, `tests:`, `chore(engine-freeze):` are checked by `check:change-isolation` when `CHERRY_COMMIT_MESSAGE` is set; conventional `feat(scope):`/`fix(scope):`/`chore:` are used everywhere else.
 
-The pull request must include:
-
+PR body:
 ```md
 ## Summary
 - what changed
-
 ## Testing
-- commands run
-- results
-
+- commands run, results (paste failures verbatim)
 ## Risk
-- changed domains
-- possible regressions
+- domains touched (from report:domain-impact), possible regressions
 ```
 
-Hard rules:
-
-- Never commit directly to `main` unless the user explicitly says to.
-- Never merge a PR unless the user explicitly says to.
-- Never skip verification silently.
-- If verification fails, stop and report the failure.
-- If the working tree is dirty before starting, inspect it first and do not overwrite unrelated user changes.
-- If a branch already exists, reuse it only if it matches the requested task; otherwise create a new branch.
-- Each PR should represent one coherent change. Do not bundle unrelated fixes.
-- Prefer `squash and merge` when the user later asks to merge.
-
-This is now the default operating model for all future repo work.
-
-## PR Checklist (what each command proves)
-- `npm run check` → guardrails + lint + typecheck are green.
-- `npm test` → unit/guardrail tests green (Prisma mocked by loader).
-- `npm run build` → Next.js build passes.
-- `npm run ci:verify` → mirrors CI entrypoint.
-- If schema changed: migrations apply and Prisma client is regenerated.
-
-## Drift Policy
-- If docs conflict with code, update docs to match reality unless legal constraints require a code fix.
-- If code conflicts with legal constraints, fix code and add guardrail/tests rather than weakening docs.
-- Do not update guardrail fixtures unless you also update the corresponding tests intentionally.
-
-## Product-Ready Definition (Cherry terms)
-Cherry is product-ready for a pilot when:
-- Engine decisions are deterministic and stable across core surfaces.
-- Sessions + ledger lifecycle is reliable (no double-award, clear pending/posted rules).
-- Vine and Wallet remain advisory-only and correctly gated.
-- Observability (DecisionEvent logging, guardrails) is in place and CI is green.
-
-## Future/Target Behavior (explicitly speculative)
-- Full bank ingest verification and automated ledger posting beyond current stubs.
-- Enforced Vine signature lifecycle and expanded device coverage.
-- Marketing and user-facing surfaces under `app/(marketing)` and richer user shell routes.
+## Parallel agents
+- One task = one branch = one domain where possible. Shared contracts (`lib/schemas/*`, `lib/engine/input/*`, `domains.manifest.json`, guardrail registries, `prisma/schema.prisma`, `engine-freeze.policy.json`) are serialized: agree the contract change first, land it, then parallelize consumers.
+- Use separate worktrees or clones; never share a working tree.
+- A task boundary states: objective, inputs, owned files, allowed dependencies, constraints, acceptance criteria, verification, expected output.
+
+## Definition of done and handoff
+Done means: the change is on a pushed branch; FULL verification ran and passed (or the exact failure is reported); docs that describe changed behavior are updated (`Status` + `Last updated`, Current vs Future sections); domain manifest updated if files were added; a PR is opened or prepared with the body above; nothing merged.
+Unfinished work: leave the branch pushed, list in the PR body what is done, what is not, what blocked you, and the next command to run.
+
+## Drift policy
+- Docs conflict with code: fix the docs, unless legal constraints require a code fix.
+- Code conflicts with legal constraints: fix the code and add a guardrail or test.
+- Guardrail weaker than documented: fix the guardrail, not the doc.
 
 ## Related docs
-- `docs/legal-constraints.md`
-- `docs/cherry-vision.md`
-- `docs/ci-and-guardrails.md`
-- `docs/guardrails.md`
-- `docs/script-standards.md`
-- `docs/repo-structure.md`
+- `docs/architecture/index.md`, `docs/doctrine.md`, `docs/legal-constraints.md`, `docs/cherry-vision.md`
+- `docs/ci-and-guardrails.md`, `docs/guardrails.md`, `docs/script-standards.md`, `docs/schema-evolution.md`
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..f1db477c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,5 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+Read `AGENTS.md`. It is the only operating contract for this repo (commands, invariants, workflow, verification). Architecture navigation starts at `docs/architecture/index.md`. Nothing here overrides either.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 595addda..4d2496a6 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,114 +1,29 @@
 Status: Active
-Last updated: 2026-01-03
+Last updated: 2026-09-22
 
 # Contributing to Cherry
 
-## Current behavior (enforced / in code)
-- CI runs `npm run ci:verify` (check + test + build) on pushes and PRs.
-- Guardrails are enforced via `npm run check` and registries in `scripts/guardrails/*`.
-
-## Information Architecture (source of truth)
-- Surface placement is defined in `docs/information-architecture.md` and the canonical route list in `docs/routes-map.md`.
-- Add or move routes only after updating those docs, and keep marketing, user, and dev console pages under their respective `(marketing)`, `(user)`, or `(dev)` route groups.
-
-## Workflow and Branch Policy
-
-### Actors
-
-- **Human contributors**
-  - May create feature branches (`feat/*`), bugfix branches (`fix/*`), and chore branches (`chore/*`).
-  - Must raise pull requests into `main`.
-  - Must not push directly to `origin/main`.
-
-- **AI Agents**
-  - Follow `AGENTS.md` for operational constraints.
-  - Must not rewrite history (`git reset --hard`, `git push --force`).
-  - Must not discard or revert existing worktree changes unless explicitly asked.
-
-- **CI**
-  - Enforces that `main` stays green by running `npm run ci:verify` on every push and pull request.
-
-### Branch Naming
+Operating rules for everyone (humans and agents) are in `AGENTS.md`: bootstrap, verification levels, branch and PR flow, hard invariants. This file adds only the human-workflow details not covered there.
 
+## Branch naming
 - `feat/<short-description>` for new features.
 - `fix/<short-description>` for bug fixes.
 - `chore/<short-description>` for maintenance and refactors.
+- `docs/<short-description>` for documentation-only changes.
 
-### Main Branch and CI Rules
-
-- `main` must pass the full gate:
-  - `npm run ci:verify` (composite: check + test + build)
-- If CI is red on `main`, no new feature work is allowed until `main` is green again.
-- Fixes to restore green must be done in focused changes that only repair CI, not introduce new features.
-
-## AI Agent Preconditions
-
-Before any AI agent runs on this repository:
-
-- Note the current branch and `git status --porcelain`; do not assume a clean worktree.
-- Do not discard unrelated changes; coordinate with the user if conflicts exist.
-- Keep changes scoped and justified; avoid broad refactors.
-
-### Non-negotiable preconditions
-
-- Agents must not treat direct commits to `main` as the normal workflow.
-- The default agent workflow is:
-  1. Start from updated `main`.
-  2. Create a focused branch.
-  3. Implement the requested change on that branch.
-  4. Run the relevant verification commands.
-  5. Commit the change with a clear conventional commit message.
-  6. Push the branch.
-  7. Open or prepare a pull request into `main`.
-  8. Do not merge unless explicitly instructed.
-- Canonical command flow:
-  ```bash
-  git checkout main
-  git pull --ff-only
-  git checkout -b <type>/<short-description>
-
-  # implement changes
-
-  git status --short
-  npm run check
-  npm test
-  npm run build
-
-  git add .
-  git commit -m "<type>: <summary>"
-  git push -u origin <type>/<short-description>
-  ```
-- The PR must include:
-  - `## Summary` — what changed
-  - `## Testing` — commands run and results
-  - `## Risk` — changed domains and possible regressions
-- Never commit directly to `main` unless the user explicitly says to.
-- Never merge a PR unless the user explicitly says to.
-- Never skip verification silently.
-- If verification fails, stop and report the failure.
-- If the working tree is dirty before starting, inspect it first and do not overwrite unrelated user changes.
-- If a branch already exists, reuse it only if it matches the requested task; otherwise create a new branch.
-- Each PR should represent one coherent change. Do not bundle unrelated fixes.
-- Prefer `squash and merge` when the user later asks to merge.
-- Agents must not proceed if the worktree is dirty without explicit user approval.
-- Agents must keep tasks bounded (≤2 commits) and avoid broad refactors.
-- If preconditions are not met, agents must stop and report the issue instead of modifying files.
-
-## Engine Changes and Freeze Policy
-
-See `docs/engine-roadmap.md` for current engine freeze status.
-
-While the freeze is active:
-- PRs that change engine semantics under `lib/engine/**`, `lib/engine.ts`, `lib/engine/legacy.ts`, `lib/vine/**`, `lib/scan-types.ts`, `lib/engine-invariants.ts`, or engine APIs in `app/api/simulate/**`, `app/api/simulations/**`, `app/api/vine/**`, and `app/api/autopilot/**` are forbidden except documented emergency bugfix exceptions listed in `docs/engine-roadmap.md`.
+## Main branch and CI
+- `main` must stay green under `npm run ci:verify`; `.github/workflows/ci.yml` runs it on every push and PR.
+- If CI is red on `main`, no new feature work lands until it is green again. Fixes that restore green are focused and add no features.
+- Route and surface placement follows `docs/information-architecture.md` and `docs/routes-map.md`; keep pages under `app/(user)`, `app/(dev)`, or `app/api`.
 
-Any PR that touches engine code:
-- Must apply the `engine-change` label.
-- Must include a link to the corresponding exception entry in `docs/engine-roadmap.md` when opened during a freeze.
+## Engine changes and the freeze
+`docs/engine-roadmap.md` holds the freeze status (ACTIVE) and exception log. While the freeze is active, PRs that change engine semantics under `lib/engine/**`, `lib/vine/**`, `lib/scan-types.ts`, `lib/engine-invariants.ts`, or the engine-facing routes (`app/api/{simulate,simulations,vine,autopilot}/**`) need a dated exception entry there. Any engine PR:
+- applies the `engine-change` label;
+- follows the version-bump and `chore(engine-freeze)` commit protocol in `docs/doctrine.md` and `lib/engine/AGENTS.md`.
 
-## Future/Target behavior
-- Add a guardrail that enforces the engine freeze policy if it becomes more formal.
+## History
+- Never rewrite shared history (`git push --force`, `git reset --hard` on shared branches).
+- Never discard someone else's working-tree changes.
 
 ## Related docs
-- `AGENTS.md`
-- `docs/ci-and-guardrails.md`
-- `docs/engine-roadmap.md`
+- `AGENTS.md`, `docs/ci-and-guardrails.md`, `docs/engine-roadmap.md`, `docs/architecture/index.md`
diff --git a/DOC_REWRITE_TASK.md b/DOC_REWRITE_TASK.md
deleted file mode 100644
index d77d997a..00000000
--- a/DOC_REWRITE_TASK.md
+++ /dev/null
@@ -1,65 +0,0 @@
-Status: Active
-Last updated: 2026-01-03
-
-# Doc Rewrite Task — Cherry
-
-This file is a temporary working spec for aligning all non-fixture documentation with code reality and guardrails. It exists to keep the rewrite orderly and verifiable.
-
-## Current behavior
-- This document guides the in-repo documentation rewrite effort and is not a product contract.
-
-## Comprehension Gates (must pass before edits)
-1. `npm ci`
-2. `npm run check`
-3. `npm test`
-4. `npm run build`
-5. `npm run ci:verify`
-
-If any step fails, document the failure mode and stop doc edits until understood.
-
-## Update Order
-### Phase 1 — Contracts First
-1. `docs/legal-constraints.md`
-2. `docs/cherry-vision.md`
-3. `docs/ci-and-guardrails.md`
-4. `docs/guardrails.md`
-5. `docs/script-standards.md`
-6. `docs/repo-structure.md`
-7. `docs/routes-map.md` + `docs/api.md`
-8. `AGENTS.md`
-9. `.github/copilot-instructions.md`
-10. `README.md`
-
-### Phase 2 — Subsystems
-- Vine: `docs/cherry-vine.md`
-- Wallet: `docs/wallet-pass.md`
-- Verification: `docs/verification-flow.md`
-- Evaluator + Autopilot + Daily state + other subsystem docs
-
-### Phase 3 — Meta Docs
-- Plans, postmortems, audits, roadmaps, marketing drafts.
-- Mark Draft/Deprecated explicitly as needed.
-
-### Phase 4 — Root Docs
-- `CONTRIBUTING.md`, `.github/pull_request_template.md`, `AUDIT.md`, `types/compat/README.md`
-
-## Exclusions
-- Do not edit markdown under `tests/fixtures/**` unless updating the related test logic intentionally.
-
-## Definition of Done
-- All comprehension gates passed.
-- Every non-fixture `.md` has:
-  - `Status` and `Last updated` header.
-  - Clear **Current behavior** vs **Future/Target behavior** where behavior is described.
-  - “Related docs” section.
-- No doc claim contradicts code, CI workflows, guardrails, or legal constraints.
-- `AGENTS.md`, Copilot instructions, and `README.md` are aligned.
-- Post-change validation: `npm run check`, `npm test`, `npm run build`.
-- `git diff --name-only | rg "\\.md$"` shows intended scope only.
-
-## Future/Target behavior
-- Remove or archive this file once the doc rewrite is complete.
-
-## Related docs
-- `AGENTS.md`
-- `docs/system-overview.md`
diff --git a/README.md b/README.md
index 7960d5d7..d000f262 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-04-27
+Last updated: 2026-09-22
 
 ## What Cherry Is
 Cherry is a **real-time spending copilot**. It observes context (merchant, amount, user budgets/cards), runs an engine, recommends the right card and budget impact, and offers Cherry Points for following advice. Cherry:
@@ -26,7 +26,7 @@ Canonical docs: `docs/cherry-vision.md`, `docs/legal-constraints.md`, `docs/cher
 ## Stack and Layout
 - Next.js 16 (App Router), React 19, Tailwind tokens in `app/globals.css`.
 - Server-first pages under `app/`; client components marked with `"use client"`.
-- Auth: NextAuth (PrismaAdapter) with `with-user` guard on APIs.
+- Auth: NextAuth (PrismaAdapter); routes resolve the user via `resolveUserContext` (`lib/user-context.ts`) or the `withUser` wrapper.
 - Data: Postgres via Prisma (`prisma/schema.prisma`).
 - Core flows:
   - `/scan` (dev UI) → `/api/scan` for advisory preview, then `/api/sessions` to create a recommendation session.
@@ -120,7 +120,7 @@ Also available via UI: `/scan`, `/sessions`, `/vine-simulator`, `/admin`.
 - `CherryPointLedger` — Cherry Points movements (PENDING/POSTED/REVOKED) tied to sessions; anomalies flagged.
 - MCC mapping tables: `MerchantCategory`, `MccToRewardCategory`.
 
-Always import Prisma from `@/lib/prisma` and validate inputs with Zod schemas in `lib/schemas/*` plus `parseJsonBody` from `lib/validation.ts`.
+Import Prisma only from `lib/prisma.ts` (relative import with `.js` extension; there is no `@/` alias) and validate inputs with Zod schemas in `lib/schemas/*` plus `parseJsonBody` from `lib/validation.ts`. Architecture map: `docs/architecture/index.md`.
 
 ---
 
diff --git a/app/api/AGENTS.md b/app/api/AGENTS.md
new file mode 100644
index 00000000..d97ad982
--- /dev/null
+++ b/app/api/AGENTS.md
@@ -0,0 +1,25 @@
+# app/api — scoped rules
+
+Root contract: `../../AGENTS.md`. Flow traces: `../../docs/architecture/data-flow.md`. This file adds only route specifics.
+
+## Shape of every handler
+```ts
+const { userId } = await resolveUserContext({ getSession: auth, requireAuth: true, allowLabDemo: false }); // or withUser(request, handler)
+const parsed = await parseJsonBody(request, SomeSchema);   // schema from lib/schemas/*
+if (parsed.ok !== true) return parsed.response;
+const now = new Date(); const nowMs = now.getTime(); const world = buildPrismaWorld();
+const result = await someService(world, userId, parsed.data, { nowMs });   // one call into lib/
+return NextResponse.json(result);
+```
+- Unauthenticated stateful requests return 401. `allowLabDemo: true` is only for advisory dev surfaces (`/api/scan`).
+- No decision logic inline; engine decisions only via `safeSolveDecisionForWorld` (`lib/engine/run.ts`).
+- Time and randomness are created here and passed down. `process.env` reads are allowed only in `app/api/**` and `scripts/**` and should go through `lib/config` (`check:config`).
+- A route file is owned by its service domain (`scripts/guardrails/domains.manifest.json`); it may import only what that domain may import. New route directory: add it to the owning domain's `owns`.
+- Dev-only routes live under `app/api/dev/**` and are gated by `proxy.ts` (`/api/dev/:path*`). `app/api/internal/**` is for cron-style entry points.
+- New public endpoint: update `docs/api.md` and add a `tests/next/api-<name>.*.test.*`.
+
+## Semantics that must not drift
+- `/api/scan` writes only `DecisionEvent`. No session, ledger, or bucket mutation.
+- `/api/sessions` creates; `[id]/confirm` increments `Bucket.spentCents` once and writes PENDING ledger rows; `[id]/verify` moves rows to POSTED/REVOKED. No other route touches `CherryPointLedger`.
+- `/api/vine/order` is dev-only, context-only; signature mode from config, 3-minute freshness window.
+- `/api/wallet/cherry-pass` returns 501 unless fully configured and enabled.
diff --git a/docs/accounting-proof-inventory.md b/docs/accounting-proof-inventory.md
index f69fc1d8..0dadccf1 100644
--- a/docs/accounting-proof-inventory.md
+++ b/docs/accounting-proof-inventory.md
@@ -1,5 +1,5 @@
 Status: Draft
-Last updated: 2026-01-18
+Last updated: 2026-09-22
 
 # Accounting Proof Inventory
 
@@ -47,14 +47,14 @@ Implicitly proves: Deterministic event stream generator for accounting proofs
 Notes: Provides seeded event generation and snapshot helpers for property tests.
 Maturity: PARTIAL
 
-Artifact: tests/engine-accounting-proof.test.ts
-Location: tests/engine-accounting-proof.test.ts
+Artifact: tests/node/engine-accounting-proof.test.ts
+Location: tests/node/engine-accounting-proof.test.ts
 Implicitly proves: Engine output proposals must satisfy ledger invariants; unsafe decisions filtered
 Notes: Exercises overdraft, unbalanced postings, sign abuse, and filtering logic.
 Maturity: IMPLICIT
 
-Artifact: tests/engine-accounting-time-order.test.ts
-Location: tests/engine-accounting-time-order.test.ts
+Artifact: tests/node/engine-accounting-time-order.test.ts
+Location: tests/node/engine-accounting-time-order.test.ts
 Implicitly proves: Engine-output application preserves monotonic time ordering for balances
 Notes: Applies engine-generated hypothetical txns at ordered effective times and checks as-of balances.
 Maturity: EXPLICIT
diff --git a/docs/agent-run-summary.md b/docs/agent-run-summary.md
deleted file mode 100644
index dc5372fd..00000000
--- a/docs/agent-run-summary.md
+++ /dev/null
@@ -1,21 +0,0 @@
-Status: Deprecated
-Last updated: 2026-01-02
-
-# Agent Run Summary (Historical)
-
-This document captures a historical run summary and is not authoritative for current routing or UI state.
-
-## Current behavior
-- See `docs/routes-map.md`, `docs/dev-route-inventory.md`, and `docs/shell-architecture.md` for current route and shell state.
-
-## Historical summary (archived)
-- Prior phases covered route migrations, design system updates, and dev console refactors.
-- Details in the original summary may no longer reflect the current repo layout.
-
-## Future/Target behavior
-- None. This document is archival.
-
-## Related docs
-- `docs/routes-map.md`
-- `docs/dev-route-inventory.md`
-- `docs/shell-architecture.md`
diff --git a/docs/api.md b/docs/api.md
index 0229e6d6..e7fe9f5c 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-04-26
+Last updated: 2026-09-22
 
 # Cherry API Reference (App Router)
 
@@ -27,7 +27,7 @@ This file documents the server routes under `app/api/*` and how they align with
 
 ## Auth
 - Auth stack: NextAuth (PrismaAdapter) in `app/api/auth/[...nextauth]/route.ts`.
-- Auth guard: `withUser` (`lib/with-user.ts`) wraps all stateful routes; unauthenticated calls return `401`.
+- Auth guard: every stateful route resolves the user via `resolveUserContext` (`lib/user-context.ts`); nine routes use the `withUser` wrapper (`lib/with-user.ts`) around it. Unauthenticated calls return `401`.
 - Client rule: on `401`, prompt sign-in (`signIn()`); server components redirect to `/signin?callbackUrl=...`.
 - `GET /api/user/context` — returns `{ userId, mode }` for authenticated requests (used by server components to avoid direct config access).
 
@@ -159,7 +159,7 @@ Purpose: persist a recommendation (manual scan or Vine), let the user claim they
 - `/api/activity` — Activity feed (sessions/ledger/simulations) with pagination/filters.
 - `/api/autopilot/prereqs` — returns Autopilot onboarding prerequisites (`cards/rules/buckets` counts + warnings) and the first missing step.
 
-All use Zod validation in `lib/schemas/*`, `parseJsonBody` from `lib/validation.ts`, and `withUser` guard where stateful.
+All use Zod validation in `lib/schemas/*`, `parseJsonBody` from `lib/validation.ts`, and `resolveUserContext` (or `withUser`) where stateful. Not yet documented here: `/api/autopilot/preview`, `/api/autopilot/commit`, `/api/daily-state`, `/api/dev/engine/inspect`, `/api/internal/run-daily`, `/api/internal/run-daily-all`, `/api/user/merchants`; see `docs/architecture/data-flow.md` and the route files.
 
 ---
 
diff --git a/docs/architecture/audit-2026-09-22.md b/docs/architecture/audit-2026-09-22.md
new file mode 100644
index 00000000..709ab57f
--- /dev/null
+++ b/docs/architecture/audit-2026-09-22.md
@@ -0,0 +1,59 @@
+Status: Active
+Last updated: 2026-09-22
+
+# Architecture Audit — 2026-09-22
+
+Baseline commit `19ec86d` on `main`, clean tree. Purpose: make the repo navigable and safely modifiable by coding agents without changing product behavior. Everything below was verified by reading code or running commands on that commit; items marked *not verified* were not.
+
+## Baseline verification (Node 24.15.0, `npm ci`, `rg` on PATH)
+| Command | Result | Wall time |
+| --- | --- | --- |
+| `npm run check` | pass | 2m32s |
+| `npm test` | pass, 240 files | 2m58s |
+| `npm run build` | fails without `CHERRY_VINE_SIGNATURE_MODE=enforce` (`lib/config/server.ts:13`); pass with it | 31s |
+
+## Verified findings
+
+### Dependency graph (353 source files, 1,059 internal edges under `lib/`, `app/`, `components/`)
+- No `@/` path alias exists; all imports are relative with `.js` suffixes. Several docs said otherwise.
+- The engine barrel loads Prisma: `lib/engine.ts` → `engine/index.ts` → `engine/public.ts` → `lib/engine-state.ts` → `adapters/runtime/engine-state.prisma.ts` → `lib/prisma.ts`, and `lib/engine/legacy.ts` → `lib/legacy-engine.ts` → `adapters/runtime/legacy-engine.prisma.ts`. `check:engine-prisma` did not catch this because its import regexes ran after string literals were blanked (dead patterns; only `prisma.` usage was checked).
+- One value cycle: `lib/engine.ts` → `engine/public.ts` → `lib/scan-helpers.ts` → `lib/engine.ts`.
+- Direction inversions: `lib/auth.ts` imports an `app/api` route; `lib/autopilot/runSimulation.ts` type-imports `components/autopilot/*`.
+- `lib/prisma.ts` has 66 importers; 17 API routes use it directly, 6 only through runtime adapters.
+- Routes call `safeSolveDecisionForWorld` (deep import of `lib/engine/run.ts`) plus the legacy engine; nobody calls `safeSolveDecisionForUser` except the offline evaluator.
+- `lib/adapters/index.ts` and `lib/schemas/index.ts` have zero importers. Zero-importer candidates: `lib/adapters/runtime/{ConsoleLogger,FetchClient,NodeCrypto,NodeFilesystem,PrismaDatabase,SystemClock}.ts`, `lib/autopilot/recent-decisions.ts`, `lib/engine/autopilot.ts`, `lib/history.ts`, `lib/ingest/bank-transactions.ts`, `lib/simulation.ts`, `lib/schemas/autopilot.ts`, `lib/ui.ts`, `lib/util/{boolean,brands}.ts`, `lib/verification/{bank,receipts,vine}.ts`, `lib/authority/replayAuthority.ts` (*deletion not verified safe*; some are named in allowlists).
+- Largest modules: `lib/autopilot/service.ts` 838 lines, `lib/engine/objective.ts` 537, `lib/accounting/ledger.ts` 514, `app/api/simulate/route.ts` 460. Highest fan-out: `app/api/scan/route.ts` and `app/api/simulate/route.ts` (22 imports each).
+
+### Documentation vs code
+Corrected in this change: non-existent `app/(marketing)` and `dist-scripts/`; `@/lib/prisma`; `withUser` described as universal (9 of 35 routes use it); `getServerSession`; CI steps; `check` described as "guardrails + lint + typecheck" (it also runs node and next tests); `.js` specifiers described as forbidden; duplicate guardrail numbers 44 and 57; doctrine §1.2 claiming `fromLegacy` may use time and DB (both guardrails ban it); doctrine §2.1 "never" (six guardrails are allowlisted); `/dev` "gated by middleware" (it is `proxy.ts`, and five dev pages are outside its matcher); legacy test paths cited in three docs. Deleted five docs that declared themselves deprecated and `DOC_REWRITE_TASK.md`.
+Not changed (needs a product decision): `/signin` has no `page.tsx` while NextAuth points at it (*404 not verified at runtime*); `docs/api.md` omits seven routes (now listed there as undocumented).
+
+### Enforcement classification
+Enforced: engine no-Date, engine no-Prisma (now including value imports), guardrail/runtime separation (with allowlist), `EngineInput` boundary, engine version gates, script runner contract, registry/doc parity, DB truth via named scripts. Documented only: `withUser` on stateful routes, Prisma only via adapters, bucket math via `buckets-runtime`, the engine-freeze content rules (four `feat(engine)` commits since the freeze, no exception entries), evaluator read-only, `upsertBankTransactions`-only ingest, locale-free SSR. Local only: `check:change-isolation` (no-op in CI).
+
+### Tests
+- 110 legacy files (`tests/*.test.*`, `tests/guardrails`, `tests/authority`, `tests/migrations`, `tests/type`, plus `tests/helpers`, `tests/__mocks__`, `tests/accounting`, `tests/engine`) duplicate `tests/node`/`tests/next`. Two pairs diverged in logic (`engine-solver`, `api-sessions.user-context`). `check:guardrails-core` requires 25 legacy paths to exist; `check:engine-optimality` runs the legacy `tests/engine/optimality` copy; `tests/node/engine/optimality` and `tests/accounting` run nowhere.
+- CI runs node and next tests three times.
+- No framework; mixed ESM/CommonJS import styles across test files.
+
+### Repository hygiene
+- `cherry-diff.patch` (47 KB) is a committed working-tree snapshot verified by `verify:cherry-diff-artifact`; it goes stale by construction. `docs/config-snapshot.md` (405 KB) is generated but required by two guardrails. `AUDIT.md` is a historical one-off referenced only by the full-checkout audit script.
+- `.evidence/latest.json` was not ignored; `scripts/audit/full-checkout-audit.mts` was ignored but tracked and required by a guardrail; `*.pem` listed twice. Fixed.
+- `data/bank/moustafa-adv-safebalance-2061.csv`: commit `d6b8651` states it is a synthetic replacement, but earlier history (`ddc864b` and before) still contains real exports. **Separate remediation required** (history rewrite is a deliberate, coordinated action; not done here).
+- `data/mcc/sanitized-mcc.txt` is byte-identical to the `.tsv` and unused; `Merchant-Category-Codes.pdf` and `unsanitized-full.txt` are unused (left in place; not required for reproducibility, not harmful).
+- No tracked secrets found. `scripts/dev-login.sh` contains a hard-coded dev password (dev-only). `lib/wallet/cherryPass.ts` derives the Wallet `authenticationToken` from the user id with a constant fallback, which is guessable (*security review recommended before enabling the pass*).
+- `scripts/side-effects.allowlist.json`: all ten `legacy-combo` entries carry `expiresBy: 2026-06-01`. `check:side-effects:diff` compares against the HEAD commit date, so **any commit dated after 2026-06-01 fails `npm run check`** until the entries are remediated or the policy is revisited. This is pre-existing and blocks every branch, including this one.
+
+## Changes made (see `decisions/0001`, `decisions/0002`)
+- `scripts/guardrails/domains.manifest.json` + `check:domain-boundaries` + self-test; `check:engine-prisma` import patterns fixed + self-test.
+- `report:domain-impact` execution script; `--filter=` on `check:tests:node` / `check:tests:next`.
+- `AGENTS.md` rewritten as the single contract (113 lines); `CLAUDE.md`, `.github/copilot-instructions.md` reduced to pointers; `CONTRIBUTING.md` trimmed to human-only content; scoped `AGENTS.md` in `lib/engine/`, `app/api/`, `scripts/`.
+- `docs/architecture/{index,domains,dependency-rules,data-flow,testing}.md` and two ADRs; stale docs corrected as listed above.
+
+## Recommended next work (in order)
+1. Decide the `side-effects` allowlist expiry (extend with a new date and owner, or remediate the ten files). Nothing lands until then.
+2. Remove the 110 duplicate legacy tests, repointing `check:guardrails-core`, `check:engine-optimality`, `verify:8.3-closure-artifact`, `projected-liquid-cents.allowlist.json`, and `tsconfig.scripts.json`; drop the redundant `check:tests:*` steps from `ci.yml` or keep them and drop `test` from `ci:verify`. Halves test wall time and ends the drift.
+3. Under the engine-freeze protocol: stop re-exporting `legacy.ts`/`public.ts` from the engine barrel so importing `lib/engine.ts` no longer loads Prisma; delete the three allowlisted debt edges.
+4. Normalize route auth on `resolveUserContext` (or make `withUser` universal) and add a guardrail; move the remaining direct `lib/prisma` route imports behind runtime stores; then tighten `persistence.mayImport` consumers in the manifest.
+5. Regenerate `docs/api.md` for the seven undocumented routes; add or remove the `/signin` page.
+6. Delete verified-dead modules after confirming they are not referenced by config or allowlists.
diff --git a/docs/architecture/auth.md b/docs/architecture/auth.md
index 1f8c4b49..319f482b 100644
--- a/docs/architecture/auth.md
+++ b/docs/architecture/auth.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-01-02
+Last updated: 2026-09-22
 
 # Auth Architecture (NextAuth + Prisma)
 
@@ -11,7 +11,7 @@ This document explains how authentication works in Cherry and how to keep it ali
 - Identity/auth stack: **NextAuth** with **PrismaAdapter**.
 - Location: `app/api/auth/[...nextauth]/route.ts`.
 - Storage: `User`, `Account`, `Session`, `VerificationToken` tables in `prisma/schema.prisma`.
-- Session guard: `withUser` (`lib/with-user.ts`) extracts `userId` via `getServerSession` and returns `401` on failure.
+- Session guard: `resolveUserContext` (`lib/user-context.ts`) resolves `userId` from the NextAuth v5 `auth()` session (`lib/auth.ts`); `withUser` (`lib/with-user.ts`) wraps it and returns `401` on failure.
 - Client handling: components use `useSession()` and call `signIn()` on `401` responses from APIs.
 
 ## Current behavior (enforced / in code)
diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md
new file mode 100644
index 00000000..b5d95deb
--- /dev/null
+++ b/docs/architecture/data-flow.md
@@ -0,0 +1,56 @@
+Status: Active
+Last updated: 2026-09-22
+
+# Data Flow
+
+Traces of the main operations through the layers, as implemented. Paths are exact; read the named file for detail.
+
+## Common boundary pattern (every API route)
+1. `resolveUserContext({ getSession: auth, requireAuth, allowLabDemo })` from `lib/user-context.ts` yields `userId` (or 401). Nine routes use the `withUser` wrapper in `lib/with-user.ts` instead; both end in `resolveUserContext`.
+2. `parseJsonBody(request, Schema)` from `lib/validation.ts` with a Zod schema from `lib/schemas/*`; returns a ready 400 response on failure.
+3. `const now = new Date(); const nowMs = now.getTime()` and `const world = buildPrismaWorld()` (`lib/adapters/runtime/world.prisma.ts`). Time and side effects enter here and are passed down.
+4. One service call. Response via `NextResponse.json`.
+
+## Scan (advisory, stateless) — `POST /api/scan`
+`app/api/scan/route.ts`
+- `resolveScanCategory` (`lib/scan-helpers.ts`) maps merchant/MCC/explicit category to a `RewardCategory`.
+- `simulateSpendAuthority` (`lib/adapters/runtime/authority.prisma.ts` -> pure `lib/authority/simulateSpendAuthority.ts`) decides admissibility.
+- `fromPrismaUserToEngineState` (`lib/adapters/runtime/engine-state.prisma.ts`) loads cards/buckets into `EngineState`.
+- `safeSolveDecisionForWorld(world, userId, context, { stateOverride, legacyDecisionProvider: runLegacyEngine })` (`lib/engine/run.ts`): `fromLegacy` -> `validateEngineInput` -> `solveDecision`; returns `{ ok:false, reason }` instead of throwing. The legacy engine decision rides along for the response shape.
+- `recordDecisionEvent` writes a `DecisionEvent` row (telemetry). No session, no ledger, no bucket mutation.
+
+## Recommendation session lifecycle
+**Create — `POST /api/sessions`** (`app/api/sessions/route.ts`): same auth/parse/engine steps as scan, then `prisma.recommendationSession.create` with `orderToken`, `expiresAt`, offered points, verdicts, `source: APP_SCAN`.
+
+**Confirm — `POST /api/sessions/[id]/confirm`** -> `confirmRecommendationSession` in `lib/sessions/confirm-service.ts`:
+- rejects expired or already-confirmed sessions (`SessionConfirmError`);
+- computes an anomaly code (amount mismatch, time window, card mismatch);
+- `ensureBucketFresh(bucketId, now)` (`lib/buckets/ensure-fresh.ts`) rolls the period if needed, then increments `Bucket.spentCents` exactly once;
+- writes `CherryPointLedger` rows with status `PENDING`, `verificationStatus: PENDING`.
+
+**Verify — `POST /api/sessions/[id]/verify`** -> `verifySessionFromSignal` in `lib/verification/verify-session.ts`: flips ledger rows to `POSTED` or `REVOKED`; revocation reverses the bucket spend via `lib/sessions/reversal.ts`. Verification signals are simulated today (`lib/verification/{bank,receipts,vine}.ts` are stubs).
+
+## Vine order (dev-only context beacon) — `POST /api/vine/order`
+`app/api/vine/order/route.ts`
+- Accepts a terminal event (`vineTerminalEventSchema`) or an `OrderContext` (`OrderContextSchema`); `mapTerminalEventToOrderContext` normalises.
+- `verifyVineSignature` (`lib/vine/security.ts`) under `CHERRY_VINE_SIGNATURE_MODE` (`off | warn | enforce`; production requires `enforce`, asserted by `lib/config/server.ts`).
+- Freshness window of 3 minutes on the order timestamp.
+- `runRecommendationFromOrderContext(world, orderContext, userId, ...)` (`lib/vine/run-recommendation.ts`) runs the engine and creates a session with `source: VINE_*` and an `orderToken`.
+
+## Autopilot — `POST /api/autopilot/preview`, `POST /api/autopilot/commit`
+- `getAutopilotPreview` (`lib/autopilot/service.ts`) builds the engine context for a proposed swipe and returns the ranked decision without persisting.
+- `commitAutopilotDecision` / `commitAutopilotDecisionV2` (flag `AUTOPILOT_COMMIT_V2`) persist an `AutopilotCommit` keyed by an idempotency key (`lib/autopilot/engineDecisionId.ts`, `lib/idempotency.ts`) and apply bucket impact through the same bucket runtime.
+- Input validation lives in `lib/validation/autopilot/*` and `lib/autopilot/types.ts`.
+
+## Bank ingest (dev-only) — `POST /api/dev/bank/ingest`, `npm run ingest:moustafa-bank`
+- CSV rows -> `lib/bank/csv-dev-provider.ts` -> `upsertBankTransactions` (`lib/bank/ingest.ts`), idempotent on `(userId, externalId)`; `BankTransaction.id` is never taken from input.
+- `lib/income/classifier.ts` derives income/P2P kinds; `lib/buckets/regimes.ts` derives regimes.
+
+## Offline evaluator (diagnostic only) — `npm run audit:evaluator:moustafa`
+`lib/evaluator/offline-history.ts` replays `BankTransaction` rows through `safeSolveDecisionForUser` and writes only `HistoricalEngineEvaluation`. Gated by `CHERRY_OFFLINE_EVALUATOR_ENABLED`; must call `assertOfflineEvaluatorModelsReady()` first.
+
+## Wallet pass — `GET /api/wallet/cherry-pass`
+Returns 501 unless `CHERRY_WALLET_PASS_ENABLED=true` and all Apple env vars are set (`lib/wallet/config.ts`); otherwise builds a `storeCard` pass (`lib/wallet/cherryPass.ts`). Never a payment instrument.
+
+## Related docs
+- `docs/api.md` (request/response shapes), `docs/verification-flow.md`, `docs/cherry-vine.md`, `docs/autopilot-master-spec.md`, `docs/offline-evaluator.md`
diff --git a/docs/architecture/decisions/0001-domain-manifest-and-boundary-guardrail.md b/docs/architecture/decisions/0001-domain-manifest-and-boundary-guardrail.md
new file mode 100644
index 00000000..99f55d39
--- /dev/null
+++ b/docs/architecture/decisions/0001-domain-manifest-and-boundary-guardrail.md
@@ -0,0 +1,23 @@
+Status: Accepted
+Last updated: 2026-09-22
+
+# ADR 0001 — Domain manifest and dependency-direction guardrail
+
+## Context
+Cherry had strong point guardrails (engine: no Prisma, no Date; guardrails: no runtime imports; shells: no cross-imports) but no statement of which module owns which file or which direction imports may flow between capabilities. Agents had to read most of `lib/` to find a change's home, and cross-domain coupling (e.g. `lib/engine.ts` transitively loading Prisma, schemas importing services) was invisible.
+
+## Decision
+- Add `scripts/guardrails/domains.manifest.json`: 24 domains in 4 layers, each with `owns` globs, `mayImport`, `tests`, `docs`, `invariants`.
+- Add `check:domain-boundaries` (registered, part of `npm run check`) that enforces total, exclusive ownership and downward value-import direction, validates that `tests`/`docs` references resolve, and requires stale `allowedViolations` entries to be deleted.
+- Pre-existing violations are allowlisted with reasons rather than fixed here, because three of them sit inside `lib/engine/**` and fall under the engine-freeze and change-isolation protocol.
+- Add `report:domain-impact` (execution registry) and `--filter` on the node/next test runners so a change's DOMAIN-level verification can be derived from the manifest.
+
+## Alternatives considered
+- dependency-cruiser / eslint-plugin-boundaries: capable, but a new dependency and a second rule language; the repo already has a regex/AST guardrail idiom and a registry with meta-checks.
+- Directory reorganisation into `lib/<domain>/`: high churn across ~360 files during an engine freeze; ownership by glob gives the same navigability without moving code.
+- A per-domain `package.json` (monorepo): no compilation or ownership benefit at this size.
+
+## Consequences
+- New files must be owned; unowned files fail `check`. Cost: one line in the manifest.
+- The manifest is the single machine-readable source for "who owns this / what may it import / what to test"; `docs/architecture/domains.md` is a rendering of it.
+- Type-only imports are unchecked. This is deliberate; it can be tightened later.
diff --git a/docs/architecture/decisions/0002-agent-instruction-authority.md b/docs/architecture/decisions/0002-agent-instruction-authority.md
new file mode 100644
index 00000000..fddfa7b1
--- /dev/null
+++ b/docs/architecture/decisions/0002-agent-instruction-authority.md
@@ -0,0 +1,18 @@
+Status: Accepted
+Last updated: 2026-09-22
+
+# ADR 0002 — One authority for agent instructions
+
+## Context
+The same operating rules (branch/PR flow, legal framing, Prisma/Zod/withUser rules) were copied across `AGENTS.md`, `CONTRIBUTING.md`, `.github/copilot-instructions.md`, `README.md`, and `CLAUDE.md`, and several copies had drifted (`@/` alias that does not exist, `withUser` described as universal when 9 of 35 routes use it, CI steps misdescribed).
+
+## Decision
+- `AGENTS.md` is the only operating contract. It is short, navigational, and links to `docs/architecture/*` and `docs/doctrine.md` for detail.
+- `CLAUDE.md` and `.github/copilot-instructions.md` are two-line pointers to `AGENTS.md`. Claude Code and Codex both read `AGENTS.md`; Copilot reads its own file.
+- `CONTRIBUTING.md` keeps only human-workflow content (branch naming, engine-change label) and points to `AGENTS.md` for the rest.
+- Scoped `AGENTS.md` files exist only where a directory has rules the root cannot express briefly: `lib/engine/`, `app/api/`, `scripts/`. They reference the root and never restate it.
+- Docs describing behaviour must match code; where they did not, the doc was corrected rather than the code, except where a guardrail was found to be weaker than documented (`check:engine-prisma` import patterns), which was fixed in code.
+
+## Consequences
+- A rule appears in exactly one place; drift is visible as a broken link rather than a contradiction.
+- Agents entering the repo read `AGENTS.md` (about 150 lines) and one architecture page, instead of five overlapping files.
diff --git a/docs/architecture/dependency-rules.md b/docs/architecture/dependency-rules.md
new file mode 100644
index 00000000..48ad8332
--- /dev/null
+++ b/docs/architecture/dependency-rules.md
@@ -0,0 +1,50 @@
+Status: Active
+Last updated: 2026-09-22
+
+# Dependency Rules
+
+## The rule
+Imports flow downward only:
+
+```
+surface (ui, dev-tools)
+   ↓
+service (sessions, evaluation, autopilot, vine, wallet, buckets, cards, bank, income, daily-state, evaluator, identity, observability)
+   ↓
+runtime (adapters-runtime, persistence)
+   ↓
+core (engine, authority, accounting, adapters-contracts, schemas, config, shared)
+```
+
+- A domain may value-import only itself and the domains listed in its `mayImport` in `scripts/guardrails/domains.manifest.json`. Surfaces list `"*"`.
+- Core domains never import runtime or services. `engine` and `authority` additionally never import Prisma or read the clock (`check:engine-prisma`, `check:engine-date`); time enters as `nowMs` from the route.
+- `persistence` (`lib/prisma.ts`) is the only place a Prisma client is created. Services may import it directly today; the target is to reach Prisma through `adapters-runtime` stores, but that migration is not enforced.
+- Type-only imports (`import type`, `export type ... from`) are not checked. They create no runtime coupling. Do not launder a value dependency through a type import.
+- `app/api/**/route.ts` files belong to the service that owns the route, so a route may import only what its service may import. Keep handlers thin: auth, `parseJsonBody`, one service call, response.
+- Guardrail scripts (the `check:<name>` scripts under `scripts/`) may not import `lib/**` (`check:environment-import-integrity`, with a small explicit allowlist). They inspect source text.
+- User shell must not import from the dev shell and vice versa (`check:shell-boundaries`).
+
+## Enforcement
+`check:domain-boundaries` (part of `npm run check`) fails when:
+- a file under `lib/`, `app/`, `components/`, `types/` has no owner or two owners;
+- a value import crosses domains outside `mayImport` and is not in `allowedViolations`;
+- an `allowedViolations` entry no longer occurs (stale debt must be deleted);
+- a domain's `docs` path or `tests` glob resolves to nothing.
+
+Cross-domain edge counts: `CHERRY_DOMAIN_BOUNDARIES_REPORT=1 npm run check:domain-boundaries`.
+
+## Adding or moving code
+1. Put the file under a path an existing domain already owns, or add the path to that domain's `owns`.
+2. If it needs a new cross-domain import, ask whether the dependency direction is right. If it is, add the target to `mayImport`. If it is not, move the shared piece down a layer (usually to `shared`, `schemas`, or `adapters-contracts`).
+3. Never add to `allowedViolations` for new code. That list is for pre-existing debt only.
+
+## Current allowlisted debt
+Listed with reasons in `domains.manifest.json`. As of this writing:
+- `lib/engine/legacy.ts` -> `lib/legacy-engine.ts` and `lib/engine/public.ts` -> `lib/engine-state.ts`: the engine barrel (`lib/engine.ts`) re-exports Prisma-backed runtime bridges, so importing the barrel loads Prisma. Removing this is an engine-freeze change (see `docs/doctrine.md` §1 and §8).
+- `lib/engine/public.ts` -> `lib/scan-helpers.ts`: value cycle `lib/engine.ts` -> `engine/index` -> `engine/public` -> `scan-helpers` -> `lib/engine.ts`.
+- `lib/authority/replayAuthority.ts` -> `lib/adapters/runtime/authority.replay.prisma.ts`: pure module re-exporting a runtime implementation; it has no importers.
+
+Other known direction problems that the manifest currently tolerates by ownership choice rather than allowlist: `lib/auth.ts` imports `app/api/auth/[...nextauth]/route.ts` (both in `identity`), and `lib/autopilot/runSimulation.ts` type-imports `components/autopilot/*`.
+
+## Related docs
+- `index.md`, `domains.md`, `docs/doctrine.md` §2 (environment separation), `docs/adapters.md`
diff --git a/docs/architecture/domains.md b/docs/architecture/domains.md
new file mode 100644
index 00000000..67532216
--- /dev/null
+++ b/docs/architecture/domains.md
@@ -0,0 +1,86 @@
+Status: Active
+Last updated: 2026-09-22
+
+# Domains
+
+Source of truth: `scripts/guardrails/domains.manifest.json` (enforced by `check:domain-boundaries`; every file under `lib/`, `app/`, `components/`, `types/` is owned by exactly one domain). This page is a readable rendering of that file. If they disagree, fix this page.
+
+Query it: `npm run report:domain-impact -- <path...>` prints the domain, allowed imports, dependents, tests, docs and invariants for any file.
+
+## Layers
+- **core** — pure, deterministic, no DB, no HTTP, no wall clock. Engine, authority, accounting, contracts, schemas, config, shared helpers.
+- **runtime** — the only place Prisma and the system clock are wired into a `World`.
+- **service** — business capabilities. Each owns its API routes and its `lib/` modules. Services may depend on core and runtime, and on the specific sibling services listed in `mayImport`.
+- **surface** — UI shells, components, dev console. May import anything.
+
+## Domain table
+
+| Domain | Layer | Purpose | Owns | Tests | Docs |
+| --- | --- | --- | --- | --- | --- |
+| `shared` | core | Pure helpers with no domain knowledge (errors, enums, text, numbers, money, ids, invariants, routes). | `lib/errors.ts`, `lib/enums.ts`, `lib/text.ts`, `lib/numbers.ts`, `lib/money.ts`, `lib/ids.ts`, `lib/invariants.ts`, `lib/routes.ts`, `lib/formatCurrency.ts`, `lib/server-determinism-fixture.ts`, `lib/util/**`, `lib/api/**`, `types/**`, `lib/mcc.ts` | `tests/node/idempotency*.test.ts`, `tests/node/identity-determinism.test.ts` | — |
+| `schemas` | core | Zod request/response contracts and the parseJsonBody boundary helper. | `lib/schemas/**`, `lib/validation.ts` | `tests/node/simulate-response-schema.test.js`, `tests/node/recommendation-temporal-schema.test.ts` | `docs/zod-style.md`, `docs/api.md` |
+| `adapters-contracts` | core | Pure TypeScript port interfaces (Clock, Logger, Digest, Entropy, stores, World). No implementations. | `lib/adapters/*.ts`, `lib/adapters/contracts/**` | `tests/node/adapters-contracts.test.ts` | `docs/adapters.md` |
+| `engine` | core | Deterministic decision engine: EngineInput contract, solver, objective, candidates, horizon, uncertainty. No time, no DB. | `lib/engine/**`, `lib/engine.ts`, `lib/engine-invariants.ts` | `tests/node/engine*.test.*`, `tests/node/engine/**`, `tests/node/objective-utility.test.ts` | `docs/doctrine.md`, `docs/engine-roadmap.md`, `docs/engine-freeze.md`, `docs/engine-time-semantics.md`, `docs/engine-optimality/status.md`, `docs/simulation/objective-semantics.md` |
+| `accounting` | core | Double-entry ledger model and engine accounting proof. | `lib/accounting/**` | `tests/node/accounting/**`, `tests/node/engine-accounting-*.test.ts` | `docs/accounting-axioms.md`, `docs/accounting/invariants.md`, `docs/engine-ledger-boundary.md` |
+| `authority` | core | Pure spend admissibility decisions and verdict policy. | `lib/authority/**`, `lib/policy/**`, `lib/guards/**` | `tests/node/authority/**`, `tests/node/authority-invariants.test.ts`, `tests/node/policy-totality.test.ts`, `tests/node/decision-event-recording.test.ts` | `docs/authority-v1.md`, `docs/decision-event-ledger.md` |
+| `config` | core | Typed, frozen server/public config loaded once at the boundary. | `lib/config/**`, `lib/base-url.ts` | `tests/node/config-injection.test.ts`, `tests/node/no-env-smoke.test.ts` | `docs/env-policy.md` |
+| `persistence` | runtime | The single Prisma client instance. | `lib/prisma.ts` | `tests/db/**` | `docs/schema-evolution.md`, `docs/storage-doctrine.md` |
+| `adapters-runtime` | runtime | Concrete World wiring (Prisma stores, system clock, entropy, logger) and Prisma-backed engine/authority bridges. | `lib/adapters/runtime/**`, `app/api/_clock.ts`, `lib/engine-state.ts`, `lib/legacy-engine.ts`, `lib/legacy-engine-types.ts`, `lib/replay/**` | `tests/node/engine-state.prisma.test.js`, `tests/node/engine-world.test.ts`, `tests/node/guardrails/prisma-adapter-totality.test.ts` | `docs/adapters.md`, `docs/engine-state.md` |
+| `identity` | service | NextAuth wiring, user context resolution, withUser guard. | `lib/auth.ts`, `lib/with-user.ts`, `lib/user-context.ts`, `lib/identity/**`, `lib/dev/**`, `app/api/auth/**`, `app/api/user/context/**`, `app/signin/**` | `tests/next/user-context*.test.*`, `tests/next/*.user-context.test.*` | `docs/architecture/auth.md` |
+| `buckets` | service | Budget buckets: balance math, period rollover, regimes, freshness. | `lib/buckets-runtime.ts`, `lib/buckets/**`, `lib/category-preferences.ts`, `app/api/buckets/**` | `tests/node/bucket*.test.js`, `tests/node/buckets-periods.test.js`, `tests/node/category-preference-enum.test.js` | `docs/buckets-rollover-plan.md` |
+| `cards` | service | Cards and reward rules CRUD. | `app/api/cards/**` | `tests/next/api-rewards.validation.test.js` | `docs/api.md` |
+| `income` | service | Income and P2P classification over bank transactions; income regimes. | `lib/income/**` | `tests/node/income-*.test.js` | `docs/income-regimes.md` |
+| `bank` | service | Bank transaction ingest (idempotent on (userId, externalId)) and dev CSV provider. | `lib/bank/**`, `lib/ingest/**`, `app/api/dev/bank/**` | `tests/node/bank-ingest*.test.js` | `docs/bank-ingest-notes.md` |
+| `evaluation` | service | Advisory scan/simulate surfaces: MCC resolution, engine invocation, decision-event telemetry. Stateless with respect to sessions and ledger. | `app/api/scan/**`, `app/api/simulate/**`, `app/api/simulations/**`, `app/api/mccs/**`, `app/api/user/merchants/**`, `lib/scan-helpers.ts`, `lib/scan-types.ts`, `lib/scan-client-state.ts`, `lib/simulation.ts`, `lib/simulation-adapter.ts`, `lib/mccCategoryMapper.ts` | `tests/next/api-scan*.test.*`, `tests/next/api-simulate*.test.*`, `tests/node/scan-client-state.test.js`, `tests/node/simulation-adapter.test.js`, `tests/node/simulate-response-schema.test.js` | `docs/api.md` |
+| `sessions` | service | Recommendation sessions, confirm/verify lifecycle, Cherry Points ledger, verification stubs. | `lib/sessions/**`, `lib/verification/**`, `lib/points.ts`, `lib/idempotency.ts`, `app/api/sessions/**`, `app/api/dev/pending-sessions/**`, `app/api/dev/verification/**` | `tests/next/api-sessions*.test.*`, `tests/node/sessions-bucket-reversal.test.js`, `tests/node/verification-session.test.js`, `tests/node/idempotency.test.ts` | `docs/verification-flow.md`, `docs/decision-event-ledger.md` |
+| `vine` | service | Cherry Vine context beacon ingest (merchant + amount + timestamp). Never a payment device. | `lib/vine/**`, `app/api/vine/**` | `tests/node/vine-*.test.js`, `tests/next/api-vine-order*.test.js`, `tests/next/vine-order-security.test.js`, `tests/node/run-recommendation.user-context.test.js` | `docs/cherry-vine.md`, `docs/vine-security.md` |
+| `wallet` | service | Cherry Pass storeCard scaffold; returns 501 unless fully configured and enabled. | `lib/wallet/**`, `app/api/wallet/**` | `tests/node/wallet-pass-config.test.js` | `docs/wallet-pass.md` |
+| `autopilot` | service | Autopilot preview/commit flow and simulation orchestration on top of the engine. | `lib/autopilot/**`, `app/api/autopilot/**`, `lib/metrics/**`, `lib/validation/autopilot/**` | `tests/node/autopilot-*.test.*`, `tests/next/api-autopilot*.test.*`, `tests/next/autopilot-*.test.*`, `tests/node/onboarding-prereqs.test.ts` | `docs/autopilot-master-spec.md`, `docs/autopilot-engine-adapter.md` |
+| `daily-state` | service | Daily state computation and alerting. | `lib/daily-state/**`, `lib/alerts/**`, `app/api/daily-state/**`, `app/api/internal/**` | `tests/node/alertPolicy.test.js`, `tests/node/type/daily-state.types.test.ts` | `docs/daily-state.md` |
+| `evaluator` | service | Offline engine evaluator. Read-only over Sessions/Ledger/Buckets; writes only HistoricalEngineEvaluation. | `lib/evaluator/**` | `tests/node/offline-evaluator-*.test.js` | `docs/offline-evaluator.md` |
+| `observability` | service | Logging, metrics, activity feeds, health and admin stats. | `lib/logger.ts`, `lib/log.ts`, `lib/logging.ts`, `lib/activity/**`, `lib/unified-activity.ts`, `lib/admin/**`, `app/api/activity/**`, `app/api/health/**`, `app/api/admin/**` | — | `docs/decision-event-ledger.md` |
+| `dev-tools` | surface | Dev-only console pages, seeding, and inspection routes. Never shipped to users. | `app/\(dev\)/**`, `app/api/seed-demo/**`, `app/api/dev/engine/**`, `lib/demo-seeder.ts` | — | `docs/dev-route-inventory.md`, `docs/dev-ui-parity.md` |
+| `ui` | surface | User-facing app shell, shared components, client API helpers. | `app/\(user\)/**`, `app/layout.tsx`, `app/providers.tsx`, `components/**`, `lib/ui/**`, `lib/ui.ts`, `lib/client/**`, `lib/home/**`, `lib/dashboard.ts`, `lib/history.ts`, `proxy.ts` | `tests/next/home-screen-authority.test.tsx`, `tests/node/home-ui-contract.test.ts`, `tests/next/client-api.test.js` | `docs/information-architecture.md`, `docs/routes-map.md`, `docs/shell-architecture.md`, `docs/home-ui-contract.md` |
+
+## Canonical entrypoints (where to start reading)
+- Engine decision: `safeSolveDecisionForWorld` in `lib/engine/run.ts` (routes) and `solveDecision` in `lib/engine/solver.ts` (pure). Input contract: `lib/engine/input/EngineInput.ts`; adapter from Prisma-shaped state: `lib/engine/input/fromLegacy.ts`.
+- World wiring: `buildPrismaWorld()` in `lib/adapters/runtime/world.prisma.ts`.
+- Auth boundary: `resolveUserContext` in `lib/user-context.ts` (most routes) and `withUser` in `lib/with-user.ts` (9 routes).
+- Request validation: `parseJsonBody` in `lib/validation.ts` with a schema from `lib/schemas/*`.
+- Session lifecycle: `app/api/sessions/route.ts` (create), `lib/sessions/confirm-service.ts` (confirm), `lib/verification/verify-session.ts` (verify).
+- Bucket math: `computeBucketBalance` in `lib/buckets-runtime.ts`; freshness: `lib/buckets/ensure-fresh.ts`.
+- Autopilot: `getAutopilotPreview`, `commitAutopilotDecision(V2)` in `lib/autopilot/service.ts`.
+- Vine: `runRecommendationFromOrderContext` in `lib/vine/run-recommendation.ts`.
+- Bank ingest: `upsertBankTransactions` in `lib/bank/ingest.ts`.
+
+## Domain invariants (enforced or documented; see `dependency-rules.md` for which)
+- `engine`: No Date/Date.now (check:engine-date)
+- `engine`: No Prisma (check:engine-prisma)
+- `engine`: EngineInput is the only input contract (check:engine-input-boundary)
+- `engine`: Behavior/input/candidate/accounting version bumps + chore(engine-freeze) commit (check:engine-version-gates, check:engine-version-bump, check:engine-freeze)
+- `accounting`: check:accounting-invariants
+- `accounting`: check:no-mutation
+- `accounting`: check:replay-equals-materialized
+- `authority`: check:authority-lint
+- `authority`: check:authority-invariants
+- `authority`: check:engine-date
+- `authority`: check:engine-prisma
+- `config`: check:config
+- `config`: check:config-init
+- `config`: check:config-lock
+- `buckets`: Balance math only via lib/buckets-runtime.ts; budgetAmount/spentCents authoritative, currentAmount legacy mirror
+- `bank`: All ingest writes go through upsertBankTransactions; BankTransaction.id never set from ingest data
+- `sessions`: Confirm increments Bucket.spentCents once per session; ledger rows PENDING -> POSTED/REVOKED only via verify
+- `evaluator`: Gate on CHERRY_OFFLINE_EVALUATOR_ENABLED; call assertOfflineEvaluatorModelsReady() first; derive runId via defaultRunIdForUser
+
+## Known cross-domain debt (allowlisted in the manifest; remove the entry when fixed)
+- `lib/engine/legacy.ts` -> `lib/legacy-engine.ts`: Legacy engine facade re-exports the Prisma-backed runtime bridge; importing lib/engine.ts loads Prisma. Engine-freeze change; track as debt.
+- `lib/engine/public.ts` -> `lib/engine-state.ts`: Autopilot swipe entrypoint reaches Prisma engine-state loader through the engine barrel. Engine-freeze change; track as debt.
+- `lib/engine/public.ts` -> `lib/scan-helpers.ts`: Value cycle engine -> scan-helpers -> engine. Engine-freeze change; track as debt.
+- `lib/authority/replayAuthority.ts` -> `lib/adapters/runtime/authority.replay.prisma.ts`: Pure module re-exports a runtime implementation. No importers; candidate for deletion.
+
+## Change impact
+When you change a domain, run its `tests` globs (DOMAIN level), then the FULL gate. Domains listed under "imported by" in `report:domain-impact` output are the ones whose tests can break. Engine, authority and accounting changes additionally require `npm run check:guardrails` (version gates, freeze, accounting proofs) and the `chore(engine-freeze)` protocol in `docs/doctrine.md`.
+
+## Related docs
+- `index.md`, `dependency-rules.md`, `testing.md`
diff --git a/docs/architecture/index.md b/docs/architecture/index.md
new file mode 100644
index 00000000..27295854
--- /dev/null
+++ b/docs/architecture/index.md
@@ -0,0 +1,38 @@
+Status: Active
+Last updated: 2026-09-22
+
+# Architecture Map
+
+Entry point for anyone (human or agent) who needs to change Cherry. Read this, then the one domain page you need. Operating rules live in `AGENTS.md`; execution invariants in `docs/doctrine.md`.
+
+## What Cherry is, in one paragraph
+A Next.js 16 App Router app (React 19, TypeScript, Prisma/PostgreSQL, NextAuth, Zod) that runs a deterministic decision engine over a user's cards, buckets, and a merchant/amount context, recommends a card and budget impact, and rewards followed advice with advisory Cherry Points. The loop is Observe -> Evaluate -> Recommend -> Reward. Cherry never touches payment rails.
+
+## System map
+
+```
+ surfaces   app/(user)  app/(dev)  components/         <- UI, dev console
+            app/api/*/route.ts                         <- thin HTTP boundary: auth, Zod, call a service
+ services   sessions  evaluation  autopilot  vine  wallet  buckets  cards  bank  income  daily-state  evaluator  identity  observability
+ runtime    lib/adapters/runtime (World: Prisma stores, clock, entropy, logger)   lib/prisma.ts
+ core       engine  authority  accounting  adapters-contracts  schemas  config  shared
+```
+
+Dependency direction is downward only. `scripts/guardrails/domains.manifest.json` is the machine-readable version of this map and `check:domain-boundaries` enforces it. See `dependency-rules.md`.
+
+## Pages
+- `domains.md` — every domain: what it owns, its entrypoints, its tests, its docs, its invariants. Start here to locate code.
+- `dependency-rules.md` — what may import what, the type-only exception, and the current allowlisted debt.
+- `data-flow.md` — scan, session create/confirm/verify, Vine order, Autopilot preview/commit, traced through the layers.
+- `testing.md` — test layout, runners, the FAST / DOMAIN / FULL verification levels, and how to run one file.
+- `decisions/` — architecture decision records.
+
+## Finding the owner of a file
+```bash
+npm run report:domain-impact -- lib/buckets-runtime.ts      # domain, allowed imports, tests, docs, invariants
+npm run report:domain-impact                                  # same for every file changed vs main
+```
+
+## Related docs
+- `AGENTS.md`, `docs/doctrine.md`, `docs/legal-constraints.md`, `docs/cherry-vision.md`
+- `docs/system-overview.md` (product-level narrative), `docs/api.md`, `docs/routes-map.md`
diff --git a/docs/architecture/testing.md b/docs/architecture/testing.md
new file mode 100644
index 00000000..54250bd5
--- /dev/null
+++ b/docs/architecture/testing.md
@@ -0,0 +1,36 @@
+Status: Active
+Last updated: 2026-09-22
+
+# Testing and Verification
+
+## Layout
+| Directory | Kind | Run by |
+| --- | --- | --- |
+| `tests/node/**` | Pure unit, contract, accounting, determinism, migration-SQL, guardrail self-tests (`tests/node/guardrails/**` run each `check:<name>` guardrail against `tests/fixtures/guardrails/**`) | `npm run check:tests:node` (inside `npm run check`), `npm test` |
+| `tests/next/**` | API route handlers and UI contracts with `next/server` mocked and Prisma mocked | `npm run check:tests:next` (inside `npm run check`), `npm test` |
+| `tests/db/**` | Real PostgreSQL: constraint existence, impossibility, conservation only (`AGENTS.md` DB truth surface) | `npm run test:db` (needs `DATABASE_URL`; CI `env-checks.yml`) |
+| `tests/node/accounting/*.spec.ts`, `tests/engine/optimality/*.spec.ts` | Property/oracle proofs | guardrails `check:accounting-invariants`, `check:no-mutation`, `check:replay-equals-materialized`, `check:engine-optimality` |
+| `tests/*.test.*`, `tests/guardrails/**`, `tests/authority/**`, `tests/migrations/**`, `tests/type/**` | Legacy copies of the `tests/node` / `tests/next` files (see Known issues) | `npm test` only |
+
+No test framework. Files are plain scripts using `node:assert/strict`; a file passes if it exits 0.
+Prisma is replaced by the mock in `scripts/lib/` through a loader, so nothing under `tests/node` or `tests/next` proves database behaviour.
+
+## Verification levels
+| Level | Command | Proves |
+| --- | --- | --- |
+| FAST | one file: `TZ=UTC npm run ts:esm -- --import ./scripts/lib/loaders/config.loader.mjs --import ./scripts/lib/loaders/prisma-mock.register.mjs -r tsconfig-paths/register tests/node/<file>` | that file only |
+| DOMAIN | `npm run report:domain-impact -- <changed paths>` prints the globs, then `npm run check:tests:node -- --filter=<glob,glob>` and `npm run check:tests:next -- --filter=<glob>` | the owning domain's registered tests. Output is labelled `FILTERED RUN`; never cite it as the gate |
+| FULL | `npm run check && npm test && npm run build` (what `npm run ci:verify` runs) | the authoritative contract. `check` = core guardrails + lint + typecheck + node tests + next tests |
+| DB | `npm run test:db` with a real Postgres and applied migrations | schema constraints |
+
+Required environment for FULL locally: `CHERRY_TMP_ROOT` (an existing dir, mode 700) and `CHERRY_VINE_SIGNATURE_MODE=enforce` (the build asserts production config). Guardrails need `rg`, `git`, `node` on PATH.
+
+## Where the tests for a domain are
+`scripts/guardrails/domains.manifest.json` `tests` field, rendered in `domains.md`, printed by `report:domain-impact`. Adding a test for a domain means adding it under `tests/node` or `tests/next` and, if it introduces a new file pattern, adding the glob to the manifest (the guardrail fails on globs that match nothing, so the list stays real).
+
+## Known issues (verified 2026-09-22)
+- 110 legacy test files at `tests/*.test.*`, `tests/guardrails`, `tests/authority`, `tests/migrations`, `tests/type` duplicate files in `tests/node` / `tests/next`; 2 pairs have diverged in logic (`engine-solver`, `api-sessions.user-context`). `check:guardrails-core` requires several of the legacy paths to exist, so removing them needs a guardrail update in the same change. `check:engine-optimality` runs the legacy `tests/engine/optimality` copy; `tests/node/engine/optimality` and `tests/accounting` run nowhere.
+- CI runs node and next tests three times (`check:tests:*`, then `ci:verify` -> `check` and `test`).
+
+## Related docs
+- `AGENTS.md` (PR checklist), `docs/ci-and-guardrails.md`, `docs/guardrails.md`
diff --git a/docs/architecture/typed-eslint-postmortem.md b/docs/architecture/typed-eslint-postmortem.md
deleted file mode 100644
index 24f9d00b..00000000
--- a/docs/architecture/typed-eslint-postmortem.md
+++ /dev/null
@@ -1,24 +0,0 @@
-Status: Deprecated
-Last updated: 2026-01-02
-
-# Typed ESLint Postmortem (Historical)
-
-This is a historical postmortem kept for context. It is not an active contract.
-
-## Current behavior
-- Lint and typecheck boundaries are enforced via tsconfig and guardrails; see `docs/ci-and-guardrails.md`.
-
-## Summary
-- Problem: typed ESLint surfaced files outside its TS program.
-- Root cause: lint scope diverged from TSConfig scope; scripts were typechecked under app semantics.
-- Key insight: ESLint is correct when it reports project-boundary violations.
-- Fix: introduce a TSConfig lattice (base/app/scripts/eslint) and explicit ESLint routing.
-- Invariant: every linted file belongs to exactly one TS program.
-- Result: editor and CI share one semantic universe with no implicit assumptions.
-
-## Future/Target behavior
-- None. This remains a historical record.
-
-## Related docs
-- `docs/ci-and-guardrails.md`
-- `docs/guardrails.md`
diff --git a/docs/cherry-core-loop-engine-vine-wallet-audit.md b/docs/cherry-core-loop-engine-vine-wallet-audit.md
index ede14ee9..119f4ffa 100644
--- a/docs/cherry-core-loop-engine-vine-wallet-audit.md
+++ b/docs/cherry-core-loop-engine-vine-wallet-audit.md
@@ -22,7 +22,7 @@ Code inspected:
 - Tests: `tests/*.test.js`.
 
 Docs consulted:
-- `docs/legal-constraints.md`, `docs/cherry-vision.md`, `docs/cherry-vine.md`, `docs/wallet-pass.md`, `docs/api.md`, `docs/buckets-rollover-plan.md`, `docs/system-overview.md`, `docs/repo-structure.md`, `AGENTS.md`, `.github/copilot-instructions.md`.
+- `docs/legal-constraints.md`, `docs/cherry-vision.md`, `docs/cherry-vine.md`, `docs/wallet-pass.md`, `docs/api.md`, `docs/buckets-rollover-plan.md`, `docs/system-overview.md`, `docs/repo-structure.md`, `AGENTS.md`.
 
 ## 1. Current behavior (verified)
 - Bank ingest (new):
diff --git a/docs/ci-and-guardrails.md b/docs/ci-and-guardrails.md
index 00c4bc97..2c779f2d 100644
--- a/docs/ci-and-guardrails.md
+++ b/docs/ci-and-guardrails.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-04-26
+Last updated: 2026-09-22
 
 # CI and guardrails
 
@@ -8,8 +8,9 @@ Last updated: 2026-04-26
 ### Pipeline
 - Runs on every push to `main` and all PRs via `.github/workflows/ci.yml`.
 - Steps (fail-fast):
-  1) `npm ci` (postinstall runs `prisma generate`)
-  2) `npm run ci:verify` (composite truth gate: check + build)
+  1) `npm ci` (postinstall runs `patch-package` and `prisma generate`)
+  2) `npm run check:guardrails`, `npm run check:tests:node`, `npm run check:tests:next` (early, granular failure)
+  3) `npm run ci:verify` (composite truth gate: check + test + build; `check:ci-must-run-check` requires it to be the last command)
 - Optional env lane (`.github/workflows/env-checks.yml`) provisions Postgres and runs:
   - `npx prisma generate`
   - `npx prisma migrate deploy`
diff --git a/docs/config-snapshot.md b/docs/config-snapshot.md
index 53f31289..f0be7ad8 100644
--- a/docs/config-snapshot.md
+++ b/docs/config-snapshot.md
@@ -157,7 +157,6 @@ workspace/
 
 # misc
 .DS_Store
-*.pem
 cookies.txt
 
 # editor settings
@@ -190,6 +189,9 @@ certs/
 *.pem
 *.pkpass
 
+.evidence/*
+!.evidence/.gitkeep
+
 # Local temp + Node compile cache
 .tmp/
 .cherry-tmp/
@@ -202,7 +204,6 @@ paste.txt
 abandoned_subsystems.md
 api_inventory.md
 architecture_map.md
-scripts/audit/full-checkout-audit.mts
 workspace_audit.md
 repo_index.json
 ```
@@ -9603,6 +9604,7 @@ export default nextConfig;
     "verify:cherry-diff-artifact": "npm run ts:esm -- scripts/execution/run.mts verify:cherry-diff-artifact",
     "verify:8.3-closure-artifact": "npm run ts:esm -- scripts/execution/run.mts verify:8.3-closure-artifact",
     "verify:repo-closure": "npm run ts:esm -- scripts/execution/run.mts verify:repo-closure",
+    "report:domain-impact": "npm run ts:esm -- scripts/execution/run.mts report:domain-impact",
     "check:routes": "npm run ts:esm -- scripts/guardrails/run.mts check:routes",
     "check:engine-freeze": "npm run ts:esm -- scripts/guardrails/run.mts check:engine-freeze",
     "check:engine-input-boundary": "npm run ts:esm -- scripts/guardrails/run.mts check:engine-input-boundary",
@@ -9672,6 +9674,7 @@ export default nextConfig;
     "check:accounting-proof-coverage": "npm run ts:esm -- scripts/guardrails/run.mts check:accounting-proof-coverage",
     "check:replay-equals-materialized": "npm run ts:esm -- scripts/guardrails/run.mts check:replay-equals-materialized",
     "check:no-mutation": "npm run ts:esm -- scripts/guardrails/run.mts check:no-mutation",
+    "check:domain-boundaries": "npm run ts:esm -- scripts/guardrails/run.mts check:domain-boundaries",
     "check:implicit-boolean": "npm run ts:esm -- scripts/guardrails/run.mts check:implicit-boolean",
     "check:branded-literal": "npm run ts:esm -- scripts/guardrails/run.mts check:branded-literal",
     "check:guardrail-self": "npm run ts:esm -- scripts/guardrails/run.mts check:guardrail-self",
@@ -10671,6 +10674,7 @@ export const EXECUTION = {
   'verify:8.3-closure-artifact': 'scripts/verify-8-3-closure-artifact.mts',
   'verify:cherry-diff-artifact': 'scripts/verify-cherry-diff-artifact.mts',
   'verify:repo-closure': 'scripts/verify-repo-closure.mts',
+  'report:domain-impact': 'scripts/domain-impact.mts',
 } as const;
 
 export type ExecutionName = keyof typeof EXECUTION;
@@ -10929,6 +10933,7 @@ export const GUARDRAILS = Object.freeze({
   'check:accounting-proof-coverage': ACCOUNTING_PROOF_COVERAGE_PATH,
   'check:replay-equals-materialized': REPLAY_EQUALS_MATERIALIZED_PATH,
   'check:no-mutation': NO_MUTATION_PATH,
+  'check:domain-boundaries': `${CHECK_PATH_BASE}domain-boundaries.mts`,
 } as const);
 
 export type GuardrailName = keyof typeof GUARDRAILS;
diff --git a/docs/core-loop-audit.md b/docs/core-loop-audit.md
deleted file mode 100644
index a06198d8..00000000
--- a/docs/core-loop-audit.md
+++ /dev/null
@@ -1,21 +0,0 @@
-Status: Deprecated
-Last updated: 2026-01-02
-
-# Cherry Core Loop Audit (Historical)
-
-This audit reflects a point-in-time review from 2025 and is no longer authoritative. It is kept for historical context only.
-
-## Current behavior
-- Use `docs/cherry-core-loop-engine-vine-wallet-audit.md`, `docs/api.md`, and `docs/cherry-vision.md` for current, code-aligned behavior.
-
-## Summary of historical scope
-- Covered `/api/scan`, sessions/ledger, engine/buckets, Vine ingest, and Wallet pass scaffolding.
-- Identified gaps around verification automation and Vine security that have since evolved.
-
-## Future/Target behavior
-- None. This document is archival.
-
-## Related docs
-- `docs/cherry-core-loop-engine-vine-wallet-audit.md`
-- `docs/api.md`
-- `docs/cherry-vision.md`
diff --git a/docs/doctrine.md b/docs/doctrine.md
index c9257d81..01d8f67f 100644
--- a/docs/doctrine.md
+++ b/docs/doctrine.md
@@ -46,7 +46,7 @@ Last updated: 2026-01-29
 ### 1.2 Allowed flow
 
 legacy state/context
-  -> fromLegacy (quarantine; time + DB allowed)
+  -> fromLegacy (adapter; receives already-loaded state and nowMs; no Date, no DB — check:engine-date and check:engine-prisma cover all of lib/engine/**)
   -> EngineInput (frozen, versioned)
   -> validateEngineInput (total, pure)
   -> solver (pure)
@@ -68,7 +68,7 @@ legacy state/context
 
 ### 2.1 Hard rule
 
-Guardrail environment may not import runtime modules. Ever.
+Guardrail environment may not import runtime modules, except the explicit allowlist in check:environment-import-integrity (brand registry, iso-date, config lock, authority invariants).
 
 Implication:
 - Guardrails must not import from lib/**.
diff --git a/docs/engine-ledger-boundary.md b/docs/engine-ledger-boundary.md
index 4a2ac10a..ba6da1d1 100644
--- a/docs/engine-ledger-boundary.md
+++ b/docs/engine-ledger-boundary.md
@@ -1,5 +1,5 @@
 Status: Draft
-Last updated: 2026-01-18
+Last updated: 2026-09-22
 
 # Engine ↔ Ledger Boundary
 
@@ -54,7 +54,7 @@ Last updated: 2026-01-18
 - A8 — Monotonic ordering / time correctness
   - Property tests (`tests/node/accounting/property.spec.ts`).
   - DB semantics tests (`tests/db/semantics/time-monotonicity.test.ts`).
-  - Engine boundary test (`tests/engine-accounting-time-order.test.ts`).
+  - Engine boundary test (`tests/node/engine-accounting-time-order.test.ts`).
 - A9 — Materialized == replayed
   - Replay test (`tests/node/accounting/replay-equals-materialized.spec.ts`).
   - DB semantics tests (`tests/db/semantics/accounting-replay.test.ts`).
diff --git a/docs/guardrails-todo.md b/docs/guardrails-todo.md
deleted file mode 100644
index 9037fcfb..00000000
--- a/docs/guardrails-todo.md
+++ /dev/null
@@ -1,34 +0,0 @@
-Status: Deprecated
-Last updated: 2026-01-02
-
-# Guardrails and Script Hygiene TODO (Historical)
-
-This document captured a migration plan that has since been implemented in guardrails and script standards. It is kept for historical context only.
-
-## Current behavior
-- Guardrail and script hygiene rules are enforced via `scripts/guardrails/registry.mts` and documented in `docs/guardrails.md` and `docs/script-standards.md`.
-- Guardrail helper exclusivity, script runner contracts, and registry completeness are enforced in CI.
-
-## Historical plan (archived)
-The sections below describe the original fixed-point migration plan. Use them only for context.
-
----
-
-### Guardrails & Script Hygiene — Fixed-Point Migration (Archived)
-
-#### Goal (archived)
-Reach a fixed point where all checks pass with zero warnings and no allowlists.
-
-#### Phases (archived)
-- Make rules explicit for scripts and guardrails.
-- Mechanically clean up script violations.
-- Ensure guardrails obey guardrails.
-- Lock the fixed point by enforcing CI entrypoints.
-
-## Future/Target behavior
-- None. This plan is complete and superseded by current guardrail docs.
-
-## Related docs
-- `docs/guardrails.md`
-- `docs/script-standards.md`
-- `docs/ci-and-guardrails.md`
diff --git a/docs/guardrails.md b/docs/guardrails.md
index ff1f9687..b037e864 100644
--- a/docs/guardrails.md
+++ b/docs/guardrails.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-01-31
+Last updated: 2026-09-22
 
 # Guardrails
 
@@ -28,6 +28,7 @@ Last updated: 2026-01-31
 - Accounting invariants run as deterministic guardrails over `lib/accounting` and its property tests.
 - Engine optimality guardrail runs bounded oracle tests via `check:engine-optimality`.
 - Engine optimality versions are frozen by `check:engine-optimality-version`.
+- Domain ownership and dependency direction are enforced from `scripts/guardrails/domains.manifest.json` (`check:domain-boundaries`).
 - Objective semantics are enforced for live objective paths via `check:objective-semantics`.
 - Guardrail runner supports `--aggregate` shadow execution; it accepts guardrail names only (no per-guardrail args) and reports in registry order by default (`--sort=name` for alphabetical).
 - Workflow presence, quoted expressions, runner-context, and delete-safety are enforced (`check:workflow-files-present`, `check:workflow-expressions-quoted`, `check:workflow-runner-context`, `check:no-workflow-force-delete`).
@@ -107,7 +108,7 @@ Last updated: 2026-01-31
 - NodeNext usage is quarantined to script configs only.
 - `docs/config-snapshot.md` must list every config file and match on-disk contents.
 - `check:config-snapshot` is read-only. Guardrails may verify the snapshot, but they must not rewrite it at runtime.
-- `.js` import specifiers are disallowed in app/components/lib/tests; they are permitted only in scripts.
+- Relative import specifiers carry a `.js` extension everywhere (resolved to `.ts` by tsx/Next); `@/` aliases are forbidden in app/components/lib/tests (`check:repo-guardrails`).
 - `next.config.ts` must exclude `.next/export-detail.json`, `.next/lock`, and `.next/server/proxy.js` from output tracing to avoid non-export build failures.
 - Enforcement: `check:config-snapshot`.
 
@@ -267,7 +268,7 @@ guaranteed to remain stable across different `engineVersion` values. Consumers m
 - DB materialized balances must match in-memory replayed ledger balances.
 - Enforcement: `check:db-accounting-replay`.
 
-### Guardrail 44 — Accounting Proof Coverage
+### Guardrail 44b — Accounting Proof Coverage
 
 - Every accounting axiom must be covered by at least one artifact and marked FULL.
 - Enforcement: `check:accounting-proof-coverage`.
@@ -410,7 +411,7 @@ Guardrail checks: `check:branded-literal` and `tests/node/guardrails/branded-typ
 - Engine-sensitive changes require a version bump and an engine-freeze baseline bump in a separate `chore(engine-freeze)` commit.
 - Guardrail check: `check:engine-version-bump`.
 
-### Guardrail 57 — Engine Version Import Restriction
+### Guardrail 57b — Engine Version Import Restriction
 
 - Imports of `lib/engine/version.ts` are limited to EngineInput and engine entrypoints.
 - Guardrail check: `check:engine-version-imports`.
@@ -550,6 +551,13 @@ Any duplication is a hard CI failure.
 - Direct `node`, `tsx`, or `ts-node` usage in script commands is forbidden.
 - Guardrail: `check:script-runner-contract`.
 
+### Guardrail 34 — Domain Boundaries
+
+- Every source file under `lib/`, `app/`, `components/`, `types/` is owned by exactly one domain declared in `scripts/guardrails/domains.manifest.json`.
+- A domain may only value-import domains listed in its `mayImport` (type-only imports are not checked). Known debt edges live in `allowedViolations` with a reason and must be removed when fixed.
+- Each domain's `tests` globs and `docs` paths must resolve to real files, so the manifest doubles as the change-impact map (`docs/architecture/domains.md`).
+- Guardrail: `check:domain-boundaries`. Set `CHERRY_DOMAIN_BOUNDARIES_REPORT=1` to print cross-domain edge counts instead of failing.
+
 ## Future/Target behavior
 
 - TODO: Expand guardrail coverage and tests as new risk areas are identified.
diff --git a/docs/home-ui-contract.md b/docs/home-ui-contract.md
index 327dae7b..5f69e84b 100644
--- a/docs/home-ui-contract.md
+++ b/docs/home-ui-contract.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-01-03
+Last updated: 2026-09-22
 
 # Home UI Contract (Idle / Observe)
 
@@ -65,7 +65,7 @@ Last updated: 2026-01-03
 - They must not be framed as allowances, approvals, recommendations, or limits enforced by Cherry.
 
 ## Guardrails & tests
-- Contract and guardrails enforced by `tests/home-ui-contract.test.ts` and Home surface tests; they ensure the bundle is authority-free, honors max lengths, and keeps Autopilot gated behind intent declaration.
+- Contract and guardrails enforced by `tests/node/home-ui-contract.test.ts` and Home surface tests; they ensure the bundle is authority-free, honors max lengths, and keeps Autopilot gated behind intent declaration.
 - If Home behavior changes, update this document, `lib/home/ui-bundle.ts`, and associated tests together.
 
 ## Related docs
diff --git a/docs/information-architecture.md b/docs/information-architecture.md
index a322b5fb..5b558b05 100644
--- a/docs/information-architecture.md
+++ b/docs/information-architecture.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-01-03
+Last updated: 2026-09-22
 
 # Information Architecture
 
@@ -31,7 +31,7 @@ Cherry’s surfaces are intentionally split into three buckets so marketing, pro
 - **Owner:** Devtools/Infra.
 
 ## Grouping rule (authoritative)
-- Any route under `app/(dev)` must be gated by dev middleware.
+- Any route under `app/(dev)` must be gated by `proxy.ts`. Today its matcher covers `/dev/:path*` and `/api/dev/:path*`; `/scan`, `/simulate`, `/sessions`, `/admin`, `/vine-simulator`, `/activity`, `/bank-simulator` are not matched (gap).
 - Any route under `app/(user)` must not import dev-only modules or expose dev tooling.
 - `app/(marketing)` must not import auth-required server actions.
 
diff --git a/docs/repo-structure-plan.md b/docs/repo-structure-plan.md
deleted file mode 100644
index c78f6dd8..00000000
--- a/docs/repo-structure-plan.md
+++ /dev/null
@@ -1,19 +0,0 @@
-Status: Deprecated
-Last updated: 2026-01-02
-
-# Repo Structure Plan (Historical)
-
-This plan is superseded by `docs/repo-structure.md`.
-
-## Current behavior
-- Use `docs/repo-structure.md` as the canonical layout reference.
-
-## Historical notes (archived)
-- The previous plan tracked a layout snapshot and proposed moves; no moves are required now.
-
-## Future/Target behavior
-- None. This document is archival.
-
-## Related docs
-- `docs/repo-structure.md`
-- `docs/ci-and-guardrails.md`
diff --git a/docs/repo-structure.md b/docs/repo-structure.md
index 3d72911c..16c55b33 100644
--- a/docs/repo-structure.md
+++ b/docs/repo-structure.md
@@ -1,119 +1,47 @@
 Status: Active
-Last updated: 2026-01-03
+Last updated: 2026-09-22
 
 # Cherry Repository Structure
 
-Use this as the source of truth for where things live and where new code should go. See `AGENTS.md` for operating rules and `docs/legal-constraints.md` for product guardrails.
+Where things live and where new code goes. Domain ownership (which capability owns which files) is in `docs/architecture/domains.md`; this page is the directory view.
 
 ## Current behavior (enforced / in code)
-- App Router routes are grouped under `app/(dev)`, `app/(user)`, and `app/(marketing)` with API routes in `app/api`.
-- The engine lives in `lib/engine.ts` and `lib/engine/*` with invariants in `lib/engine-invariants.ts`.
-- Prisma is only instantiated in `lib/prisma.ts` and consumed by adapters and API routes.
-- Scripts are kept under `scripts/` and executed via the `ts:esm` runner.
+- App Router routes are grouped under `app/(dev)` and `app/(user)`, with API routes in `app/api` and the sign-in card in `app/signin`. There is no `app/(marketing)` group yet.
+- Imports are relative with a `.js` extension; there is no `@/` path alias (`check:repo-guardrails` rejects it).
+- Prisma is instantiated only in `lib/prisma.ts`.
+- Scripts live under `scripts/` as `.mts` and run via `npm run ts:esm`; there is no `dist-scripts/` build output.
 
-## Top-Level Overview (curated)
 ```
 .
-├─ app/              # Next.js App Router UI + API entrypoints
-│  ├─ (dev)/(user)/(marketing)  # route groups for console, user app, and marketing
-│  └─ api/           # REST-ish handlers (scan, sessions, vine, wallet, admin, etc.)
-├─ components/       # Shared UI components (client/server as needed)
-├─ lib/              # Shared domain logic (engine, validation, enums, vine, wallet, auth helpers)
-├─ prisma/           # Database schema and migrations
-├─ scripts/          # Source scripts (ingest, seed, audit)
-├─ dist-scripts/     # Built script artifacts (keep generated outputs here)
-├─ data/             # MCC and other ingest inputs
-├─ docs/             # Product + technical docs (vision, vine, wallet, API, agents, audits, structure)
-├─ public/           # Static assets served by Next.js
-├─ types/            # Shared TypeScript types
-├─ .github/          # GitHub meta (e.g., copilot instructions)
-├─ Config files      # tsconfig*.json, eslint.config.mjs, next.config.ts, package*.json, postcss.config.mjs
-└─ .vscode/          # Editor settings (optional)
+├─ app/              # Next.js App Router: (dev) console, (user) shell, api/ route handlers, layout/providers
+├─ components/       # Shared UI (components/ui primitives, autopilot, simulations, layout, user)
+├─ lib/              # Domain logic; see docs/architecture/domains.md for ownership
+│  ├─ engine/        #   pure decision engine (core)
+│  ├─ authority/, accounting/, adapters/{contracts,*.ts}, schemas/, config/   # core
+│  ├─ adapters/runtime/, prisma.ts                                            # runtime
+│  └─ sessions/, vine/, wallet/, autopilot/, buckets/, bank/, income/, evaluator/, ...  # services
+├─ prisma/           # schema.prisma + migrations
+├─ scripts/          # guardrails (check-*.mts, guardrails/), execution scripts (execution/), loaders (lib/)
+├─ tests/            # node/ next/ db/ fixtures/ replay/ (+ legacy top-level copies, see docs/architecture/testing.md)
+├─ data/             # MCC inputs, dev bank CSV fixture
+├─ docs/             # architecture/ (start), doctrine, guardrails, product docs
+├─ types/            # global d.ts and compat shims (types/compat/README.md)
+├─ patches/          # patch-package patches (allowlisted in scripts/vendor-shims.allowlist.json)
+├─ public/           # static assets
+└─ proxy.ts          # dev-route gate (/dev/*, /api/dev/*)
 ```
 
-## Directory Purposes, Do/Don’t
-
-### app/
-- **Purpose:** All UI routes and API route handlers (Next.js App Router). This is the entrypoint for Observe/Recommend surfaces and API boundaries.
-- **Put here:** Route files (`page.tsx`, `layout.tsx`), server components, client components for route-specific UI, API `route.ts` handlers.
-- **Do NOT put:** Heavy domain logic (belongs in `lib/`), scripts, Prisma client instantiation (use `@/lib/prisma`).
-
-### components/
-- **Purpose:** Reusable UI blocks shared across routes.
-- **Put here:** Presentational components, shared client/server components that aren’t route-specific.
-- **Do NOT put:** Business logic, API helpers, data access.
-
-### lib/
-- **Purpose:** Shared domain logic and helpers.
-- **Put here:** Engine (`lib/engine.ts`, `lib/engine/*`, `lib/engine-invariants.ts`), enums, validation schemas, auth helpers (`with-user`, `auth`), vine helpers (`lib/vine/*`), wallet helpers (`lib/wallet/*`), points/verification helpers.
-- **Do NOT put:** Route handlers, Prisma client instantiation outside `lib/prisma`.
-
-### prisma/
-- **Purpose:** Database schema/migrations.
-- **Put here:** `schema.prisma`, migration folders, Prisma scripts under `prisma/scripts/` if needed.
-- **Do NOT move:** `schema.prisma` out of this directory.
-
-### scripts/
-- **Purpose:** Source scripts for maintenance/ingest/seed/audit.
-- **Put here:** TS/JS scripts run via npm scripts (e.g., ingest MCC, seed demo, audit integrity).
-- **Do NOT put:** Built artifacts (those belong in `dist-scripts/`).
-
-### dist-scripts/
-- **Purpose:** Generated/build outputs for scripts.
-- **Put here:** Compiled script artifacts if needed for deployment/runtime.
-- **Do NOT edit** by hand; treat as build output.
-
-### data/
-- **Purpose:** Input datasets (e.g., MCC TSV/PDF/JSON).
-- **Put here:** MCC sources and similar static inputs for ingest scripts.
-- **Do NOT put:** Generated outputs (those go to `dist-scripts/` or `data/mcc` outputs as appropriate).
-
-### docs/
-- **Purpose:** Canonical documentation.
-- **Contains:** Product identity (cherry-vision), hardware (cherry-vine), wallet pass, API reference, agent guidance, audits (core-loop-audit), repo structure/plan.
-- **Do NOT put:** Code, migrations, or scripts.
-
-### public/
-- **Purpose:** Static assets served by Next.js.
-- **Put here:** Images, icons, fonts, manifest files.
-- **Do NOT put:** Sensitive data or server code.
-
-### types/
-- **Purpose:** Shared TypeScript declarations.
-- **Put here:** Global types that don’t fit elsewhere.
-- **Do NOT put:** Business logic or React components.
-
-### .github/
-- **Purpose:** GitHub-specific config (actions, copilot instructions).
-- **Do NOT put:** App code.
-
-### Config files
-- **Purpose:** Tooling configuration (Next.js, TypeScript, ESLint, PostCSS, package scripts).
-- **Do NOT duplicate** conflicting configs; update central ones when structure changes.
-
-## Mapping to Cherry’s Product Model
-- **Observe/Recommend surfaces:** `app/` (UI routes like `/scan`, `/vine-simulator`, APIs like `/api/scan`, `/api/vine/order`).
-- **Evaluate (engine):** `lib/engine.ts` + invariants, enums, validation in `lib/schemas/*` and `lib/validation.ts` helpers.
-- **Reward (sessions/ledger):** `app/api/sessions/*` entrypoints backed by `lib` helpers and Prisma models (`RecommendationSession`, `CherryPointLedger`).
-- **Vine context:** `lib/vine/*`, `app/api/vine/order`, UI `/vine-simulator`.
-- **Wallet pass scaffold:** `lib/wallet/*`, `app/api/wallet/cherry-pass`.
-- **Data/model:** `prisma/` schema + migrations, seeded via `scripts/`.
-- **Docs:** `docs/` contains identity, hardware, wallet, API, and audit references to align code with product constraints.
-
-## Conventions for New Code
-- Keep API route handlers thin; push logic into `lib/`.
-- Use `@/lib/prisma` for DB access; no new Prisma clients elsewhere.
-- Validate inputs with Zod schemas in `lib/schemas/*` (and `lib/validation/autopilot/*` for Autopilot).
-- Place new scripts in `scripts/` (source) and build to `dist-scripts/` only if needed.
-- Keep docs in `docs/`; add cross-links when adding new surfaces.
-- Maintain Next.js App Router patterns (server-first; mark client components explicitly).
+## Conventions for new code
+- API handlers stay thin; logic goes into the owning `lib/<domain>/` module. Add the route to that domain's `owns` in `scripts/guardrails/domains.manifest.json`.
+- Validate with Zod schemas in `lib/schemas/*` via `parseJsonBody`.
+- Server-first components; interactive parts in a sibling `client.tsx` with `'use client'`.
+- New scripts: register in `scripts/execution/registry.mts` (see `scripts/AGENTS.md`).
+- Use `git mv` when relocating files and update the manifest in the same change.
 - Preserve public API paths unless intentionally versioned.
-- Use `git mv` for any relocations to keep history, and update path aliases/imports accordingly.
 
 ## Future/Target behavior (explicitly speculative)
-- Route groups may be reorganized as the dev console and user surfaces evolve; update this file alongside `docs/repo-structure-plan.md`.
+- A marketing surface under `app/(marketing)` when it lands (`docs/information-architecture.md`).
+- Services reach Prisma only through `lib/adapters/runtime` stores.
 
 ## Related docs
-- `AGENTS.md`
-- `docs/repo-structure-plan.md`
-- `docs/ci-and-guardrails.md`
+- `AGENTS.md`, `docs/architecture/index.md`, `docs/ci-and-guardrails.md`, `docs/information-architecture.md`
diff --git a/docs/routes-map.md b/docs/routes-map.md
index 20c37d0f..993f2883 100644
--- a/docs/routes-map.md
+++ b/docs/routes-map.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-01-02
+Last updated: 2026-09-22
 
 # Routes Map
 
@@ -9,7 +9,7 @@ Canonical map of key routes, aligned to `docs/information-architecture.md`. Curr
 
 | Path | Surface | Purpose | Owner | Notes |
 | --- | --- | --- | --- | --- |
-| /signin | User | Auth entry for user + dev shells | Auth/Product | Shared sign-in at root; do not bypass NextAuth. |
+| /signin | User | Auth entry for user + dev shells | Auth/Product | NextAuth `pages.signIn` target; `app/signin/` currently holds only `signin-card.tsx` (no `page.tsx`). |
 | /app | User | User shell for advisory entry | Product | Primary user shell. |
 | /app/onboarding | User | Onboarding hub | Product | Buckets/cards creation flows. |
 | /app/onboarding/buckets/new | User | New bucket flow | Product |  |
@@ -21,7 +21,7 @@ Canonical map of key routes, aligned to `docs/information-architecture.md`. Curr
 | /app/autopilot | User | Autopilot detail surface | Product | Lives under `/app`. |
 | /buckets | User | Buckets overview | Product | User shell outside `/app`. |
 | /history | User | Spend history timeline | Product |  |
-| /dev | Dev | Dev console dashboard | Devtools/Infra | Dev-only shell, gated by middleware. |
+| /dev | Dev | Dev console dashboard | Devtools/Infra | Dev-only shell; `proxy.ts` gates `/dev/:path*` and `/api/dev/:path*` only. |
 | /dev/buckets | Dev | Buckets management with diagnostics | Devtools/Infra | Dev-only. |
 | /dev/history | Dev | Spend history inspector | Devtools/Infra | Dev-only. |
 | /dev/statements | Dev | Statement rollups | Devtools/Infra |  |
diff --git a/docs/system-overview.md b/docs/system-overview.md
index bc55c520..d4102bd0 100644
--- a/docs/system-overview.md
+++ b/docs/system-overview.md
@@ -1,5 +1,5 @@
 Status: Active
-Last updated: 2026-01-03
+Last updated: 2026-09-22
 
 # Cherry System Overview
 
@@ -29,7 +29,7 @@ This file summarizes where those concepts live in code today and highlights gaps
   - Advisory-only: `/api/scan` in `app/api/scan/route.ts` runs the engine, allows `expectedAmountCents = 0`, and logs `DecisionEvent` telemetry but does not create sessions or ledger rows.
   - Context ingest: `/api/vine/order` (dev-only) accepts Vine terminal payloads or `OrderContext`, enforces freshness (~3 minutes), creates sessions, and logs authority decisions; simulator UI at `/vine-simulator`.
 - **Evaluate**
-  - Canonical engine: `lib/engine.ts` (+ invariants in `lib/engine-invariants.ts`), MCC-aware via `resolveCategory`; buckets are rolled in-memory and normalized via `lib/buckets-runtime.ts` before verdicts.
+  - Canonical engine: the solver in `lib/engine/solver.ts`, called by routes through `safeSolveDecisionForWorld` (`lib/engine/run.ts`) with an `EngineInput` built by `lib/engine/input/fromLegacy.ts`; the legacy MCC-aware engine (`lib/engine/legacy.ts`, `resolveCategory`) still supplies the response shape. Buckets are rolled in-memory and normalized via `lib/buckets-runtime.ts` before verdicts.
   - Zod schemas ensure typed inputs (`lib/schemas/*` + `parseJsonBody` in `lib/validation.ts`).
 - **Recommend**
   - Decisions flow back to clients (`ScanClient`, Vine simulator) with bucket/card verdicts and Cherry incentive offers; `RecommendationSession` stores verdicts, coverageMode, orderToken, expiry.
@@ -51,7 +51,7 @@ This file summarizes where those concepts live in code today and highlights gaps
 ---
 
 ## Current Strengths
-- Single engine path (`lib/engine.ts`) used by `/api/scan`, `/api/sessions`, `/api/vine/order`; bucket rollover applied in memory for verdict accuracy.
+- Single engine entrypoint (`safeSolveDecisionForWorld`) used by `/api/scan`, `/api/simulate`, `/api/sessions`, and via `lib/vine/run-recommendation.ts` by `/api/vine/order`; bucket rollover applied in memory for verdict accuracy.
 - Session + ledger lifecycle exists with anomaly handling, verification stubs, and bucket spend increment on confirm.
 - Dev tooling: Vine simulator UI, admin diagnostics and seed endpoints, MCC ingest script, integrity audit script.
 - UI surfaces: Manual Lookup & Rewards (`/scan`), Sessions list (`/sessions`), Vine simulator (`/vine-simulator`), Admin panel (`/admin`).
@@ -96,7 +96,7 @@ This file summarizes where those concepts live in code today and highlights gaps
 - Hardware: `docs/cherry-vine.md`
 - Wallet: `docs/wallet-pass.md`
 - API contract (including `/api/scan`): `docs/api.md`
-- Agent ops: `AGENTS.md`, `.github/copilot-instructions.md`
+- Agent ops: `AGENTS.md`; architecture map: `docs/architecture/index.md`
 
 ## Documentation index (all markdown, non-fixture)
 
@@ -104,9 +104,8 @@ This file summarizes where those concepts live in code today and highlights gaps
 - `README.md`
 - `AGENTS.md`
 - `CONTRIBUTING.md`
-- `AUDIT.md`
-- `DOC_REWRITE_TASK.md` (temporary)
-- `.github/copilot-instructions.md`
+- `AUDIT.md` (historical)
+- `CLAUDE.md`, `.github/copilot-instructions.md` (pointers to `AGENTS.md`)
 - `.github/pull_request_template.md`
 - `types/compat/README.md`
 
@@ -124,7 +123,6 @@ This file summarizes where those concepts live in code today and highlights gaps
 - `docs/dev-ui-parity.md`
 - `docs/shell-architecture.md`
 - `docs/repo-structure.md`
-- `docs/repo-structure-plan.md` (deprecated)
 
 ### Engine, authority, buckets
 - `docs/authority-v1.md`
@@ -152,20 +150,17 @@ This file summarizes where those concepts live in code today and highlights gaps
 - `docs/ci-and-guardrails.md`
 - `docs/guardrails.md`
 - `docs/guardrails-status.md`
-- `docs/guardrails-todo.md` (deprecated)
 - `docs/script-standards.md`
 - `docs/zod-style.md`
 - `docs/audit-format.md`
 
 ### Architecture notes
+- `docs/architecture/index.md` (start here), `domains.md`, `dependency-rules.md`, `data-flow.md`, `testing.md`, `decisions/`
 - `docs/architecture/auth.md`
-- `docs/architecture/typed-eslint-postmortem.md` (deprecated)
 - `docs/architecture/compat-shims.md`
 
 ### Audits, plans, and drafts
 - `docs/cherry-core-loop-engine-vine-wallet-audit.md`
-- `docs/core-loop-audit.md` (deprecated)
-- `docs/agent-run-summary.md` (deprecated)
 - `docs/marketing-hero-spec.md` (draft)
 
 ## Related docs
diff --git a/lib/engine/AGENTS.md b/lib/engine/AGENTS.md
new file mode 100644
index 00000000..4c5fcc28
--- /dev/null
+++ b/lib/engine/AGENTS.md
@@ -0,0 +1,24 @@
+# lib/engine — scoped rules
+
+Root contract: `../../AGENTS.md`. Invariants: `../../docs/doctrine.md` §1, §6, §8. This file adds only engine specifics.
+
+## Before editing anything here
+1. The engine feature freeze is ACTIVE (`docs/engine-roadmap.md`). No new action types, guardrail kinds, objective terms, or decision dimensions, and no reweighting or reinterpretation of existing ones, without a dated exception entry in that doc.
+2. Any change that can affect ordering, admissibility, accounting, or candidate space needs:
+   - a bump in `version.ts` (`engineBehaviorVersion`, `engineInputVersion`, `engineCandidateSpaceVersion`, or `engineAccountingVersion`, whichever applies);
+   - a separate commit `chore(engine-freeze): ...` that updates `scripts/guardrails/engine-freeze.policy.json` (and fixture hashes) — `check:engine-version-bump` requires that commit to be the latest touching the policy;
+   - the engine change itself in a commit prefixed `engine:` touching only `lib/engine/` (`check:change-isolation`, active when `CHERRY_COMMIT_MESSAGE` is set).
+3. Run `npm run check:guardrails` before the full gate: `check:engine-freeze`, `check:engine-version-gates`, `check:engine-optimality`, `check:accounting-invariants`, `check:objective-semantics` all live there.
+
+## Purity
+- No `Date` anywhere in this directory, including `input/fromLegacy.ts` (`check:engine-date` bans the token). Time is `nowMs` in the context.
+- No Prisma, no `lib/prisma`, no `lib/adapters/runtime` value imports (`check:engine-prisma`, `check:domain-boundaries`). Existing exceptions (`legacy.ts` -> `../legacy-engine.js`, `public.ts` -> `../engine-state.js`) are allowlisted debt; do not add more.
+- No `??` silent defaults, no float money math (`check:repo-guardrails`). Money is integer cents; scores use `OBJECTIVE_SCORE_UNIT`.
+- Never throw across the boundary from `safeSolveDecisionFor*`; return `{ ok: false, reason }`.
+
+## Map
+- `input/EngineInput.ts` — the only input contract (`check:engine-input-boundary`); `input/fromLegacy.ts` builds it; `input/validate.ts` is total.
+- `solver.ts` — `solveDecision`, `safeSolveDecisionForUser`. `run.ts` — `safeSolveDecisionForWorld` (what routes call).
+- `objective.ts`, `candidates.ts`, `guardrails.ts`, `simulate.ts`, `horizon/`, `uncertainty/`, `optimality/` — scoring, candidate space, hard constraints, rollouts, proofs.
+- `legacy.ts` + `legacy-mapper.ts` — the older MCC-aware engine and its mapping to the solver's decision shape; still consumed by routes for response compatibility.
+- Tests: `tests/node/engine*.test.*`, `tests/node/engine/**`; replay fixtures in `tests/replay/`.
diff --git a/package.json b/package.json
index 8abd66bb..20bc6be2 100644
--- a/package.json
+++ b/package.json
@@ -24,6 +24,7 @@
     "verify:cherry-diff-artifact": "npm run ts:esm -- scripts/execution/run.mts verify:cherry-diff-artifact",
     "verify:8.3-closure-artifact": "npm run ts:esm -- scripts/execution/run.mts verify:8.3-closure-artifact",
     "verify:repo-closure": "npm run ts:esm -- scripts/execution/run.mts verify:repo-closure",
+    "report:domain-impact": "npm run ts:esm -- scripts/execution/run.mts report:domain-impact",
     "check:routes": "npm run ts:esm -- scripts/guardrails/run.mts check:routes",
     "check:engine-freeze": "npm run ts:esm -- scripts/guardrails/run.mts check:engine-freeze",
     "check:engine-input-boundary": "npm run ts:esm -- scripts/guardrails/run.mts check:engine-input-boundary",
@@ -93,6 +94,7 @@
     "check:accounting-proof-coverage": "npm run ts:esm -- scripts/guardrails/run.mts check:accounting-proof-coverage",
     "check:replay-equals-materialized": "npm run ts:esm -- scripts/guardrails/run.mts check:replay-equals-materialized",
     "check:no-mutation": "npm run ts:esm -- scripts/guardrails/run.mts check:no-mutation",
+    "check:domain-boundaries": "npm run ts:esm -- scripts/guardrails/run.mts check:domain-boundaries",
     "check:implicit-boolean": "npm run ts:esm -- scripts/guardrails/run.mts check:implicit-boolean",
     "check:branded-literal": "npm run ts:esm -- scripts/guardrails/run.mts check:branded-literal",
     "check:guardrail-self": "npm run ts:esm -- scripts/guardrails/run.mts check:guardrail-self",
diff --git a/scripts/AGENTS.md b/scripts/AGENTS.md
new file mode 100644
index 00000000..271ba5d2
--- /dev/null
+++ b/scripts/AGENTS.md
@@ -0,0 +1,24 @@
+# scripts — scoped rules
+
+Root contract: `../AGENTS.md`. Standards: `../docs/script-standards.md`, `../docs/guardrails.md`. This file adds only what you need to add or change a script without tripping the meta-guardrails.
+
+## Two registries, one runner
+- Guardrails: a `check-<name>.mts` file at the top of `scripts/`, registered as `check:<name>` in `guardrails/registry.mts`, plus an identical `"check:<name>": "npm run ts:esm -- scripts/guardrails/run.mts check:<name>"` line in `package.json`, plus an entry in `docs/guardrails.md` in the same change (`check:guardrail-doc-sync`, `check:guardrail-name-path-bijection`, `check:no-orphan-check-files`).
+- Execution scripts: any other script, registered in `execution/registry.mts` and exposed as `"<prefix>:<name>": "npm run ts:esm -- scripts/execution/run.mts <prefix>:<name>"`. Allowed prefixes: `check: ingest: audit: backfill: cleanup: report: tmp: generate: verify:` (`check:no-orphan-scripts`).
+- Everything runs through `npm run ts:esm -- ...` (`CHERRY_TSESM=1`, `tsconfig.scripts.json`); scripts call `ensureTsEsm()` first. Forward args with `--`.
+
+## Rules the meta-guardrails enforce on script code
+- Guardrail scripts (`check-<name>.mts`, `guardrails/**`) may not import `lib/**`; read source text or JSON instead (`check:environment-import-integrity`, `check:guardrail-no-runtime-io`). Execution scripts may import `lib/**` but not `app/**` or `components/**`.
+- JSON via `guardrails/lib/read-json.mts` + a Zod schema; never `JSON.parse`. Subprocesses via `guardrails/lib/run-tool.mts`. Failures via `guardrails/lib/fail.mts` with `PREFIX` and `FIX`.
+- `catch (error: unknown)`; no `any`; explicit boolean conditions (`x.length > 0`, not `if (x)`); no `Date.now()` in guardrails.
+- Imports use `.mjs` extensions that resolve to `.mts`; no `@/` aliases; no `.ts` extensions.
+- Guardrails are read-only, deterministic, no network.
+- Docs must not reference a check script by file path; name the npm script (`check:<name>`) instead (`check:guardrail-execution`).
+
+## Self-tests
+Add `tests/node/guardrails/<name>.test.ts` that spawns the guardrail via `npm run ts:esm` against a fixture under `tests/fixtures/guardrails/` (most checks accept a `CHERRY_<NAME>_ROOT` or fixture env override) and asserts a non-zero exit plus the expected message.
+
+## Useful entry points
+- `npm run check:<name>` runs one guardrail; `npm run check:guardrails` runs the core tier; `npm run check:env` the env tier.
+- `npm run report:domain-impact -- <paths>` maps files to domains and tests.
+- `CHERRY_DOMAIN_BOUNDARIES_REPORT=1 npm run check:domain-boundaries` prints cross-domain edge counts.
diff --git a/scripts/check-domain-boundaries.mts b/scripts/check-domain-boundaries.mts
new file mode 100644
index 00000000..c5fd0ead
--- /dev/null
+++ b/scripts/check-domain-boundaries.mts
@@ -0,0 +1,260 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import { z } from 'zod';
+import { ensureTsEsm } from './lib/ensure-ts-esm.mjs';
+import { asMessage } from './guardrails/lib/error.mjs';
+import { fail } from './guardrails/lib/fail.mjs';
+import { readJsonFile } from './guardrails/lib/read-json.mjs';
+
+ensureTsEsm();
+
+const ROOT = process.env['CHERRY_DOMAIN_BOUNDARIES_ROOT'] ?? process.cwd();
+const PREFIX = 'check:domain-boundaries';
+const MANIFEST_PATH = path.join('scripts', 'guardrails', 'domains.manifest.json');
+const FIX =
+  'Assign the file to exactly one domain in scripts/guardrails/domains.manifest.json, or route the import through an allowed domain (see docs/architecture/dependency-rules.md).';
+
+const SCAN_GLOBS = [
+  'lib/**/*.{ts,tsx,js,jsx,mjs,cjs}',
+  'app/**/*.{ts,tsx,js,jsx,mjs,cjs}',
+  'components/**/*.{ts,tsx,js,jsx,mjs,cjs}',
+  'types/**/*.{ts,tsx,d.ts}',
+  'proxy.ts',
+];
+const IGNORE_GLOBS = ['**/node_modules/**', '**/.next/**', '**/__mocks__/**', '**/.tmp/**'];
+const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
+
+const DomainSchema = z
+  .object({
+    layer: z.enum(['core', 'runtime', 'service', 'surface']),
+    description: z.string().min(1),
+    owns: z.array(z.string().min(1)).min(1),
+    mayImport: z.array(z.string().min(1)),
+    tests: z.array(z.string().min(1)),
+    docs: z.array(z.string().min(1)),
+    invariants: z.array(z.string().min(1)).optional(),
+  })
+  .strict();
+
+const ManifestSchema = z
+  .object({
+    version: z.literal(1),
+    description: z.string(),
+    domains: z.record(z.string().min(1), DomainSchema),
+    allowedViolations: z.array(
+      z.object({ from: z.string().min(1), to: z.string().min(1), reason: z.string().min(1) }).strict()
+    ),
+  })
+  .strict();
+
+type Manifest = z.infer<typeof ManifestSchema>;
+
+type Edge = { from: string; to: string };
+
+function normalize(filePath: string): string {
+  return filePath.split(path.sep).join('/');
+}
+
+function guardrailFail(message: string, details?: string[]): never {
+  fail(PREFIX, message, { details, fix: FIX });
+}
+
+function loadManifest(): Manifest {
+  const parsed = ManifestSchema.safeParse(readJsonFile(path.join(ROOT, MANIFEST_PATH)));
+  if (!parsed.success) {
+    guardrailFail(`Invalid ${MANIFEST_PATH}`, parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`));
+  }
+  return parsed.data;
+}
+
+function validateManifestReferences(manifest: Manifest): string[] {
+  const problems: string[] = [];
+  const ids = new Set(Object.keys(manifest.domains));
+  for (const [id, domain] of Object.entries(manifest.domains)) {
+    for (const target of domain.mayImport) {
+      if (target !== '*' && !ids.has(target)) {
+        problems.push(`${id}.mayImport references unknown domain '${target}'`);
+      }
+    }
+    for (const doc of domain.docs) {
+      if (!fs.existsSync(path.join(ROOT, doc))) {
+        problems.push(`${id}.docs: missing file ${doc}`);
+      }
+    }
+    for (const testGlob of domain.tests) {
+      const matches = fg.sync(testGlob, { cwd: ROOT, ignore: IGNORE_GLOBS });
+      if (matches.length === 0) {
+        problems.push(`${id}.tests: glob matches no files: ${testGlob}`);
+      }
+    }
+  }
+  return problems;
+}
+
+function buildOwnership(manifest: Manifest, sourceFiles: string[]): { owner: Map<string, string>; problems: string[] } {
+  const owner = new Map<string, string>();
+  const problems: string[] = [];
+  const sourceSet = new Set(sourceFiles);
+  for (const [id, domain] of Object.entries(manifest.domains)) {
+    const matches = fg.sync(domain.owns, { cwd: ROOT, ignore: IGNORE_GLOBS, onlyFiles: true });
+    for (const match of matches) {
+      const file = normalize(match);
+      if (!sourceSet.has(file)) continue;
+      const existing = owner.get(file);
+      if (existing !== undefined && existing !== id) {
+        problems.push(`${file} is owned by both '${existing}' and '${id}'`);
+        continue;
+      }
+      owner.set(file, id);
+    }
+  }
+  for (const file of sourceFiles) {
+    if (!owner.has(file)) {
+      problems.push(`${file} is not owned by any domain`);
+    }
+  }
+  return { owner, problems };
+}
+
+function stripComments(content: string): string {
+  return content.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+}
+
+const IMPORT_FROM_REGEX = /^\s*(import|export)\s+(type\s+)?[^;'"]*?\bfrom\s+['"]([^'"]+)['"]/gm;
+const SIDE_EFFECT_IMPORT_REGEX = /^\s*import\s+['"]([^'"]+)['"]/gm;
+const DYNAMIC_IMPORT_REGEX = /\b(?:import|require)\(\s*['"]([^'"]+)['"]\s*\)/g;
+
+function valueImportSpecifiers(content: string): string[] {
+  const stripped = stripComments(content);
+  const specifiers: string[] = [];
+  let match: RegExpExecArray | null;
+  IMPORT_FROM_REGEX.lastIndex = 0;
+  while ((match = IMPORT_FROM_REGEX.exec(stripped)) !== null) {
+    const isTypeOnly = match[2] !== undefined;
+    const specifier = match[3];
+    if (isTypeOnly || specifier === undefined) continue;
+    specifiers.push(specifier);
+  }
+  SIDE_EFFECT_IMPORT_REGEX.lastIndex = 0;
+  while ((match = SIDE_EFFECT_IMPORT_REGEX.exec(stripped)) !== null) {
+    const specifier = match[1];
+    if (specifier !== undefined) specifiers.push(specifier);
+  }
+  DYNAMIC_IMPORT_REGEX.lastIndex = 0;
+  while ((match = DYNAMIC_IMPORT_REGEX.exec(stripped)) !== null) {
+    const specifier = match[1];
+    if (specifier !== undefined) specifiers.push(specifier);
+  }
+  return specifiers;
+}
+
+function resolveRelative(fromFile: string, specifier: string): string | null {
+  const base = path.resolve(ROOT, path.dirname(fromFile), specifier);
+  const candidates: string[] = [base];
+  const withoutJs = base.replace(/\.(js|mjs|cjs|jsx)$/, '');
+  for (const ext of RESOLVE_EXTENSIONS) {
+    candidates.push(`${withoutJs}${ext}`);
+    candidates.push(path.join(base, `index${ext}`));
+  }
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+      return normalize(path.relative(ROOT, candidate));
+    }
+  }
+  return null;
+}
+
+function collectEdges(sourceFiles: string[]): Edge[] {
+  const edges: Edge[] = [];
+  for (const file of sourceFiles) {
+    const content = fs.readFileSync(path.join(ROOT, file), 'utf8');
+    for (const specifier of valueImportSpecifiers(content)) {
+      if (!specifier.startsWith('.')) continue;
+      const resolved = resolveRelative(file, specifier);
+      if (resolved === null) continue;
+      edges.push({ from: file, to: resolved });
+    }
+  }
+  return edges;
+}
+
+function isAllowedEdge(manifest: Manifest, fromDomain: string, toDomain: string): boolean {
+  if (fromDomain === toDomain) return true;
+  const domain = manifest.domains[fromDomain];
+  if (domain === undefined) return false;
+  return domain.mayImport.includes('*') || domain.mayImport.includes(toDomain);
+}
+
+function printReport(manifest: Manifest, owner: Map<string, string>, edges: Edge[]): void {
+  const counts = new Map<string, number>();
+  for (const edge of edges) {
+    const fromDomain = owner.get(edge.from);
+    const toDomain = owner.get(edge.to);
+    if (fromDomain === undefined || toDomain === undefined || fromDomain === toDomain) continue;
+    const key = `${fromDomain} -> ${toDomain}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const lines = [...counts.entries()]
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map(([key, count]) => {
+      const [fromDomain, toDomain] = key.split(' -> ');
+      const allowed = isAllowedEdge(manifest, fromDomain ?? '', toDomain ?? '') ? 'allowed' : 'VIOLATION';
+      return `${key}: ${count} (${allowed})`;
+    });
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+function main(): void {
+  const manifest = loadManifest();
+  const referenceProblems = validateManifestReferences(manifest);
+  if (referenceProblems.length > 0) {
+    guardrailFail('Domain manifest references are stale', referenceProblems);
+  }
+
+  const sourceFiles = fg
+    .sync(SCAN_GLOBS, { cwd: ROOT, ignore: IGNORE_GLOBS, onlyFiles: true })
+    .map(normalize)
+    .sort();
+  const { owner, problems: ownershipProblems } = buildOwnership(manifest, sourceFiles);
+  if (ownershipProblems.length > 0) {
+    guardrailFail('Domain ownership must be total and exclusive', ownershipProblems);
+  }
+
+  const edges = collectEdges(sourceFiles);
+  if (process.env['CHERRY_DOMAIN_BOUNDARIES_REPORT'] === '1') {
+    printReport(manifest, owner, edges);
+    return;
+  }
+
+  const allowedKeys = new Set(manifest.allowedViolations.map((entry) => `${entry.from} -> ${entry.to}`));
+  const seenAllowed = new Set<string>();
+  const violations: string[] = [];
+  for (const edge of edges) {
+    const fromDomain = owner.get(edge.from);
+    const toDomain = owner.get(edge.to);
+    if (fromDomain === undefined || toDomain === undefined) continue;
+    if (isAllowedEdge(manifest, fromDomain, toDomain)) continue;
+    const key = `${edge.from} -> ${edge.to}`;
+    if (allowedKeys.has(key)) {
+      seenAllowed.add(key);
+      continue;
+    }
+    violations.push(`${key}: domain '${fromDomain}' may not import '${toDomain}'`);
+  }
+  const staleAllowances = [...allowedKeys].filter((key) => !seenAllowed.has(key));
+  if (staleAllowances.length > 0) {
+    guardrailFail('allowedViolations entries no longer occur; remove them', staleAllowances);
+  }
+  if (violations.length > 0) {
+    guardrailFail('Domain dependency violations detected', violations);
+  }
+  process.stdout.write(`check-domain-boundaries: ok (${sourceFiles.length} files, ${edges.length} edges, ${Object.keys(manifest.domains).length} domains)\n`);
+}
+
+try {
+  main();
+} catch (error: unknown) {
+  if (error instanceof Error && error.name === 'GuardrailFailure') throw error;
+  fail(PREFIX, `Guardrail crashed: ${asMessage(error)}`, { fix: FIX });
+}
diff --git a/scripts/check-engine-prisma.mts b/scripts/check-engine-prisma.mts
index 14cbd2f3..00ac5db7 100644
--- a/scripts/check-engine-prisma.mts
+++ b/scripts/check-engine-prisma.mts
@@ -15,7 +15,7 @@ type Violation = {
   message: string;
 };
 
-const ROOT = process.cwd();
+const ROOT = process.env['CHERRY_ENGINE_PRISMA_ROOT'] ?? process.cwd();
 const PREFIX = 'check:engine-prisma';
 const FIX = 'Remove Prisma usage from engine code and use adapters instead.';
 const TARGETS = [
@@ -24,11 +24,18 @@ const TARGETS = [
 ];
 const IGNORE = ['**/__tests__/**', '**/__mocks__/**', '**/.tmp/**'];
 
-const PATTERNS: Array<{ message: string; regex: RegExp }> = [
-  { message: "imports '@prisma/client'", regex: /\bfrom\s+['"]@prisma\/client['"]/ },
+// Import patterns run against raw source (string literals survive); usage patterns run against
+// comment/string-stripped source. `import type` from @prisma/client is allowed (types only).
+const IMPORT_PATTERNS: Array<{ message: string; regex: RegExp }> = [
+  {
+    message: "value-imports '@prisma/client'",
+    regex: /^\s*(?:import|export)\s+(?!type\b)[^;]*?\bfrom\s+['"]@prisma\/client['"]/m,
+  },
   { message: "requires '@prisma/client'", regex: /\brequire\s*\(\s*['"]@prisma\/client['"]\s*\)/ },
-  { message: "imports '@/lib/prisma'", regex: /\bfrom\s+['"]@\/lib\/prisma['"]/ },
-  { message: "requires '@/lib/prisma'", regex: /\brequire\s*\(\s*['"]@\/lib\/prisma['"]\s*\)/ },
+  { message: "imports lib/prisma", regex: /\bfrom\s+['"][^'"]*\/lib\/prisma(?:\.js)?['"]/ },
+  { message: "requires lib/prisma", regex: /\brequire\s*\(\s*['"][^'"]*\/lib\/prisma(?:\.js)?['"]\s*\)/ },
+];
+const USAGE_PATTERNS: Array<{ message: string; regex: RegExp }> = [
   { message: 'uses prisma client', regex: /\bprisma\s*\./ },
   { message: 'calls getPrisma()', regex: /\bgetPrisma\s*\(/ },
 ];
@@ -129,10 +136,15 @@ function scanFile(filePath: string): Violation[] {
   const relative = path.normalize(path.relative(ROOT, filePath));
   const violations: Violation[] = [];
 
-  for (const pattern of PATTERNS) {
-    const index = sanitized.search(pattern.regex);
-    if (index !== -1) {
-      const slice = sanitized.slice(0, index);
+  const scans: Array<{ text: string; patterns: Array<{ message: string; regex: RegExp }> }> = [
+    { text: content, patterns: IMPORT_PATTERNS },
+    { text: sanitized, patterns: USAGE_PATTERNS },
+  ];
+  for (const { text, patterns } of scans) {
+    for (const pattern of patterns) {
+      const index = text.search(pattern.regex);
+      if (index === -1) continue;
+      const slice = text.slice(0, index);
       const line = slice.split('\n').length;
       const lastNewline = slice.lastIndexOf('\n');
       const col = lastNewline === -1 ? index + 1 : index - lastNewline;
diff --git a/scripts/domain-impact.mts b/scripts/domain-impact.mts
new file mode 100644
index 00000000..1d60605c
--- /dev/null
+++ b/scripts/domain-impact.mts
@@ -0,0 +1,123 @@
+import * as path from 'node:path';
+import fg from 'fast-glob';
+import { z } from 'zod';
+import { ensureTsEsm } from './lib/ensure-ts-esm.mjs';
+import { fail } from './guardrails/lib/fail.mjs';
+import { readJsonFile } from './guardrails/lib/read-json.mjs';
+import { runTool } from './guardrails/lib/run-tool.mjs';
+
+ensureTsEsm();
+
+// Usage:
+//   npm run report:domain-impact -- <path> [<path> ...]   # domains + tests + docs for these files
+//   npm run report:domain-impact                          # same, for files changed vs origin/main (or main)
+// Read-only. Prints the DOMAIN-level verification an agent should run before the FULL gate.
+
+const ROOT = process.cwd();
+const PREFIX = 'report:domain-impact';
+const MANIFEST_PATH = path.join(ROOT, 'scripts', 'guardrails', 'domains.manifest.json');
+const FIX = 'Pass repo-relative paths, or run inside a git checkout with a main branch.';
+
+const ManifestSchema = z
+  .object({
+    domains: z.record(
+      z.string(),
+      z
+        .object({
+          layer: z.string(),
+          description: z.string(),
+          owns: z.array(z.string()),
+          mayImport: z.array(z.string()),
+          tests: z.array(z.string()),
+          docs: z.array(z.string()),
+          invariants: z.array(z.string()).optional(),
+        })
+        .passthrough()
+    ),
+  })
+  .passthrough();
+
+function normalize(filePath: string): string {
+  return filePath.split(path.sep).join('/');
+}
+
+function changedFiles(): string[] {
+  for (const base of ['origin/main', 'main']) {
+    const result = runTool('git', ['diff', '--name-only', `${base}...HEAD`]);
+    if (result.exitCode !== 0) continue;
+    const staged = runTool('git', ['diff', '--name-only', 'HEAD']);
+    const untracked = runTool('git', ['ls-files', '--others', '--exclude-standard']);
+    const all = `${result.stdout}\n${staged.stdout}\n${untracked.stdout}`;
+    return [...new Set(all.split('\n').map((line) => line.trim()).filter((line) => line.length > 0))];
+  }
+  fail(PREFIX, 'Unable to diff against origin/main or main', { fix: FIX });
+}
+
+function main(): void {
+  const manifest = ManifestSchema.safeParse(readJsonFile(MANIFEST_PATH));
+  if (!manifest.success) {
+    fail(PREFIX, 'Invalid domains manifest', { details: [manifest.error.message], fix: FIX });
+  }
+  const argFiles = process.argv.slice(2).map((arg) => normalize(path.relative(ROOT, path.resolve(ROOT, arg))));
+  const files = argFiles.length > 0 ? argFiles : changedFiles();
+
+  const ownerByFile = new Map<string, string>();
+  for (const [id, domain] of Object.entries(manifest.data.domains)) {
+    for (const file of fg.sync(domain.owns, { cwd: ROOT, onlyFiles: true })) {
+      ownerByFile.set(normalize(file), id);
+    }
+  }
+
+  const touched = new Map<string, string[]>();
+  const unowned: string[] = [];
+  for (const file of files) {
+    const owner = ownerByFile.get(file);
+    if (owner === undefined) {
+      unowned.push(file);
+      continue;
+    }
+    touched.set(owner, [...(touched.get(owner) ?? []), file]);
+  }
+
+  const lines: string[] = [];
+  lines.push(`Files considered: ${files.length}`);
+  for (const [id, ownedFiles] of [...touched.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+    const domain = manifest.data.domains[id];
+    if (domain === undefined) continue;
+    lines.push('');
+    lines.push(`DOMAIN ${id} (${domain.layer}): ${domain.description}`);
+    lines.push(`  files: ${ownedFiles.join(', ')}`);
+    lines.push(`  may import: ${domain.mayImport.length > 0 ? domain.mayImport.join(', ') : '(nothing)'}`);
+    const dependents = Object.entries(manifest.data.domains)
+      .filter(([other, def]) => other !== id && (def.mayImport.includes(id) || def.mayImport.includes('*')))
+      .map(([other]) => other);
+    lines.push(`  imported by: ${dependents.length > 0 ? dependents.join(', ') : '(nothing)'}`);
+    lines.push(`  tests: ${domain.tests.length > 0 ? domain.tests.join(' ') : '(none registered)'}`);
+    lines.push(`  docs: ${domain.docs.length > 0 ? domain.docs.join(' ') : '(none)'}`);
+    for (const invariant of domain.invariants ?? []) {
+      lines.push(`  invariant: ${invariant}`);
+    }
+  }
+  if (unowned.length > 0) {
+    lines.push('');
+    lines.push(`Outside lib/app/components (not domain-mapped): ${unowned.join(', ')}`);
+  }
+  const testGlobs = [...touched.keys()].flatMap((id) => manifest.data.domains[id]?.tests ?? []);
+  lines.push('');
+  lines.push('DOMAIN verification (not a substitute for the FULL gate):');
+  const nodeGlobs = testGlobs.filter((glob) => glob.startsWith('tests/node'));
+  const nextGlobs = testGlobs.filter((glob) => glob.startsWith('tests/next'));
+  if (nodeGlobs.length > 0) {
+    lines.push(`  npm run check:tests:node -- --filter=${nodeGlobs.join(',')}`);
+  }
+  if (nextGlobs.length > 0) {
+    lines.push(`  npm run check:tests:next -- --filter=${nextGlobs.join(',')}`);
+  }
+  if (touched.has('engine') || touched.has('authority') || touched.has('accounting')) {
+    lines.push('  npm run check:guardrails   # engine-sensitive: version gates, freeze, accounting proofs');
+  }
+  lines.push('FULL gate: npm run check && npm test && npm run build');
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+main();
diff --git a/scripts/execution/registry.mts b/scripts/execution/registry.mts
index a56e0893..a058c61a 100644
--- a/scripts/execution/registry.mts
+++ b/scripts/execution/registry.mts
@@ -35,6 +35,7 @@ export const EXECUTION = {
   'verify:8.3-closure-artifact': 'scripts/verify-8-3-closure-artifact.mts',
   'verify:cherry-diff-artifact': 'scripts/verify-cherry-diff-artifact.mts',
   'verify:repo-closure': 'scripts/verify-repo-closure.mts',
+  'report:domain-impact': 'scripts/domain-impact.mts',
 } as const;
 
 export type ExecutionName = keyof typeof EXECUTION;
diff --git a/scripts/guardrails/domains.manifest.json b/scripts/guardrails/domains.manifest.json
new file mode 100644
index 00000000..8f0249e1
--- /dev/null
+++ b/scripts/guardrails/domains.manifest.json
@@ -0,0 +1,661 @@
+{
+  "version": 1,
+  "description": "Domain ownership and allowed dependency direction for lib/, app/, components/. Checked by check:domain-boundaries. Type-only imports are not checked. Every source file under the scanned roots must be owned by exactly one domain.",
+  "domains": {
+    "shared": {
+      "layer": "core",
+      "description": "Pure helpers with no domain knowledge (errors, enums, text, numbers, money, ids, invariants, routes).",
+      "owns": [
+        "lib/errors.ts",
+        "lib/enums.ts",
+        "lib/text.ts",
+        "lib/numbers.ts",
+        "lib/money.ts",
+        "lib/ids.ts",
+        "lib/invariants.ts",
+        "lib/routes.ts",
+        "lib/formatCurrency.ts",
+        "lib/server-determinism-fixture.ts",
+        "lib/util/**",
+        "lib/api/**",
+        "types/**",
+        "lib/mcc.ts"
+      ],
+      "mayImport": [],
+      "tests": [
+        "tests/node/idempotency*.test.ts",
+        "tests/node/identity-determinism.test.ts"
+      ],
+      "docs": []
+    },
+    "schemas": {
+      "layer": "core",
+      "description": "Zod request/response contracts and the parseJsonBody boundary helper.",
+      "owns": [
+        "lib/schemas/**",
+        "lib/validation.ts"
+      ],
+      "mayImport": [
+        "shared"
+      ],
+      "tests": [
+        "tests/node/simulate-response-schema.test.js",
+        "tests/node/recommendation-temporal-schema.test.ts"
+      ],
+      "docs": [
+        "docs/zod-style.md",
+        "docs/api.md"
+      ]
+    },
+    "adapters-contracts": {
+      "layer": "core",
+      "description": "Pure TypeScript port interfaces (Clock, Logger, Digest, Entropy, stores, World). No implementations.",
+      "owns": [
+        "lib/adapters/*.ts",
+        "lib/adapters/contracts/**"
+      ],
+      "mayImport": [
+        "shared"
+      ],
+      "tests": [
+        "tests/node/adapters-contracts.test.ts"
+      ],
+      "docs": [
+        "docs/adapters.md"
+      ]
+    },
+    "engine": {
+      "layer": "core",
+      "description": "Deterministic decision engine: EngineInput contract, solver, objective, candidates, horizon, uncertainty. No time, no DB.",
+      "owns": [
+        "lib/engine/**",
+        "lib/engine.ts",
+        "lib/engine-invariants.ts"
+      ],
+      "mayImport": [
+        "shared",
+        "adapters-contracts",
+        "accounting"
+      ],
+      "tests": [
+        "tests/node/engine*.test.*",
+        "tests/node/engine/**",
+        "tests/node/objective-utility.test.ts"
+      ],
+      "docs": [
+        "docs/doctrine.md",
+        "docs/engine-roadmap.md",
+        "docs/engine-freeze.md",
+        "docs/engine-time-semantics.md",
+        "docs/engine-optimality/status.md",
+        "docs/simulation/objective-semantics.md"
+      ],
+      "invariants": [
+        "No Date/Date.now (check:engine-date)",
+        "No Prisma (check:engine-prisma)",
+        "EngineInput is the only input contract (check:engine-input-boundary)",
+        "Behavior/input/candidate/accounting version bumps + chore(engine-freeze) commit (check:engine-version-gates, check:engine-version-bump, check:engine-freeze)"
+      ]
+    },
+    "accounting": {
+      "layer": "core",
+      "description": "Double-entry ledger model and engine accounting proof.",
+      "owns": [
+        "lib/accounting/**"
+      ],
+      "mayImport": [
+        "shared",
+        "engine"
+      ],
+      "tests": [
+        "tests/node/accounting/**",
+        "tests/node/engine-accounting-*.test.ts"
+      ],
+      "docs": [
+        "docs/accounting-axioms.md",
+        "docs/accounting/invariants.md",
+        "docs/engine-ledger-boundary.md"
+      ],
+      "invariants": [
+        "check:accounting-invariants",
+        "check:no-mutation",
+        "check:replay-equals-materialized"
+      ]
+    },
+    "authority": {
+      "layer": "core",
+      "description": "Pure spend admissibility decisions and verdict policy.",
+      "owns": [
+        "lib/authority/**",
+        "lib/policy/**",
+        "lib/guards/**"
+      ],
+      "mayImport": [
+        "shared",
+        "adapters-contracts"
+      ],
+      "tests": [
+        "tests/node/authority/**",
+        "tests/node/authority-invariants.test.ts",
+        "tests/node/policy-totality.test.ts",
+        "tests/node/decision-event-recording.test.ts"
+      ],
+      "docs": [
+        "docs/authority-v1.md",
+        "docs/decision-event-ledger.md"
+      ],
+      "invariants": [
+        "check:authority-lint",
+        "check:authority-invariants",
+        "check:engine-date",
+        "check:engine-prisma"
+      ]
+    },
+    "config": {
+      "layer": "core",
+      "description": "Typed, frozen server/public config loaded once at the boundary.",
+      "owns": [
+        "lib/config/**",
+        "lib/base-url.ts"
+      ],
+      "mayImport": [
+        "shared"
+      ],
+      "tests": [
+        "tests/node/config-injection.test.ts",
+        "tests/node/no-env-smoke.test.ts"
+      ],
+      "docs": [
+        "docs/env-policy.md"
+      ],
+      "invariants": [
+        "check:config",
+        "check:config-init",
+        "check:config-lock"
+      ]
+    },
+    "persistence": {
+      "layer": "runtime",
+      "description": "The single Prisma client instance.",
+      "owns": [
+        "lib/prisma.ts"
+      ],
+      "mayImport": [
+        "config"
+      ],
+      "tests": [
+        "tests/db/**"
+      ],
+      "docs": [
+        "docs/schema-evolution.md",
+        "docs/storage-doctrine.md"
+      ]
+    },
+    "adapters-runtime": {
+      "layer": "runtime",
+      "description": "Concrete World wiring (Prisma stores, system clock, entropy, logger) and Prisma-backed engine/authority bridges.",
+      "owns": [
+        "lib/adapters/runtime/**",
+        "app/api/_clock.ts",
+        "lib/engine-state.ts",
+        "lib/legacy-engine.ts",
+        "lib/legacy-engine-types.ts",
+        "lib/replay/**"
+      ],
+      "mayImport": [
+        "shared",
+        "adapters-contracts",
+        "engine",
+        "authority",
+        "accounting",
+        "persistence",
+        "buckets",
+        "config",
+        "observability"
+      ],
+      "tests": [
+        "tests/node/engine-state.prisma.test.js",
+        "tests/node/engine-world.test.ts",
+        "tests/node/guardrails/prisma-adapter-totality.test.ts"
+      ],
+      "docs": [
+        "docs/adapters.md",
+        "docs/engine-state.md"
+      ]
+    },
+    "identity": {
+      "layer": "service",
+      "description": "NextAuth wiring, user context resolution, withUser guard.",
+      "owns": [
+        "lib/auth.ts",
+        "lib/with-user.ts",
+        "lib/user-context.ts",
+        "lib/identity/**",
+        "lib/dev/**",
+        "app/api/auth/**",
+        "app/api/user/context/**",
+        "app/signin/**"
+      ],
+      "mayImport": [
+        "shared",
+        "persistence",
+        "config",
+        "observability"
+      ],
+      "tests": [
+        "tests/next/user-context*.test.*",
+        "tests/next/*.user-context.test.*"
+      ],
+      "docs": [
+        "docs/architecture/auth.md"
+      ]
+    },
+    "buckets": {
+      "layer": "service",
+      "description": "Budget buckets: balance math, period rollover, regimes, freshness.",
+      "owns": [
+        "lib/buckets-runtime.ts",
+        "lib/buckets/**",
+        "lib/category-preferences.ts",
+        "app/api/buckets/**"
+      ],
+      "mayImport": [
+        "shared",
+        "persistence",
+        "schemas",
+        "identity",
+        "config",
+        "observability",
+        "income"
+      ],
+      "tests": [
+        "tests/node/bucket*.test.js",
+        "tests/node/buckets-periods.test.js",
+        "tests/node/category-preference-enum.test.js"
+      ],
+      "docs": [
+        "docs/buckets-rollover-plan.md"
+      ],
+      "invariants": [
+        "Balance math only via lib/buckets-runtime.ts; budgetAmount/spentCents authoritative, currentAmount legacy mirror"
+      ]
+    },
+    "cards": {
+      "layer": "service",
+      "description": "Cards and reward rules CRUD.",
+      "owns": [
+        "app/api/cards/**"
+      ],
+      "mayImport": [
+        "shared",
+        "persistence",
+        "schemas",
+        "identity",
+        "observability"
+      ],
+      "tests": [
+        "tests/next/api-rewards.validation.test.js"
+      ],
+      "docs": [
+        "docs/api.md"
+      ]
+    },
+    "income": {
+      "layer": "service",
+      "description": "Income and P2P classification over bank transactions; income regimes.",
+      "owns": [
+        "lib/income/**"
+      ],
+      "mayImport": [
+        "shared",
+        "persistence"
+      ],
+      "tests": [
+        "tests/node/income-*.test.js"
+      ],
+      "docs": [
+        "docs/income-regimes.md"
+      ]
+    },
+    "bank": {
+      "layer": "service",
+      "description": "Bank transaction ingest (idempotent on (userId, externalId)) and dev CSV provider.",
+      "owns": [
+        "lib/bank/**",
+        "lib/ingest/**",
+        "app/api/dev/bank/**"
+      ],
+      "mayImport": [
+        "shared",
+        "persistence",
+        "schemas",
+        "identity",
+        "config",
+        "observability",
+        "buckets",
+        "income"
+      ],
+      "tests": [
+        "tests/node/bank-ingest*.test.js"
+      ],
+      "docs": [
+        "docs/bank-ingest-notes.md"
+      ],
+      "invariants": [
+        "All ingest writes go through upsertBankTransactions; BankTransaction.id never set from ingest data"
+      ]
+    },
+    "evaluation": {
+      "layer": "service",
+      "description": "Advisory scan/simulate surfaces: MCC resolution, engine invocation, decision-event telemetry. Stateless with respect to sessions and ledger.",
+      "owns": [
+        "app/api/scan/**",
+        "app/api/simulate/**",
+        "app/api/simulations/**",
+        "app/api/mccs/**",
+        "app/api/user/merchants/**",
+        "lib/scan-helpers.ts",
+        "lib/scan-types.ts",
+        "lib/scan-client-state.ts",
+        "lib/simulation.ts",
+        "lib/simulation-adapter.ts",
+        "lib/mccCategoryMapper.ts"
+      ],
+      "mayImport": [
+        "shared",
+        "schemas",
+        "engine",
+        "authority",
+        "adapters-runtime",
+        "persistence",
+        "identity",
+        "buckets",
+        "config",
+        "observability"
+      ],
+      "tests": [
+        "tests/next/api-scan*.test.*",
+        "tests/next/api-simulate*.test.*",
+        "tests/node/scan-client-state.test.js",
+        "tests/node/simulation-adapter.test.js",
+        "tests/node/simulate-response-schema.test.js"
+      ],
+      "docs": [
+        "docs/api.md"
+      ]
+    },
+    "sessions": {
+      "layer": "service",
+      "description": "Recommendation sessions, confirm/verify lifecycle, Cherry Points ledger, verification stubs.",
+      "owns": [
+        "lib/sessions/**",
+        "lib/verification/**",
+        "lib/points.ts",
+        "lib/idempotency.ts",
+        "app/api/sessions/**",
+        "app/api/dev/pending-sessions/**",
+        "app/api/dev/verification/**"
+      ],
+      "mayImport": [
+        "shared",
+        "schemas",
+        "engine",
+        "authority",
+        "adapters-runtime",
+        "persistence",
+        "identity",
+        "buckets",
+        "config",
+        "observability",
+        "evaluation"
+      ],
+      "tests": [
+        "tests/next/api-sessions*.test.*",
+        "tests/node/sessions-bucket-reversal.test.js",
+        "tests/node/verification-session.test.js",
+        "tests/node/idempotency.test.ts"
+      ],
+      "docs": [
+        "docs/verification-flow.md",
+        "docs/decision-event-ledger.md"
+      ],
+      "invariants": [
+        "Confirm increments Bucket.spentCents once per session; ledger rows PENDING -> POSTED/REVOKED only via verify"
+      ]
+    },
+    "vine": {
+      "layer": "service",
+      "description": "Cherry Vine context beacon ingest (merchant + amount + timestamp). Never a payment device.",
+      "owns": [
+        "lib/vine/**",
+        "app/api/vine/**"
+      ],
+      "mayImport": [
+        "shared",
+        "schemas",
+        "engine",
+        "authority",
+        "adapters-runtime",
+        "persistence",
+        "identity",
+        "config",
+        "observability",
+        "sessions",
+        "evaluation"
+      ],
+      "tests": [
+        "tests/node/vine-*.test.js",
+        "tests/next/api-vine-order*.test.js",
+        "tests/next/vine-order-security.test.js",
+        "tests/node/run-recommendation.user-context.test.js"
+      ],
+      "docs": [
+        "docs/cherry-vine.md",
+        "docs/vine-security.md"
+      ]
+    },
+    "wallet": {
+      "layer": "service",
+      "description": "Cherry Pass storeCard scaffold; returns 501 unless fully configured and enabled.",
+      "owns": [
+        "lib/wallet/**",
+        "app/api/wallet/**"
+      ],
+      "mayImport": [
+        "shared",
+        "persistence",
+        "identity",
+        "config",
+        "observability"
+      ],
+      "tests": [
+        "tests/node/wallet-pass-config.test.js"
+      ],
+      "docs": [
+        "docs/wallet-pass.md"
+      ]
+    },
+    "autopilot": {
+      "layer": "service",
+      "description": "Autopilot preview/commit flow and simulation orchestration on top of the engine.",
+      "owns": [
+        "lib/autopilot/**",
+        "app/api/autopilot/**",
+        "lib/metrics/**",
+        "lib/validation/autopilot/**"
+      ],
+      "mayImport": [
+        "shared",
+        "schemas",
+        "engine",
+        "authority",
+        "adapters-runtime",
+        "persistence",
+        "identity",
+        "buckets",
+        "config",
+        "observability",
+        "sessions",
+        "evaluation"
+      ],
+      "tests": [
+        "tests/node/autopilot-*.test.*",
+        "tests/next/api-autopilot*.test.*",
+        "tests/next/autopilot-*.test.*",
+        "tests/node/onboarding-prereqs.test.ts"
+      ],
+      "docs": [
+        "docs/autopilot-master-spec.md",
+        "docs/autopilot-engine-adapter.md"
+      ]
+    },
+    "daily-state": {
+      "layer": "service",
+      "description": "Daily state computation and alerting.",
+      "owns": [
+        "lib/daily-state/**",
+        "lib/alerts/**",
+        "app/api/daily-state/**",
+        "app/api/internal/**"
+      ],
+      "mayImport": [
+        "shared",
+        "persistence",
+        "identity",
+        "config",
+        "observability",
+        "buckets",
+        "autopilot",
+        "schemas"
+      ],
+      "tests": [
+        "tests/node/alertPolicy.test.js",
+        "tests/node/type/daily-state.types.test.ts"
+      ],
+      "docs": [
+        "docs/daily-state.md"
+      ]
+    },
+    "evaluator": {
+      "layer": "service",
+      "description": "Offline engine evaluator. Read-only over Sessions/Ledger/Buckets; writes only HistoricalEngineEvaluation.",
+      "owns": [
+        "lib/evaluator/**"
+      ],
+      "mayImport": [
+        "shared",
+        "engine",
+        "persistence",
+        "buckets",
+        "income",
+        "adapters-runtime"
+      ],
+      "tests": [
+        "tests/node/offline-evaluator-*.test.js"
+      ],
+      "docs": [
+        "docs/offline-evaluator.md"
+      ],
+      "invariants": [
+        "Gate on CHERRY_OFFLINE_EVALUATOR_ENABLED; call assertOfflineEvaluatorModelsReady() first; derive runId via defaultRunIdForUser"
+      ]
+    },
+    "observability": {
+      "layer": "service",
+      "description": "Logging, metrics, activity feeds, health and admin stats.",
+      "owns": [
+        "lib/logger.ts",
+        "lib/log.ts",
+        "lib/logging.ts",
+        "lib/activity/**",
+        "lib/unified-activity.ts",
+        "lib/admin/**",
+        "app/api/activity/**",
+        "app/api/health/**",
+        "app/api/admin/**"
+      ],
+      "mayImport": [
+        "shared",
+        "persistence",
+        "identity",
+        "config",
+        "bank"
+      ],
+      "tests": [],
+      "docs": [
+        "docs/decision-event-ledger.md"
+      ]
+    },
+    "dev-tools": {
+      "layer": "surface",
+      "description": "Dev-only console pages, seeding, and inspection routes. Never shipped to users.",
+      "owns": [
+        "app/\\(dev\\)/**",
+        "app/api/seed-demo/**",
+        "app/api/dev/engine/**",
+        "lib/demo-seeder.ts"
+      ],
+      "mayImport": [
+        "*"
+      ],
+      "tests": [],
+      "docs": [
+        "docs/dev-route-inventory.md",
+        "docs/dev-ui-parity.md"
+      ]
+    },
+    "ui": {
+      "layer": "surface",
+      "description": "User-facing app shell, shared components, client API helpers.",
+      "owns": [
+        "app/\\(user\\)/**",
+        "app/layout.tsx",
+        "app/providers.tsx",
+        "components/**",
+        "lib/ui/**",
+        "lib/ui.ts",
+        "lib/client/**",
+        "lib/home/**",
+        "lib/dashboard.ts",
+        "lib/history.ts",
+        "proxy.ts"
+      ],
+      "mayImport": [
+        "*"
+      ],
+      "tests": [
+        "tests/next/home-screen-authority.test.tsx",
+        "tests/node/home-ui-contract.test.ts",
+        "tests/next/client-api.test.js"
+      ],
+      "docs": [
+        "docs/information-architecture.md",
+        "docs/routes-map.md",
+        "docs/shell-architecture.md",
+        "docs/home-ui-contract.md"
+      ]
+    }
+  },
+  "allowedViolations": [
+    {
+      "from": "lib/engine/legacy.ts",
+      "to": "lib/legacy-engine.ts",
+      "reason": "Legacy engine facade re-exports the Prisma-backed runtime bridge; importing lib/engine.ts loads Prisma. Engine-freeze change; track as debt."
+    },
+    {
+      "from": "lib/engine/public.ts",
+      "to": "lib/engine-state.ts",
+      "reason": "Autopilot swipe entrypoint reaches Prisma engine-state loader through the engine barrel. Engine-freeze change; track as debt."
+    },
+    {
+      "from": "lib/engine/public.ts",
+      "to": "lib/scan-helpers.ts",
+      "reason": "Value cycle engine -> scan-helpers -> engine. Engine-freeze change; track as debt."
+    },
+    {
+      "from": "lib/authority/replayAuthority.ts",
+      "to": "lib/adapters/runtime/authority.replay.prisma.ts",
+      "reason": "Pure module re-exports a runtime implementation. No importers; candidate for deletion."
+    }
+  ]
+}
diff --git a/scripts/guardrails/registry.mts b/scripts/guardrails/registry.mts
index 3682fc0c..a8ba3855 100644
--- a/scripts/guardrails/registry.mts
+++ b/scripts/guardrails/registry.mts
@@ -196,6 +196,7 @@ export const GUARDRAILS = Object.freeze({
   'check:accounting-proof-coverage': ACCOUNTING_PROOF_COVERAGE_PATH,
   'check:replay-equals-materialized': REPLAY_EQUALS_MATERIALIZED_PATH,
   'check:no-mutation': NO_MUTATION_PATH,
+  'check:domain-boundaries': `${CHECK_PATH_BASE}domain-boundaries.mts`,
 } as const);
 
 export type GuardrailName = keyof typeof GUARDRAILS;
diff --git a/scripts/run-tests-next.mts b/scripts/run-tests-next.mts
index 92b81c29..2c2928d5 100644
--- a/scripts/run-tests-next.mts
+++ b/scripts/run-tests-next.mts
@@ -27,11 +27,29 @@ const testFiles = fg
   })
   .sort();
 
-if (testFiles.length === 0) {
+// --filter=<glob>[,<glob>] narrows the run (DOMAIN-level verification). Never authoritative:
+// the FULL gate is `npm run check && npm test && npm run build`.
+const filterArg = process.argv.find((arg) => arg.startsWith('--filter='));
+const filteredFiles =
+  filterArg === undefined
+    ? testFiles
+    : fg
+        .sync(filterArg.slice('--filter='.length).split(',').filter((glob) => glob.length > 0), {
+          cwd: repoRoot,
+          absolute: true,
+          ignore: ['**/__mocks__/**', 'tests/fixtures/**', 'tests/db/**'],
+        })
+        .filter((file) => testFiles.includes(file))
+        .sort();
+if (filterArg !== undefined) {
+  process.stdout.write(`FILTERED RUN (${filteredFiles.length}/${testFiles.length} files); not a substitute for the full gate\n`);
+}
+
+if (filteredFiles.length === 0) {
   fail(PREFIX, 'No Next tests found under tests/next/**/*.test.{js,ts,tsx}', { fix: FIX });
 }
 
-for (const file of testFiles) {
+for (const file of filteredFiles) {
   process.stdout.write(`RUN ${path.relative(repoRoot, file)}\n`);
   const result = runTsEsm(
     file,
diff --git a/scripts/run-tests-node.mts b/scripts/run-tests-node.mts
index 9dd0a783..938b8a5a 100644
--- a/scripts/run-tests-node.mts
+++ b/scripts/run-tests-node.mts
@@ -27,11 +27,29 @@ const testFiles = fg
   })
   .sort();
 
-if (testFiles.length === 0) {
+// --filter=<glob>[,<glob>] narrows the run (DOMAIN-level verification). Never authoritative:
+// the FULL gate is `npm run check && npm test && npm run build`.
+const filterArg = process.argv.find((arg) => arg.startsWith('--filter='));
+const filteredFiles =
+  filterArg === undefined
+    ? testFiles
+    : fg
+        .sync(filterArg.slice('--filter='.length).split(',').filter((glob) => glob.length > 0), {
+          cwd: repoRoot,
+          absolute: true,
+          ignore: ['**/__mocks__/**', 'tests/fixtures/**', 'tests/db/**'],
+        })
+        .filter((file) => testFiles.includes(file))
+        .sort();
+if (filterArg !== undefined) {
+  process.stdout.write(`FILTERED RUN (${filteredFiles.length}/${testFiles.length} files); not a substitute for the full gate\n`);
+}
+
+if (filteredFiles.length === 0) {
   fail(PREFIX, 'No Node tests found under tests/node/**/*.test.{js,ts,tsx}', { fix: FIX });
 }
 
-for (const file of testFiles) {
+for (const file of filteredFiles) {
   process.stdout.write(`RUN ${path.relative(repoRoot, file)}\n`);
   const result = runTsEsm(
     file,
diff --git a/tests/fixtures/guardrails/repo/domain-boundaries/lib/a/x.ts b/tests/fixtures/guardrails/repo/domain-boundaries/lib/a/x.ts
new file mode 100644
index 00000000..f088f203
--- /dev/null
+++ b/tests/fixtures/guardrails/repo/domain-boundaries/lib/a/x.ts
@@ -0,0 +1,4 @@
+import { y } from '../b/y.js';
+import type { Y } from '../b/y.js';
+
+export const x: Y = y;
diff --git a/tests/fixtures/guardrails/repo/domain-boundaries/lib/b/y.ts b/tests/fixtures/guardrails/repo/domain-boundaries/lib/b/y.ts
new file mode 100644
index 00000000..b96154c2
--- /dev/null
+++ b/tests/fixtures/guardrails/repo/domain-boundaries/lib/b/y.ts
@@ -0,0 +1,2 @@
+export type Y = number;
+export const y: Y = 1;
diff --git a/tests/fixtures/guardrails/repo/domain-boundaries/scripts/guardrails/domains.manifest.json b/tests/fixtures/guardrails/repo/domain-boundaries/scripts/guardrails/domains.manifest.json
new file mode 100644
index 00000000..c8ae4721
--- /dev/null
+++ b/tests/fixtures/guardrails/repo/domain-boundaries/scripts/guardrails/domains.manifest.json
@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "description": "fixture",
+  "domains": {
+    "a": { "layer": "core", "description": "a", "owns": ["lib/a/**"], "mayImport": [], "tests": [], "docs": [] },
+    "b": { "layer": "core", "description": "b", "owns": ["lib/b/**"], "mayImport": ["a"], "tests": [], "docs": [] }
+  },
+  "allowedViolations": []
+}
diff --git a/tests/node/guardrails/domain-boundaries.test.ts b/tests/node/guardrails/domain-boundaries.test.ts
new file mode 100644
index 00000000..c2b71a1a
--- /dev/null
+++ b/tests/node/guardrails/domain-boundaries.test.ts
@@ -0,0 +1,21 @@
+import * as assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(__filename), '..', '..', '..');
+const fixtureRoot = path.join(repoRoot, 'tests', 'fixtures', 'guardrails', 'repo', 'domain-boundaries');
+
+const result = spawnSync('npm', ['run', 'ts:esm', '--', 'scripts/check-domain-boundaries.mts'], {
+  cwd: repoRoot,
+  encoding: 'utf8',
+  env: { ...process.env, CHERRY_DOMAIN_BOUNDARIES_ROOT: fixtureRoot },
+});
+
+const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+assert.notEqual(result.status, 0, `expected guardrail to fail for fixture, got status=${result.status ?? 'null'}`);
+assert.equal(output.includes("domain 'a' may not import 'b'"), true, `expected value-import violation, got: ${output}`);
+assert.equal(output.includes('lib/a/x.ts -> lib/b/y.ts'), true, 'expected file-level edge in output');
+
+process.stdout.write('domain-boundaries: ok\n');
diff --git a/tests/node/guardrails/engine-prisma-import.test.ts b/tests/node/guardrails/engine-prisma-import.test.ts
new file mode 100644
index 00000000..931973d9
--- /dev/null
+++ b/tests/node/guardrails/engine-prisma-import.test.ts
@@ -0,0 +1,20 @@
+import * as assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const repoRoot = path.resolve(path.dirname(__filename), '..', '..', '..');
+const fixtureRoot = path.join(repoRoot, 'tests', 'fixtures', 'guardrails', 'repo', 'engine-prisma');
+
+const result = spawnSync('npm', ['run', 'ts:esm', '--', 'scripts/check-engine-prisma.mts'], {
+  cwd: repoRoot,
+  encoding: 'utf8',
+  env: { ...process.env, CHERRY_ENGINE_PRISMA_ROOT: fixtureRoot },
+});
+
+const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+assert.notEqual(result.status, 0, `expected guardrail to fail for fixture, got status=${result.status ?? 'null'}`);
+assert.equal(output.includes("value-imports '@prisma/client'"), true, `expected import violation, got: ${output}`);
+
+process.stdout.write('engine-prisma-import: ok\n');