Doc grouping and updates

Author: Cyber-preacher

README.md

@@ -42,12 +42,13 @@ If only `yarn dev` runs, `/api/*` is not available and auth/gating/read pages wi
 ### Backend docs
 
 - Start here: `docs/README.md`
-- Module map (paper → docs → code): `docs/vortex-simulation-modules.md`
-- API contract: `docs/vortex-simulation-api-contract.md`
-- Proposal wizard architecture: `docs/vortex-simulation-proposal-wizard-architecture.md`
-- Local dev: `docs/vortex-simulation-local-dev.md`
-- Scope and rules: `docs/vortex-simulation-scope-v1.md`, `docs/vortex-simulation-state-machines.md`
-- Vortex 1.0 reference (working copy): `docs/vortex-1.0-paper.md`
+- Docs are grouped in: `docs/simulation/`, `docs/ops/`, `docs/paper/`
+- Module map (paper → docs → code): `docs/simulation/vortex-simulation-modules.md`
+- API contract: `docs/simulation/vortex-simulation-api-contract.md`
+- Proposal wizard architecture: `docs/simulation/vortex-simulation-proposal-wizard-architecture.md`
+- Local dev: `docs/simulation/vortex-simulation-local-dev.md`
+- Scope and rules: `docs/simulation/vortex-simulation-scope-v1.md`, `docs/simulation/vortex-simulation-state-machines.md`
+- Vortex 1.0 reference (working copy): `docs/paper/vortex-1.0-paper.md`
 
 ## Scripts
 
@@ -86,4 +87,4 @@ If only `yarn dev` runs, `/api/*` is not available and auth/gating/read pages wi
 
 - `dist/` is generated build output.
 - Keep glossary entries in sync between `src/data/vortexopedia.ts` and `prolog/vortexopedia.pl` if you edit definitions.
-- DB-backed dev requires `DATABASE_URL` + `yarn db:migrate && yarn db:seed` (see `docs/vortex-simulation-local-dev.md`).
+- DB-backed dev requires `DATABASE_URL` + `yarn db:migrate && yarn db:seed` (see `docs/simulation/vortex-simulation-local-dev.md`).

docs/README.md

@@ -2,6 +2,12 @@
 
 This folder documents the **Vortex simulation backend** that powers the UI in this repo.
 
+Docs are grouped by intent:
+
+- `docs/simulation/` — core simulation specs, architecture, and implementation plan
+- `docs/ops/` — operational runbook for the backend
+- `docs/paper/` — working reference copy of the Vortex 1.0 paper
+
 ## Overview
 
 This repo ships two pieces together:
@@ -20,7 +26,7 @@ The simulation is **not** an on-chain implementation. Humanode mainnet is used o
 
 The UI reads from `/api/*`. The contract is kept stable so the backend can evolve without forcing UI churn:
 
-- Contract source of truth: `docs/vortex-simulation-api-contract.md`
+- Contract source of truth: `docs/simulation/vortex-simulation-api-contract.md`
 - TS DTO types used by the UI: `src/types/api.ts`
 
 In v1, reads are backed by a transitional `read_models` table (and optional overlays from normalized tables), so pages can render without requiring the full normalized domain schema on day one.
@@ -67,20 +73,20 @@ Goal: keep a tight, professional set of docs that answers:
 
 ## Reading order
 
-1. `docs/vortex-simulation-scope-v1.md` — v1 scope, explicit non-goals, and what “done” means
-2. `docs/vortex-simulation-modules.md` — module map (paper → docs → code)
-3. `docs/vortex-simulation-processes.md` — domain processes to model (product-level)
-4. `docs/vortex-simulation-proposal-wizard-architecture.md` — proposal wizard template architecture (project vs system flows)
-5. `docs/vortex-simulation-state-machines.md` — formal state machines, invariants, and derived metrics
-6. `docs/vortex-simulation-tech-architecture.md` — technical architecture (runtime + DB + API shape)
-7. `docs/vortex-simulation-data-model.md` — DB tables and how reads/writes/events map to them
-8. `docs/vortex-simulation-api-contract.md` — frozen DTO contracts consumed by the UI
-9. `docs/vortex-simulation-local-dev.md` — local dev commands and env vars
-10. `docs/vortex-simulation-ops-runbook.md` — admin endpoints, safety controls, and operational workflows
-11. `docs/vortex-simulation-implementation-plan.md` — phased plan + current status
-12. `docs/vortex-simulation-v1-constants.md` — v1 constants shared by code and tests
-13. `docs/vortex-1.0-paper.md` — working, adapted reference copy of the Vortex 1.0 paper (used for audits)
-14. `docs/vortex-simulation-paper-alignment.md` — paper vs simulation audit notes (what matches, what’s deferred)
+1. `docs/simulation/vortex-simulation-scope-v1.md` — v1 scope, explicit non-goals, and what “done” means
+2. `docs/simulation/vortex-simulation-modules.md` — module map (paper → docs → code)
+3. `docs/simulation/vortex-simulation-processes.md` — domain processes to model (product-level)
+4. `docs/simulation/vortex-simulation-proposal-wizard-architecture.md` — proposal wizard template architecture (project vs system flows)
+5. `docs/simulation/vortex-simulation-state-machines.md` — formal state machines, invariants, and derived metrics
+6. `docs/simulation/vortex-simulation-tech-architecture.md` — technical architecture (runtime + DB + API shape)
+7. `docs/simulation/vortex-simulation-data-model.md` — DB tables and how reads/writes/events map to them
+8. `docs/simulation/vortex-simulation-api-contract.md` — frozen DTO contracts consumed by the UI
+9. `docs/simulation/vortex-simulation-local-dev.md` — local dev commands and env vars
+10. `docs/ops/vortex-simulation-ops-runbook.md` — admin endpoints, safety controls, and operational workflows
+11. `docs/simulation/vortex-simulation-implementation-plan.md` — phased plan + current status
+12. `docs/simulation/vortex-simulation-v1-constants.md` — v1 constants shared by code and tests
+13. `docs/paper/vortex-1.0-paper.md` — working, adapted reference copy of the Vortex 1.0 paper (used for audits)
+14. `docs/simulation/vortex-simulation-paper-alignment.md` — paper vs simulation audit notes (what matches, what’s deferred)
 
 ## Doc conventions
 
@@ -92,10 +98,10 @@ Goal: keep a tight, professional set of docs that answers:
 
 ### Truth hierarchy
 
-- **API truth:** `docs/vortex-simulation-api-contract.md` + `src/types/api.ts`
-- **Scope truth:** `docs/vortex-simulation-scope-v1.md`
-- **Behavior truth:** `docs/vortex-simulation-state-machines.md` (rules + invariants)
-- **Operational truth:** `docs/vortex-simulation-ops-runbook.md`
+- **API truth:** `docs/simulation/vortex-simulation-api-contract.md` + `src/types/api.ts`
+- **Scope truth:** `docs/simulation/vortex-simulation-scope-v1.md`
+- **Behavior truth:** `docs/simulation/vortex-simulation-state-machines.md` (rules + invariants)
+- **Operational truth:** `docs/ops/vortex-simulation-ops-runbook.md`
 
 ### Status tags
 

docs/vortex-simulation-ops-runbook.md docs/ops/vortex-simulation-ops-runbook.mddocs/vortex-simulation-ops-runbook.md renamed to docs/ops/vortex-simulation-ops-runbook.md

@@ -7,7 +7,7 @@ This document is the operational reference for running the simulation backend as
 - Production: Cloudflare Pages Functions (`functions/`)
 - Local: Node runner (`yarn dev:api`) with the UI proxy (`yarn dev` / `yarn dev:full`)
 
-Local dev details: `docs/vortex-simulation-local-dev.md`.
+Local dev details: `docs/simulation/vortex-simulation-local-dev.md`.
 
 ## Admin auth
 
@@ -42,7 +42,7 @@ Write commands run through `POST /api/command`. The system supports four layers
 - `GET /api/admin/users/:address`
 - `GET /api/admin/audit`
 
-Details of request/response DTOs: `docs/vortex-simulation-api-contract.md`.
+Details of request/response DTOs: `docs/simulation/vortex-simulation-api-contract.md`.
 
 ## Incident playbooks
 

docs/vortex-1.0-paper.md docs/paper/vortex-1.0-paper.mddocs/vortex-1.0-paper.md renamed to docs/paper/vortex-1.0-paper.md

@@ -167,7 +167,7 @@ Notes:
 - `templateId` is optional; if omitted the backend infers `"system"` when `metaGovernance` is present, otherwise `"project"`.
 - The backend now validates drafts using a template-aware discriminant (project vs system) so system proposals can omit project-only fields; missing fields are normalized to defaults for storage.
 - Planned (v2+): drafts will continue to evolve into a template-driven discriminated union (project vs system-change flows), with full backend/schema separation. The target architecture and rollout phases are documented in:
-  - `docs/vortex-simulation-proposal-wizard-architecture.md`
+  - `docs/simulation/vortex-simulation-proposal-wizard-architecture.md`
 
 type ProposalDraftSaveCommand = {
   type: "proposal.draft.save";

docs/vortex-simulation-api-contract.md …lation/vortex-simulation-api-contract.mddocs/vortex-simulation-api-contract.md renamed to docs/simulation/vortex-simulation-api-contract.md docs/vortex-simulation-api-contract.md renamed to docs/simulation/vortex-simulation-api-contract.md

@@ -16,7 +16,7 @@ The schema is implemented in `db/schema.ts` with migrations under `db/migrations
 
 Purpose:
 
-- Store JSON payloads that directly match the DTOs in `docs/vortex-simulation-api-contract.md`.
+- Store JSON payloads that directly match the DTOs in `docs/simulation/vortex-simulation-api-contract.md`.
 
 Modes:
 
@@ -90,7 +90,7 @@ Planned (v2+):
 
 - The draft `payload` will evolve from a single “project-shaped” object with optional `metaGovernance` into a **discriminated union** aligned with proposal wizard templates (project vs system-change flows).
 - The wizard architecture and phased migration strategy are described in:
-  - `docs/vortex-simulation-proposal-wizard-architecture.md`
+  - `docs/simulation/vortex-simulation-proposal-wizard-architecture.md`
 
 ## Proposals (Phase 14)