Skip to content

Reference

Information-oriented — exact definitions and the source material behind the solutions, consulted rather than read start-to-finish. To do a task see how-to/; for the why, see explanation/.

Canonical reference

Doc Defines
domain-model.md The DocGen vocabulary — organizations, documents, sections, tools, prompts, data needs, gathered / synthesized data. Every other doc cites these terms.
demo-app.md The apps/web demo as-built — architecture, the document page, the seeded solutions.
api-surface.md The stable map of the /v1 authoring/config API areas.
configuration.md Where each configuration area is documented.
tenancy-and-permissions.md Organization scoping, active-org resolution, and permission/auth surfaces.

The /v1 API is the authoritative interface reference: the integrator guide is v1-api.md (base URL, auth, endpoints, progress SSE, error shapes), with the machine-readable contract in openapi-v1.json and the stability policy in versioning.md. The live schema is GET /v1/config-schema; authoring workflows (endpoints, spec shape) are in how-to/authoring-and-config-api.md.

Source documents & inputs

The source material the DocGen solutions were built from — client specs, sample data, and the analysis derived from them. Everything a new reader needs to follow why the Phoenix / JBRK configurations look the way they do. These are inputs, not deliverables; the release + solution docs (linked at the bottom) are the design/implementation record that consumes them.

Provenance. The Phoenix UC2 material originates from the Phoenix UC2 Google Drive folder shared by the client engagement. The reinsurance numbers and EFS narrative are AltaML-authored stand-ins in Matthew Nicolini's style (not his voice), provisional until Matthew's sign-off — see the Disclosures in phoenix-uc2-analysis.md §6. Only 2 of 7 deals are GROUNDED (614563 Sutton/Bamboo, 618702 Heritage Per Risk); the rest are DERIVED / EDGE-CASE. Each deal carries a _numbersOrigin field recording its lineage.

Phoenix (firm-order memo / Odyssey UC2)

File What it is Informs
Phoenix_Firm_Order_Memo_Spec.docx The client spec for the five-paragraph reinsurance firm-order memo (§6 format, §8 approval-extraction rules). The authoritative requirement. solutions/odyssey/*, releases/r3-odyssey-uat/*, mcp_servers/phoenix.py
phoenix-uc2-analysis.md The analysis: memo structure, the formulas, the insufficient-data gating, and the framework gap analysis (GAP-1…4 → R2 features G1–G4). Start here. releases/r2-framework-production-features/r2-tdd.md, the framework-gap epic
phoenix-data/build_deals.py Authoritative generator for the sample deals (layer structure, pricing, cat-modeling, EFS approvals). phoenix-data/deals.json
phoenix-data/build_expected.py Authoritative generator for the gold memos (the assembly + formula source of truth). phoenix-data/expected-memos.json
phoenix-data/deals.json 7 sample deals (mock Phoenix + EFS records). The faked integration input. Vendored copy lives at docgen/src/docgen/mcp_servers/phoenix_deals.json (the local Phoenix MCP server's store). mcp_servers/phoenix.py, the seeded Phoenix template
phoenix-data/expected-memos.json The gold rendered memos — every Phoenix test asserts byte-equality against these. tests/integration/test_phoenix_seeded.py, test_phoenix_engine.py
phoenix-data/phoenix_memo.py A standalone, NON-engine memo generator. Kept as an independent test oracle (cross-checks the engine output), not an example. tests/integration/test_phoenix_memo.py
phoenix-memo-generator.html The original interactive HTML mockup of the memo + gating UI. Visual reference for the intended output + "attention" states. UI/UX of the Phoenix walkthrough

Note: deals.json exists twice on purpose — the docs/reference/ copy is the authoritative gold source (regenerated by build_deals.py); the docgen/src/docgen/fixtures/phoenix_deals.json copy is the shipped sample store the connector reads (kept in sync with the reference copy).

File What it is Informs
JBRK_Legal_OS_Info_Guide.docx The JBRK Legal OS guide — the source for the composition model (atoms/molecules → Text/Snippet, approval-gated Risk Blocks, Section II/III assembly, per-transaction step_num). releases/r2-framework-production-features/r2-tdd.md [T2-composition], solutions/tomorrow-law/*

Framework & mechanism guides (moved)

The mechanism docs that used to live here are now sorted by Diátaxis mode:

Now at Covers
how-to/authoring-and-config-api.md Create / configure / export / update templates & documents over /v1, for humans and agents. Start here to drive DocGen.
how-to/seeding-and-platform-tools.md Seeding + the databases (Postgres docgen / SQLite fallback) + the per-org platform tools.
how-to/mcp-transport-and-library-enforcement.md MCP streamable-http transport, the DealDesk server, MCP_*_URL, the library-enforcement CI.
how-to/mcp-per-user-auth.md Per-user identity forwarding through docgen to MCP source servers.
how-to/observability-and-secrets-setup.md Arize/Phoenix tracing, the config-vs-secret model, wiring a new project.
explanation/rendering-and-prompts.md How a template becomes a document — render modes, batched synthesis, synth_group, voice, citations/verify.

Per-org solution docs. Every org now has a folder under ../solutions/: odyssey and tomorrow-law carry a full PRD + TDD; goa, altaml-dealdesk, and vertical-scope carry a README documenting the use case and pointing to the template spec (the spec JSON remains the source of truth until a full PRD/TDD is written).

Where these are consumed

  • Framework design: ../releases/r2-framework-production-features/r2-tdd.md ([T2-composition], [T2-render], [T2-readiness]).
  • Solution configs (the genericity proof): ../solutions/odyssey/, ../solutions/tomorrow-law/, ../solutions/goa/. See the solutions index.
  • Productionization (real connectors): ../releases/r3-odyssey-uat/ (Odyssey UAT).
  • Implementation in code: docgen/src/docgen/mcp_servers/phoenix.py, docgen/src/docgen/fixtures/phoenix.py, docgen/src/docgen/engine/readiness.py.