The development guide drifted as portal-admin shipped, the docs site
landed, and Prisma stayed pinned at 6.x. Surgical pass.
Section 1 (Repo layout):
* Add `apps/portal-admin/` and `apps/portal-admin-e2e/` — both
exist on `main` since #134.
* Drop the phantom `prisma.config.ts` (Prisma 6.x doesn't ship
one) and fix the "Prisma 7" tag to "Prisma 6.x" with the
ADR-0006 pin reference.
* Add `docs/index.md`, `docs/architecture.md`, `docs/.vitepress/`
+ new workflows (`docs-site.yml`, `renovate.yml`) so the layout
matches what `ls` actually shows.
Section 3 (Initial setup) — new diagram:
* Mermaid `flowchart` of the local-dev topology (host-side dev
servers + Compose containers + viewer profiles + the optional
docs site). Replaces the prose ports-table that was scattered
across §3 and §5 for new contributors.
Section 4 (Daily commands):
* Add `portal-admin` to serve / test / generate examples.
* Correct the single-test-file recipe — Nx's vitest executor
rejects `--testFile`; use positional `path/to/file.spec.ts`
for Vitest projects, `--testPathPattern=…` for Jest.
* New "Documentation site" subsection — `docs:dev` / `docs:build`
/ `docs:preview`, link to ADR-0022.
Section 5 (Observability):
* Mermaid `sequenceDiagram` of how a click becomes a trace
(browser span → traceparent → BFF span → Pino log line with
matching trace_id → OTLP batch → Jaeger). Anchors the
correlation rule that the prose explained but didn't visualise.
Section 6 (Renovate):
* Add "Transitive vulnerabilities — `pnpm.overrides`" subsection.
Documents the pattern from #159 (vite + esbuild via VitePress)
so the next contributor hitting a transitive vuln has the
playbook on hand.
Section 9 (Sections to come):
* Split into "Code shipped — doc to write" and "Not yet". Many
phase-2 items moved out of "to come" since the code has shipped
(auth, sessions, MFA decorator, admin module, audit viewer,
user directory, downstream strategies, OpenAPI tooling,
capabilities endpoint). The roadmap now reflects what's
actually still missing.
Julien Gautier