docs(domains): make the runbooks true against the code

[goetchstone]

The AI-assistant catalog will be authored from these runbooks, so a wrong filter documented here becomes a wrong number shown to a user with no indication it's wrong. This is a truth pass, not an expansion — no new sections, no date stamps, no de-specifying real vendor names.

Method

A verifier per runbook that had to open the cited code before writing anything, then an adversarial auditor that tried to refute each edit with a file:line.

The auditors caught 19 bad edits from the first pass — including one that contradicted a commit already on main. Those refutations were themselves re-checked before being applied, and two were rejected: the sales-orders status-downgrade paragraph and the returns customer-portal rows are responsive to real omissions, not overreach.

The bigger corrections

doc	was
returns.md	A status machine that doesn't exist — APPROVED/REFUNDED/EXCHANGED aren't ReturnStatus members. Plus a restockingFeePct field and fee calculation; grep for "restocking" over app/src and app/prisma returns nothing. Deleted, not softened.
staff-auth.md	"The permission layer gates exactly one route." Recounted: of 337 route files carrying either guard, 216 gate on a capability and 121 on the role enum (8 use both).
pos.md	processorTxnId described as unique with INSERT-on-conflict webhook semantics. No unique index exists; idempotency comes from a PENDING filter.
accounting.md	Named a SystemGLMapping section that doesn't exist; pointed the JE generator at a GET-only endpoint.
sales-orders.md	"The POS does not send statuses. Do not look for a status field." It does — and cancelled/returned are load-bearing.
reporting.md	22 dead Pages-Router URLs; claimed the revenue-status filter was universal (it was absent from four reports until #95).
config-presets.md	Said the roles preset controls which Role rows exist. applyPreset never deletes a Role.

The mangled sentences

Nine sentences were repaired that a scrubbing pass in the initial public release had broken — an order-number prefix replaced by the literal phrase "the return prefix":

late-the return prefix-inside-period flagged
prefix-swap: the sale prefix→the return prefix, the sale prefix→the return prefix, the sale prefix→the return prefix

Rewritten to name the mechanism (isReturnOrder / RETURN_STORE_SUFFIX) rather than restore a tenant literal — the direction the rest of this work is going. Where the mechanism couldn't be located in code (service-dispatch's order-number token), the claim was dropped rather than guessed.

Code findings, tracked separately

• feat(pos): enforce the till variance thresholds pos.md already specifies #53 — /api/warehouse/returns/queue and /pickups are bare getServerSession with no role check, behind pages that are MANAGER/ADMIN/WAREHOUSE gated. Customer names, phones and pickup addresses.
• fix(accounting): refunds must reduce cash in the daily journal #52 — isReturnOrder hardcodes one tenant's RS prefix (shared.ts:210, commented "Returns Saybrook").
• docs: ship the agent layer FRAMEWORK.md already specifies #51 — the default business timezone ships as America/New_York.

Verification state, stated plainly

• Adversarially verified by agent: accounting, sales-orders, returns, commission, reporting
• Verified by hand: staff-auth, pos, config-presets — their audit batch died twice on API errors, so I re-derived the route counts, the REGISTER permission set, the absent processorTxnId index and the applyRoles delete behaviour myself rather than shipping them unchecked.

markdownlint + prettier clean. Formatting-only churn on the other 26 domain docs was reverted to keep this diff readable.

🤖 Generated with Claude Code