Skip to main content

Origo Documentation System

Purpose​

  • This page defines the structure, ownership, writing rules, navigation model, and build contract for the Origo documentation system.
  • It is the operating manual for the documentation migration and the review standard for later docs changes.

Required reading​

  • README.md
  • docs/README.md
  • docs/Developer/README.md
  • AGENTS.md
  • contracts/governance/documentation-contract.json

Canonical source model​

  • README.md is the product home page and first-success entry point.
  • docs/README.md is the canonical public docs hub.
  • /docs is the canonical source for public product docs.
  • /docs/Developer is the canonical source for contributor and maintainer docs.
  • Package README.md files under Origo modules are orientation surfaces only.
  • Governance authority remains in AGENTS.md and contracts/governance/*.json.
  • Historical slice records under spec/slices/ are archival and provenance-oriented, not the primary product learning path.

Information architecture​

  • Overview
  • Guides
  • Reference
  • Developer
  • Packages

Section responsibilities​

  • Overview explains what Origo is, what it is not, system boundaries, and the end-to-end data lifecycle.
  • Guides teach real Origo workflows from start to finish.
  • Reference documents stable user-visible and operator-visible interfaces and semantics.
  • Developer documents contribution, maintenance, release, proof, and documentation process.
  • Packages orients readers inside code ownership boundaries and routes them back to canonical docs.

Origo narrative spine​

  1. Origo acquires source-native financial data from exchanges, ETF issuers, Bitcoin nodes, and FRED.
  2. Origo preserves immutable canonical truth with provenance, schema discipline, and replayability.
  3. Origo projects canonical truth into native and aligned serving surfaces.
  4. Origo serves only contract-valid and, where relevant, terminally proved history.
  5. Origo exposes observability, proof, and blocker surfaces so operators can see what is true, what is available, and what is blocked.
  6. Origo supports deterministic replay, backfill, rebuild, and recovery workflows.
  7. Governance defines authority boundaries, but governance prose must not replace machine governance authority.

Writing rules​

  • Start with what the thing is and why a reader would use it.
  • Prefer current behavior over historical narrative.
  • Prefer real runnable flows and real artefacts over invented examples.
  • Keep governance references honest: explain them, but do not duplicate them into competing prose authority.
  • Use one primary page type per page.
  • End pages with explicit next steps when useful.

Page types​

Home page​

  • Required blocks:
    • what Origo is
    • what Origo is not
    • capability summary
    • first successful workflow
    • routes into the docs system

Docs hub​

  • Required blocks:
    • system overview
    • reading order by audience
    • architecture map
    • routes into overview, guides, reference, developer docs, and packages

Guide​

  • Required blocks:
    • what this guide covers
    • prerequisites
    • current scope
    • at least one concrete example
    • expected outputs or artefacts
    • next steps

Reference​

  • Required blocks:
    • short intro and scope
    • conventions or naming rules
    • structured entry documentation
    • output behavior where relevant
    • caveats and failure behavior where relevant

Developer page​

  • Required blocks:
    • page purpose
    • required reading or prerequisites
    • process or checklist
    • failure cases or review notes
    • linked related maintenance pages

Package README​

  • Required blocks:
    • what the package owns
    • what it does not own
    • key entry points
    • major dependencies or adjacent modules
    • link to canonical public docs
  • The home page and docs hub must both route readers by task.
  • Guides must link forward into the reference layer.
  • Reference pages must link to the next page a reader should open, not just dump related filenames.
  • Package READMEs must point outward to canonical docs rather than trying to explain the whole system locally.
  • Historical slice records may support provenance, but they must not carry primary learning flow.

Site build contract​

  • The docs site lives in docs-site/ inside this repository.
  • The first implementation uses Docusaurus.
  • The site must support local development and static build.
  • Base URL must be environment-driven.
  • Search must work across the docs corpus.
  • Broken internal links must fail the build.
  • The navigation shell must reflect the five-section architecture.

Review checklist​

  1. Confirm the target page type.
  2. Confirm the page’s place in the Origo narrative spine.
  3. Confirm whether the page is canonical or secondary.
  4. Confirm the page routes to the next useful document.
  5. Confirm no governance prose is replacing machine authority.
  6. Confirm examples are real and current.
  7. Confirm package READMEs link outward.

Failure cases​

  • Public docs that route readers into spec/slices/* as the normal learning path fail this contract.
  • Developer docs that mirror governance contracts as competing prose authority fail this contract.
  • Reference pages without examples, failure behavior, or scope boundaries fail this contract.
  • Package READMEs that lack links back to canonical docs fail this contract.
  • Docs-site changes without broken-link enforcement fail this contract.
  • docs/Developer/README.md
  • docs/Developer/Contributing.md
  • docs/Developer/Tests-And-Gates.md
  • docs/Developer/Proof-And-Evidence-Workflow.md