Breakdown: Docs accuracy — credentials, AI claims, and retiring the feature matrix

• scope-slug: docs-accuracy · source: Jamie's platform-audit notes (2026-08-17) + the docs contradictions catalogued by the web-app feature audit; no scope.md behind this batch. Notes quoted per stub.
• initiative: Refine the bridge / objective: Q2-2026 Objective 4 — Build Brand & Credibility
• personas: Admin (docs readers are the team; the docs are the product's source of truth)

What I understood

Three corrections to apps/docs. Live demo credentials — including a shared mailbox password — are published in plaintext on the demo-environment page and must go. The requirements page claims the BRD agent runs on "Claude Haiku via the OpenRouter API", which is false — it runs through Vercel's AI Gateway with Haiku as the default agent model and Sonnet for deep extraction — and Jamie wants the claim corrected. And the file the docs declare as the "source of truth" feature-role matrix describes the retired platform/api architecture; Jamie's ruling: retire it outright, treat its ten catalogued contradictions as wrong on the matrix's side, and find a better way to present features than the spreadsheet-shaped page.

Where it sits

apps/docs only (business section + technical/demo-environment + public/ assets). No platform code.

Build order

1. remove-demo-credentials — strip published credentials from the demo-environment page — depends-on: none
2. fix-ai-provider-claims — correct the OpenRouter claim to the real gateway + models — depends-on: none
3. retire-feature-matrix — remove the stale master matrix; establish the per-section pages as the presentation of features — depends-on: none

Parallelizable

All three are independent; ordered by risk (credentials first).

Out of scope (whole scope)

• Rewriting the per-section business docs (they were accurate enough to audit against).
• Rotating the exposed demo credentials themselves — an ops action outside the repo; flagged in stub 1's notes so it isn't lost.
• The docs' other minor contradictions (invoice manual-vs-auto wording, status-viewer path) beyond what stub 3's cleanup naturally touches — each Ship-stage docs-sync keeps chipping at these.

Stub: Correct the docs' AI provider and model claims

• feature-slug: fix-ai-provider-claims
• scope: docs-accuracy
• personas: Admin
• initiative: Refine the bridge / objective: Q2-2026 Objective 4 — Build Brand & Credibility
• depends-on: none
• sequence: 2 of 3

Problem

The service-journey requirements page says the BRD agent runs on "Claude Haiku via the OpenRouter API". It doesn't — every agent routes through Vercel's AI Gateway (AI SDK v6), with anthropic/claude-haiku-4.5 as the default agent model and anthropic/claude-sonnet-5 for deep extraction. Two docs pages disagree with each other and one is flatly wrong. Jamie's note: "update the false openrouter claim in the docs to what we actual use vercel's AI gatewat with a default model of sonnet/haiku."

Proposed change

Correct every AI provider/model claim in apps/docs to the single true statement (Vercel AI Gateway; Haiku 4.5 default agent model, Sonnet 5 deep-extraction model), stated once on the most technical page and referenced (not restated) elsewhere, so the next model bump has one place to edit.

Acceptance criteria (rough)

• No mention of OpenRouter remains in apps/docs.
• The requirements page, build-the-bridge initiative page, and technical applications page agree, with the model detail stated in exactly one place.
• The stated models match packages/services/src/ai/core/agent.ts at merge time.

Out of scope (this feature)

• Changing the actual models or gateway config.
• The AI billing runbook (ai-platform-enablement/ai-gateway-billing-unlock writes that).

Notes for Define

Evidence: wrong claim in apps/docs/app/business/service-journey/requirements/page.mdx ("Claude Haiku via the OpenRouter API"); partially-right claim in business/initiatives/build-the-bridge ("BRDAgent (Claude Haiku 4.5)"); truth in packages/services/src/ai/core/agent.ts (DEFAULT_AGENT_MODEL, DEEP_EXTRACTION_MODEL). Follow docs-sync conventions for the edit. touches: apps/docs only.

Stub: Remove published demo credentials from the docs

• feature-slug: remove-demo-credentials
• scope: docs-accuracy
• personas: Admin
• initiative: Refine the bridge / objective: Q2-2026 Objective 4 — Build Brand & Credibility
• depends-on: none
• sequence: 1 of 3

Problem

The demo-environment docs page publishes live credentials in plaintext: the shared demo password for all six persona logins, the filler customer logins, and a shared mailbox address with its password. The docs site is the team's reference, but plaintext credentials in a repo-backed page are one leak (or one over-broad share) from a compromised demo tenant and mailbox. Jamie's note: "remove the old live demo credentials in the docs page."

Proposed change

Strip every credential from the page — passwords gone entirely, the persona table keeps names/roles/emails only if the emails are considered non-sensitive (open question), and the page instead says where credentials live (the team's secret store) without saying what they are. Sweep the rest of apps/docs and the repo's markdown for the same strings so no copy survives elsewhere.

Acceptance criteria (rough)

• No password appears anywhere in apps/docs (or any repo markdown) — verified by searching for the known strings before and after.
• The demo-environment page still tells a team member how to get access (pointer to the secret store / who to ask), so the runbook remains usable.
• The provisioning runbook's steps still make sense without inline credentials.

Out of scope (this feature)

• Rotating the exposed credentials (demo logins and the shared mailbox) — ops action outside the repo, but it must happen since git history retains the strings; flag to Jamie at pickup. Note: the migration to a rewritten history is not worth it; rotation is.

Open questions

• Q1: Do the demo+<role>@apoyar.eu addresses stay on the page (they're semi-public by design, used in the seeder's seat resolution) or go too? Recommend they stay — the seeder docs need them — with only passwords removed.
• Q2: Where do the credentials actually live going forward (1Password? Vercel env?) — the page should point at the agreed place; Jamie to name it.

Notes for Define

Evidence: apps/docs/app/technical/demo-environment/page.mdx (persona table with the shared demo password, filler logins, shared mailbox address with its password — the strings are deliberately not repeated here; git history retains them, which is why rotation is flagged). The storyline's canonical emails live in code (packages/services/src/db/services/demo-data/storyline/default.ts) — the docs can reference that file rather than duplicating. touches: apps/docs only.

Answers from Jamie — interrogation 2026-08-17

Recorded by the intake-easy-features session; these rulings bind Define.

• Q1 (demo+<role>@apoyar.eu addresses): strip both — addresses AND passwords all leave the page; the page points entirely at the secret store.
• Q2 (where credentials live): Vercel env vars — credentials live as environment variables on the Vercel project; the docs point admins there.
• Rotation flag: acknowledged — the exposed demo passwords and shared mailbox must be rotated as an ops action regardless (git history retains the strings).

Stub: Retire the stale feature-role matrix

• feature-slug: retire-feature-matrix
• scope: docs-accuracy
• personas: Admin
• initiative: Refine the bridge / objective: Q2-2026 Objective 4 — Build Brand & Credibility
• depends-on: none
• sequence: 3 of 3

Problem

apps/docs/public/feature-role-matrix.md — declared "the source of truth" by the feature-role-matrix index page — documents the retired apps/platform + apps/api architecture, lacks every newer feature, and contradicts the live per-section pages in at least ten catalogued places (vendor lead access, proposal visibility for managers, admin BRD capabilities, and more). Jamie's ruling: "remove the feature matrix from the docs, it should be retired. Figure out a better way to display the features, the excel spreadsheet is a nightmare of a setup, the ten contradictions of the feature matrix can entirely be assumed to be wrong from the feature matrix point of view."

Proposed change

Delete the stale master file and its "source of truth" framing; promote the per-section feature-role-matrix pages to be the presentation of features; and where those pages currently mirror the master's spreadsheet shape, restructure toward something maintainable — the strongest candidate being generation from the code that already knows the answer (the permission registry + role templates + route policies, which the scope viewer at /admin/settings/scope already renders live). Correct the known per-section contradictions in favour of the live pages/code while in there (vendor lead access, manager proposal visibility).

Acceptance criteria (rough)

• public/feature-role-matrix.md is gone and nothing links to it; the index page no longer names a spreadsheet as the source of truth.
• The per-section pages stand alone and no longer contradict the roles page on the ten catalogued points (resolve each toward the live behaviour).
• A stated maintenance story exists for feature/role presentation — either "hand-maintained per-section pages, one seam each" or a generated view from the permission registry — chosen deliberately and written down on the index page.

Out of scope (this feature)

• Building a full generated docs pipeline if the ruling is to keep hand-maintained pages (see open question) — this stub must stay one PR.
• Changing actual permissions to match docs — code wins; docs follow.

Open questions

• Q1: How far to take generation in this PR? Options: (a) retire + fix contradictions only, point readers at /admin/settings/scope for live truth; (b) also generate a static role-capability table into the docs from PLATFORM_ROLE_TEMPLATE_DEFAULTS at build time. Recommend (a) now, (b) as a follow-up chore if wanted — Jamie to pick at pickup.
• Q2: public/taxonomy-governance-matrix.md has the same legacy-architecture framing — retire it in the same sweep or leave it? Check its inbound links at Define.

Notes for Define

Evidence: the ten contradictions are catalogued in the web-app feature audit (vendor lead access; manager proposal visibility; admin lead-vs-BRD capabilities; invoice manual-vs-auto; BRD model claim (stub 2 fixes); status-viewer path /admin/status vs /admin/settings/statuses; demo-data path split; milestone completion trigger; negotiation loop presence; matrix architecture). Live truth sources: per-section business/feature-role-matrix/* pages, packages/services/src/permissions/defaults.ts, apps/web/lib/route-policies.ts, and the scope viewer. Follow docs-sync + Nextra conventions (_meta.ts when pages move). touches: apps/docs only.

Answers from Jamie — interrogation 2026-08-17

Recorded by the intake-easy-features session; these rulings bind Define.

• Q1 (how far): option (a) — retire the matrix and fix contradictions now, pointing readers at /admin/settings/scope for live truth; the generated static table is a follow-up chore.
• Q2 (taxonomy-governance-matrix.md): retire it in the same sweep, subject to the inbound-link check at Define.