# Technical Documentation System

> How the real documentation is organized: the TVA phased methodology (0-5), the eight ADRs that actually constrain the design, the anti-capture principle, the eight work-group charters, and the difference between docs/ (published site) and tech-docs/ (source of truth).

- Repository: The-AI-Alliance/tapestry
- GitHub: https://github.com/The-AI-Alliance/tapestry
- Human wiki: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6
- Complete Markdown: https://grok-wiki.com/public/wiki/the-ai-alliance-tapestry-4a40b7cf9eb6/llms-full.txt

## Source Files

- `tech-docs/README.md`
- `tech-docs/architecture/README.md`
- `tech-docs/architecture/0-tva-methodology.md`
- `tech-docs/governance/anti-capture-principle.md`
- `tech-docs/work-groups/README.md`
- `docs/_config.yml`
- `docs/index.markdown`
- `docs/contributing.markdown`

---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [tech-docs/README.md](tech-docs/README.md)
- [tech-docs/architecture/README.md](tech-docs/architecture/README.md)
- [tech-docs/architecture/0-tva-methodology.md](tech-docs/architecture/0-tva-methodology.md)
- [tech-docs/governance/anti-capture-principle.md](tech-docs/governance/anti-capture-principle.md)
- [tech-docs/governance/README.md](tech-docs/governance/README.md)
- [tech-docs/work-groups/README.md](tech-docs/work-groups/README.md)
- [tech-docs/architecture/decisions/README.md](tech-docs/architecture/decisions/README.md)
- [tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md)
- [tech-docs/architecture/decisions/adr-008-data-sovereignty.md](tech-docs/architecture/decisions/adr-008-data-sovereignty.md)
- [docs/_config.yml](docs/_config.yml)
- [docs/index.markdown](docs/index.markdown)
- [docs/contributing.markdown](docs/contributing.markdown)
- [README.md](README.md)
- [AGENTS.md](AGENTS.md)

</details>

# Technical Documentation System

The technical documentation for Project Tapestry lives in two distinct places that serve different audiences and purposes. `tech-docs/` is the source of truth for all architecture, governance, and design decisions. `docs/` contains the sources for the published GitHub Pages website. Understanding this split, the TVA methodology that produced the design, the eight constraining ADRs, the anti-capture principle, and the eight work-group charters is the fastest way to orient yourself before reading code or contributing.

## TVA Methodology

TVA (Tapestry Vision Architecture) is the structured, bidirectional requirements-to-architecture process used to derive Tapestry's design. It exists because the project must simultaneously deliver frontier-class capability and genuine sovereignty for heterogeneous participants; premature architectural commitment is the primary risk.

TVA organizes work into six phases across two movements:

- **Requirements (Phases 1–4)** work top-down from stakeholders to the constraints the architecture must satisfy.
- **Architecture (Phases 5–6)** work bottom-up, letting technical realities revise earlier goals.

The phases are not a waterfall. After an initial forward pass, the process requires iterative consistency checks: Phase 5 decisions must ripple back through Phases 4–1, orphaned items must be resolved, and tensions must be named explicitly as open questions.

```mermaid
graph TD
    subgraph Requirements ["Requirements (top-down)"]
        P1["Phase 1: Stakeholder Mapping"]
        P2["Phase 2: Pain Point Analysis"]
        P3["Phase 3: Value Proposition Mapping"]
        P4["Phase 4: Design Goal Synthesis"]
    end
    subgraph Architecture ["Architecture (bottom-up)"]
        P5["Phase 5: Architectural Option Space"]
        P6["Phase 6: Architecture Decision Records"]
    end
    P1 --> P2 --> P3 --> P4 --> P5 --> P6
    P5 -.->|"revises"| P4
    P4 -.->|"ripples back"| P3
    P3 -.->|"ripples back"| P2
    P2 -.->|"ripples back"| P1
```

**Current status** (as recorded in the methodology document):

| Phase | Status    |
|-------|-----------|
| 0 — TVA Methodology (this document) | Complete |
| 1 — Stakeholder Mapping | Complete |
| 2 — Pain Point Analysis | Complete |
| 3 — Value Proposition Mapping | Complete |
| 4 — Design Goal Synthesis | Complete |
| 5 — Architectural Option Space | Complete |
| 6 — Architecture Decision Records | Next (ADRs exist in proposed state) |

**Sources:** [tech-docs/architecture/0-tva-methodology.md:1-120](tech-docs/architecture/0-tva-methodology.md), [tech-docs/architecture/README.md:1-16](tech-docs/architecture/README.md)

## Architecture Decision Records (ADRs)

All significant architectural and governance commitments are captured as Architecture Decision Records (ADRs) in `tech-docs/architecture/decisions/`. There are currently eight ADRs, numbered TAP-001 through TAP-008. All are in "proposed" status and use a standard metadata table (Status, Confidence, Date, Deciders) followed by Context, Decision, and Rationale sections.

The complete set:

| ADR | Title | Key Commitment |
|-----|-------|----------------|
| TAP-001 | Core-plus-sovereign architecture | Layered model: shared frontier base + participant sovereign layers (initial ~80/20 split, shifting over time) |
| TAP-002 | Consortium training model | Governed, contribution-weighted, anti-capture training loop across sovereign nodes |
| TAP-003 | Cultural alignment as primary differentiator | Sovereign post-training and alignment pipelines are first-class, not afterthoughts |
| TAP-004 | The consortium training loop | Explicit phased loop: shared base improvement + sovereign layer improvement with provenance and credit |
| TAP-005 | Sovereign model pipeline | Participant-owned continued pretraining, alignment, and export paths that preserve control |
| TAP-006 | Phased base model strategy | Start with adopted base, move to consortium-owned bases over time |
| TAP-007 | Training architecture comparison | Documents why core-plus-sovereign was chosen over pure monolithic or fully federated alternatives |
| TAP-008 | Data sovereignty | Data contribution models, residency, provenance, and usage constraints that downstream systems must honor |

The decisions/README.md index currently lists only seven; TAP-008 (Data Sovereignty) was added later and is the most recent.

**Sources:** [tech-docs/architecture/decisions/README.md:45-56](tech-docs/architecture/decisions/README.md), [tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md:1-30](tech-docs/architecture/decisions/adr-001-core-plus-sovereign.md), [tech-docs/architecture/decisions/adr-008-data-sovereignty.md:1-15](tech-docs/architecture/decisions/adr-008-data-sovereignty.md)

## The Anti-Capture Principle

Governance is treated as a load-bearing architectural constraint, not policy added later.

The single foundational statement:

> Tapestry's purpose is sovereign AI for its participants. Its governance must honor that purpose: no participant's sovereignty should be compromised by another's power within the platform, and Tapestry itself must never become the dependency it was built to replace.

This principle directly shapes ADR content, work-group charters (especially Governance & Participation), contribution weighting in the training loop, and the design of decision rights.

**Sources:** [tech-docs/governance/anti-capture-principle.md:1-6](tech-docs/governance/anti-capture-principle.md), [tech-docs/governance/README.md:1-7](tech-docs/governance/README.md), [tech-docs/work-groups/README.md:18](tech-docs/work-groups/README.md)

## Work Group Charters

Eight durable, lifecycle-oriented work groups own requirements discovery, technical exploration, implementation notes, open questions, and delivery artifacts in one place. Each charter explicitly traces its existence to specific TVA phases and ADRs.

The eight groups:

| Work Group | Directory | Owns |
|------------|-----------|------|
| Data Governance | data-governance/ | Sovereign data sourcing, licensing, stewardship, residency, provenance, contribution rights, data-quality criteria |
| Base Model Training | base-model-training/ | Adopted-base strategy, consortium training loop, shared-base continued pretraining, aggregation |
| Sovereign Alignment | sovereign-alignment/ | Participant-owned continued pretraining, post-training alignment, instruction tuning, portability of sovereign layers |
| Evaluation & Certification | evaluation-certification/ | Capability, cultural alignment, safety, benchmark design, certification criteria, audit evidence, release gates |
| Security & Privacy | security-privacy/ | Privacy tiers, secure aggregation, differential privacy, TEEs, threat models, model-update leakage |
| Infrastructure & Operations | infrastructure-operations/ | Heterogeneous compute, orchestration, node operations, observability, fault tolerance, cost/accounting |
| Deployment & Adoption | deployment-adoption/ | Serving, chat/product harnesses, integration patterns, participant rollout, developer experience |
| Governance & Participation | governance-participation/ | Anti-capture mechanics, contribution credit, decision rights, consortium process |

Each charter follows a compact template: Purpose, Why it exists (with links to phases/ADRs), Scope (in/out), Initial questions, Early deliverables, and Interfaces.

**Sources:** [tech-docs/work-groups/README.md:7-58](tech-docs/work-groups/README.md), [tech-docs/work-groups/data-governance/README.md:1-30](tech-docs/work-groups/data-governance/README.md)

## docs/ (Published Site) vs. tech-docs/ (Source of Truth)

| Aspect | docs/ | tech-docs/ |
|--------|-------|------------|
| Purpose | User-facing technical website (GitHub Pages) | Engineering source of truth for design and decisions |
| Technology | Jekyll + Just the Docs theme | Plain Markdown + occasional Mermaid |
| Primary audience | New contributors, partners, external readers | People doing architecture, governance, or implementation work |
| Content style | Orientation, navigation, high-level work-group descriptions | Full TVA phases, all ADRs, detailed charters, open questions, diagrams |
| Build | `make view-local` / GitHub Pages (see GITHUB_PAGES.md) | None — read directly from repo |
| Current linkage | No deep embedding or automatic inclusion of TVA/ADR content | Explicitly referenced from root README and AGENTS.md |

The published site (configured in `docs/_config.yml` with title "Project Tapestry: Technology", baseurl `/tapestry`) is deliberately lightweight. It orients readers and points them at the repo. The actual technical depth — the artifacts that constrain implementation — lives only in `tech-docs/`.

Root README and AGENTS.md are explicit:

- "The technical documentation lives under `tech-docs/`."
- "`docs/` is the GitHub Pages site. It is the user-facing technical website..."
- "`tech-docs/` is the main home for design and technical decision docs."

**Sources:** [README.md:40-65](README.md), [AGENTS.md:1-60](AGENTS.md), [docs/_config.yml:11-26](docs/_config.yml), [docs/contributing.markdown:34-38](docs/contributing.markdown)

## How to Navigate

1. Start with `tech-docs/README.md` and `tech-docs/architecture/README.md`.
2. Read `0-tva-methodology.md` for the process and status.
3. Read the eight ADRs in `architecture/decisions/` (they are the actual constraints).
4. Read the anti-capture principle and the work-group charter that matches your interest.
5. Use the published site (`docs/`) only for orientation or when you want the rendered Jekyll view.

Everything else in the repository — code in `src/`, examples, tests — must eventually be traceable to decisions and charters recorded here.

**Sources:** [tech-docs/README.md:1-37](tech-docs/README.md), [AGENTS.md:25-35](AGENTS.md)

This separation and the artifacts it protects are intentional: the design reasoning that will determine whether Tapestry can actually deliver sovereign frontier AI is too important to be scattered across slides, issues, or chat logs.