UpsQuad Engineering Docs

Welcome to UpsQuad's internal engineering documentation. This site is the human-readable view of the canonical markdown that lives in upsquad-core/docs/.

Single source of truth

This site is a rebuilt view — it is regenerated from the markdown in git on every push to main. It is never an editable store. If a doc is wrong, fix the markdown file in git (use the "Edit this page" link), open a PR, and both this site and the agent-facing RAG index refresh from the merged source. This preserves UpsQuad's "source control is the audit trail" tenet.

What lives here

Section	What it holds
ADRs	Architecture Decision Records — the why behind technical choices
HLDs	High-Level Designs — system/feature shape before implementation
LLDs	Low-Level Designs — implementation-level specs per wave/item
Runbooks	Operational procedures (worktrees, CI cleanup, migrations, cutovers)
Retrospectives	Post-incident / post-wave learnings
Security	Incident-response plan, security.txt
QA	QA reports per wave
ICS	Isolated Compute Sandbox quickstart
Product reference	PRD markdown files. NOTE: the authoritative PRD registry is the set of GitHub issues + docs/PRD_REGISTRY.md; these markdown copies are reference only.

What is NOT here

• PRDs-as-issues — product requirements tracked as GitHub issues are not migrated into this site. The PRD registry and issues stay authoritative. (Founder decision: file-docs only.)
• An editing surface — you do not write docs in this site. You write markdown in the repo.

The two views over one source

            repo markdown  (SINGLE SOURCE — stays in git: docs/**)
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
   Docusaurus          Context Engine RAG
   (this site —        (agent view — fast-follow,
    the human view)     dogfoods UpsQuad's own retrieval)

The agent-facing RAG index (pillar 2) is a fast-follow: it ingests the same docs/** markdown into UpsQuad's own Context Engine and exposes retrieval to agents over MCP. It depends on the Context Engine IngestDocument enabler.

Conventions

• ADRs are numbered (ADR-NNNN-slug.md) and immutable once accepted — supersede with a new ADR rather than editing history.
• Runbooks are living operational docs; keep them current.
• Editing: every page has an "Edit this page" link that points at the canonical markdown in upsquad-core/docs/.