synaptiai Documentation Package Contract
Owns the shape of the package: which files exist, what each must contain, and what opens every one of them.
Iron Law
THE PACKAGE SHAPE IS FIXED — 8 directories, 23 files, every run. Content adapts; structure never.
A missing canonical file is indistinguishable from an incomplete run. An irrelevant topic is handled with a justified N/A at section level, never by deleting the file — because "we dropped that file, it did not apply" and "we ran out of time" read identically six months later.
The 23 files
| Path | Audience | Default confidentiality | Contract |
|---|---|---|---|
00-control/documentation-index.md |
All | Internal | package-contract-00-control.md |
00-control/evidence-ledger.md |
Diligence, verification | Internal | package-contract-00-control.md |
00-control/assumptions-questions-and-contradictions.md |
Diligence, owners | Internal | package-contract-00-control.md |
00-control/claim-and-disclosure-register.md |
Disclosure, legal | Restricted | package-contract-00-control.md |
00-control/terminology-and-ownership.md |
All | Internal | package-contract-00-control.md |
01-project/executive-project-brief.md |
Executive, investor | Internal | package-contract-01-project.md |
01-project/product-and-domain.md |
Product, engineering | Internal | package-contract-01-project.md |
02-architecture/system-architecture.md |
Engineering, security | Internal | package-contract-02-architecture.md |
02-architecture/components-and-codebase.md |
Engineering | Internal | package-contract-02-architecture.md |
02-architecture/data-and-ai.md |
Engineering, data, privacy | Internal | package-contract-02-architecture.md |
02-architecture/interfaces-and-integrations.md |
Engineering, partners | Internal | package-contract-02-architecture.md |
02-architecture/infrastructure-and-deployment.md |
Engineering, operations | Internal | package-contract-02-architecture.md |
03-assurance/security-privacy-and-compliance.md |
Security, privacy, legal | Restricted | package-contract-03-assurance.md |
03-assurance/reliability-performance-and-observability.md |
Operations, engineering | Internal | package-contract-03-assurance.md |
03-assurance/testing-quality-and-delivery.md |
Engineering | Internal | package-contract-03-assurance.md |
04-operating/onboarding-and-local-development.md |
New teammates | Internal | package-contract-04-operating.md |
04-operating/operations-and-incident-response.md |
Operations | Internal | package-contract-04-operating.md |
04-operating/decisions-technical-debt-and-risks.md |
Leadership, engineering | Internal | package-contract-04-operating.md |
05-due-diligence/technical-due-diligence-report.md |
Decision maker | Restricted | package-contract-05-due-diligence.md |
05-due-diligence/assets-dependencies-and-licenses.md |
Diligence, legal | Internal | package-contract-05-due-diligence.md |
06-public/technical-partner-guide.md |
Partners | Per disclosure policy | package-contract-06-public.md |
06-public/customer-product-and-trust-guide.md |
Customers | Per disclosure policy | package-contract-06-public.md |
07-verification/documentation-verification-report.md |
All | Internal | package-contract-07-verification.md |
Load only the contract for the document you are drafting. Loading all eight pulls over 500 requirements and hard rules into one context for no benefit.
Headers
Every file opens with YAML frontmatter — internal-v1 for the 21 internal documents, public-v1 for the two under 06-public/. Body line 1 is the H1; body line 2 is the contract pointer comment. This is positional and mechanically checked.
---
dossier-header: internal-v1
title: System Architecture
...
---
# System Architecture
<!-- contract: references/package-contract-02-architecture.md#system-architecture -->
Field rules, the status ladder, and the public header's exclusions: references/document-headers.md.
last-verified is the date the document's claims were checked against evidence — not the date the file was edited. A formatting fix does not advance it. Advancing it without re-checking is the quietest way to make a stale package look current.
What every document must make clear
Independent of its subject, a reader must be able to answer four questions without leaving the page:
- What is true now
- What is planned but not implemented
- What is unknown or unverified
- Which limits and conditions apply
Plus: where the canonical source of truth lives, so the reader knows what to trust when this document goes stale.
Justified N/A
An N/A is a claim — "this is demonstrably irrelevant to this project" — and needs evidence like any other.
| Situation | Correct handling |
|---|---|
| No AI component | Section N/A with the evidence for the absence |
| No persistent data | Not N/A. Explain how state is handled — statelessness is a design fact |
| No external interface | Interface sections N/A; the partner guide explains the supported partnership model |
| Not inspected | Never N/A. This is U with an AQ-#### row |
The last row is the failure mode that matters. N/A and Unknown are opposite claims, and using one for the other is a High finding.
Supplemental documents
Permitted when the project genuinely needs them — a safety case, a per-service deep dive. They must be linked from the documentation index, must explain why they exist, and must not duplicate a canonical source of truth. The canonical 23 stay intact regardless.
One supplement is always written: a README.md signpost at the output root, from templates/package-readme.md. A reader browsing the output root otherwise lands on eight numbered directories with no entry point, and the index cannot route someone who never finds it. The signpost states no fact about the project — no counts, no dates, no verdict — so it cannot go stale and needs no evidence row. Everything that can drift stays in the index, which the signpost links to. Register it in the index's supplemental table like any other.
Diagrams
Use Mermaid where it materially improves understanding of real structure, data flow, trust boundaries, or deployment flow. Every node and edge needs evidence; inferred connections are labelled inferred in internal documents.
Decorative diagrams, generic textbook illustrations, and exhaustive file trees have negative value — they cost review attention and carry no decision.
Output Format
Scaffold via bin/dossier-scaffold.sh --output-root <path>, which never overwrites an existing file. Verify via bin/dossier-package-check.sh.
### Package Structure
| Document | Exists | Header valid | Status | Last verified | Contract pointer resolves |
|---|---|---|---|---|---|
### Structural findings
| Severity | File | Problem | Required correction |
|---|---|---|---|
The documentation index is regenerated from this table, never hand-maintained in parallel — a hand-maintained index drifts from the package it indexes, which is exactly the failure the package exists to prevent elsewhere.
Rationalization Prevention
| Excuse | Response |
|---|---|
"This project has no AI, so data-and-ai.md is noise" |
It is one file with a justified N/A section and a data model that does apply. Deleting it breaks every cross-package diff. |
| "I will merge the two public documents, the audiences overlap" | Partners and customers need different abstraction levels and different disclosure boundaries. Merging optimizes for the writer. |
| "The index is out of date but the documents are fine" | The index is how every reader enters. A wrong index makes correct documents unreachable. |
"I updated the formatting, so I will refresh last-verified" |
That date means claims were re-checked. Advancing it for a formatting fix is a false statement about verification. |
"This section does not apply — N/A" |
Does not apply, or was not inspected? They are opposite claims. Only one of them is N/A. |
| "A diagram here would look good" | Would it change a decision? If not, it costs review attention and adds a drift surface. |
| "Adding a supplemental file is easier than fitting this in" | Then the canonical file is wrong or the content is not needed. Supplements are for genuine extra depth. |
Integration
Loaded by dossier-doc-drafter for every document, by /dossier:init when scaffolding, and by dossier-pass-a-evidence, which rebuilds the file inventory from these contracts rather than from the index — auditing the index against itself would prove nothing.
References: references/document-headers.md, references/package-contract-*.md, references/project-type-adaptation.md.