Documentation overview

Where everything lives.

Index of every document in this repository. Reorganised 2026-07-27, when the count passed forty and finding anything meant grepping. If you are picking this project up, read this file first and then exactly one other.

Start here, depending on who you are:

You are…	Read
resuming the active acceptance work order	`docs/internal/HANDOFF-NOW.md`, then the newest entry in `PROGRESS.md`
a new agent taking another task	`docs/internal/OPUS-HANDOFF.md`, then `PROGRESS.md`
writing a spec or a design argument	`docs/internal/RETRACTIONS.md` before you write
installing or running the public product	`README.md`, then `https://skilakmesh.com/download`
maintaining install or release automation	`INSTALL.md`, then `RELEASE.md` and `docs/OPERATIONS.md`
evaluating what it does and does not do	`LIMITATIONS.md`

The one rule that keeps this index honest: a document listed as live is one somebody would act on today. When a document stops being that, move it to docs/internal/archive/ and move its row down here in the same commit. An index that quietly accumulates dead entries is worse than no index, because it is believed.

Public — ships in the source-available export

These are on the ALLOW list in scripts/publish-public.sh. Everything not on that list is private by default, which is why the list is an allowlist.

File	What it is
`README.md`	product overview and entry point
`LIMITATIONS.md`	what the product does not do — derived from the internal register
`TERMS.md`, `PRIVACY.md`, `COMMERCIAL-LICENSE.md`, `LICENSE`	legal
`docs/AI-FLOW-COVERAGE.md`	which AI clients are covered, and how
`docs/SETUP-PER-CLIENT.md`	per-client setup
`docs/SMESH-CLI-SPEC.md`	CLI surface

Internal — live (`docs/internal/`)

Never published. Each says “internal” in its own header, and each is on the FORBIDDEN belt-and-braces list.

The private root also contains current maintainer runbooks that are excluded from the lean public allowlist:

File	What it is
`INSTALL.md`	public-native install contract and physical launch acceptance matrix
`RELEASE.md`	sealed-candidate and public tag-promotion runbook
`docs/OPERATIONS.md`	public release-channel operations plus separate self-hosted runtime recovery
`DEPLOY.md`	private self-hosted deployment reference; not part of the native public release
`SECURITY-REVIEW.md`	private security-review record
`CONTRIBUTING.md`, `CLA.md`	private-repository contribution process and agreement
`dashboard/README.md`, `website/README.md`	private component-maintainer notes
`AGENTS.md`, `CLAUDE.md`	private agent operating instructions

The record and the rules

File	What it is	Read it when
`PROGRESS.md`	the append-only execution log. Decisions, measurements, rulings, corrections. Newest last	always, first
`HANDOFF-NOW.md`	current resume note. Verified local gates, matrix result, open Fable rulings	resuming the work order
`ACCEPTANCE-RESULTS.md`	generated — every row’s grade from the last run. Regenerate, never hand-edit	checking where the build stands
`ACCEPTANCE-WORKSHEET.md`	Fable’s 61-row enterprise acceptance sheet — normative; rows the build fails are reported, not adjusted	changing detection or policy
`OPUS-HANDOFF.md`	how to execute: read order, sub-batch discipline, conduct rules, anti-scope	you are starting work
`RETRACTIONS.md`	arguments this project has used and withdrawn, with why each failed	before writing any design argument
`REVISION-PLAN.md`	the v2 architecture and its phases P1–P5	you need the shape of the whole thing
`PRODUCT-BRIEF.md`	what exists and what is a stub — accurate but dated 2026-07-26	background only; verify against the tree
`LIMITATIONS-REGISTER.md`	every known limitation, its mitigation, and its revisit triggers. Public `LIMITATIONS.md` is derived from it	you are narrowing or widening a limitation
`REVIEW-BACKLOG.md`	open review findings	picking up loose ends

Contracts under construction

File	State
`FORWARDING-SPEC.md`	live — the v2 request-forwarding contract. Revised through several review rounds
`AUDIT-SCHEMA-V2.md`	live — the v2 audit record contract

Briefs and gates for work in flight

File	State
`REWRITE-BRIEF-1fc.md`	live — brief for the 1fc spec author (provenance-grouped scanning)
`SOL-BRIEF-P1-1b.md`	reference — the 1b implementation brief; §3’s list of live controls is still the useful part
`SMOKE-1B.md`	live — rationale for the manual gate. The runnable version is `scripts/smoke-1b.sh`
`LAWYER-REVIEW-PACKET.md`	live — counsel questions, awaiting answers
`IP-COMPETITOR-MATRIX.md`	live — internal competitor snapshot and counsel-ready candidate mechanism matrix

Internal — archive (`docs/internal/archive/`)

Superseded or historical. Do not act on these. Kept because the record is append-only and because knowing what was tried is worth the disk.

File	Why it is here
`PROVENANCE-GROUPING-SPEC.md`	cancelled 2026-07-27, not superseded by a successor — the defect it addressed was fixed by a smaller change (excluding the entropy fallback from the joined pass), and shipping this design would have removed a detection that works. Cancelled on measurement before any of it was written. Its §3.4 (claims and not-claims stated separately) is now a required section of every spec
`REVIEW-1fc-draft-coordinator.md`	first review seat on the above; its blocking finding was itself superseded when both constructions proved not to fix the defect
`FIRST-CONTACT-SPEC.md`	superseded and wrong in its central claim — it targeted the wrong scanning channel. Replaced by the work in `REWRITE-BRIEF-1fc.md`. Kept as the worked example of a spec that overstated itself
`AGENT-HANDOFF.md`, `HANDOFF.md`	pre-v2 handoffs, superseded by `OPUS-HANDOFF.md`
`PRODUCTION-PLAN.md`, `PRODUCTION-READINESS.md`	pre-pivot launch planning, superseded by `REVISION-PLAN.md`
`STAGE3-BRIEF.md`, `skilak-mesh_PLAN.md`	early staging plans
`FEEDBACK-FOR-SOL.md`	round-2 review findings, all remediated. ~2000 lines of reproduction detail — the most sensitive file here; it is why the publish allowlist exists
`DR-DRILL-2026-07-24.md`	a dated drill record
`INDIVIDUAL-BETA.md`	unshipped product plans; revisit if the beta returns

Conventions worth knowing before you add a document

Internal by default. A new document is private unless somebody consciously adds it to ALLOW in scripts/publish-public.sh. Put internal work in docs/internal/, and add it to FORBIDDEN as well — the belt-and-braces half.
src/ ships publicly; tests/ do not. Do not name an internal document in public source or public build tooling. The publish gate checks for both full paths and bare document names, and it has caught its own author more than once.
PROGRESS.md is append-only. Never rewrite an entry. Correct it with a later, dated one — including corrections to your own entries from an hour earlier. That habit is the only reason the record is worth reading.
Do not add a fifth handoff document. The archive contains four. If you are tempted to write a new plan-of-record, the answer is almost always an entry in PROGRESS.md or a row in LIMITATIONS-REGISTER.md.

Source file: DOCS.md in SkilakLabs/mesh.