README.md

Documentation

Docs are split by the question they answer:

Directory	Question	Contents
adr/	Why did we choose this?	Architecture Decision Records — semantically immutable once accepted; link-only maintenance follows ADR-0033
design/	How does it fit together?	Living documents describing the current architecture
specs/	What exactly is the contract?	Precise, testable interface definitions
plans/	When/in what order do we build?	Roadmaps and phase plans; updated as work lands

Index

Decisions (ADRs)

• 0001 — Record architecture decisions
• 0002 — Agent-portable instruction surface
• 0003 — Record image provenance in /usr/share/frostyard
• 0004 — Product-namespaced filesystem paths, split by lifetime tier
• 0005 — Transport discrimination by marker file and /run update-state contract
• 0006 — OS artifact versions are 14-digit UTC timestamps
• 0007 — The Frostyard sysext filename pattern and derived versions
• 0008 — Sysext distribution layout and update contract (index truncation resolved by 0032)
• 0009 — repository.frostyard.org is the single artifact origin
• 0010 — Publish packages through the shared repogen action
• 0011 — Distro packages are named frostyard-<tool>
• 0012 — svu-derived versions, make bump, and the rolling dev prerelease
• 0013 — Component releases trigger image rebuilds via repository_dispatch (superseded by 0056)
• 0014 — One GPG repository key, baked into images
• 0015 — os-release is the image identity surface
• 0016 — Reverse-DNS org.frostyard.* identifiers
• 0017 — io.snosi.* OCI capability labels and the mechanics QA tier
• 0018 — Org-wide agent instruction and knowledge surfaces
• 0019 — Repository governance as machine-readable policy with risk tiers
• 0020 — Trust boundaries for AI automation in CI
• 0021 — SHA-pinned actions and least-privilege CI workflows
• 0022 — make ci is the canonical gate; TestI* is reserved
• 0023 — External downloads are version-pinned and checksum-verified
• 0024 — Rename the AI-facing docs directory from yeti/ to cairn/ (superseded by 0025)
• 0025 — One docs/ tree per repository, in core's four-category shape
• 0026 — Distribute core agent skills to repos via sync PRs from core
• 0027 — Retire fisherman; firn is the frostyard bootc installer
• 0028 — Retire snosi-install; firn is the frostyard A/B installer
• 0029 — ACMM conformance via canonical aliases
• 0030 — Shipped systemd units never use RequiredBy= enablement
• 0031 — Retire Dakota's secure bootc installer; firn owns the path
• 0032 — Treat incremental sysext indexes as exhaustive
• 0033 — Permit link-only maintenance in immutable ADRs
• 0034 — Cancel stale rolling dev releases
• 0035 — Author organization authority as strict JSON
• 0036 — Publish versioned verification profiles
• 0037 — Publish executable organization goals
• 0038 — make ci stays canonical; the TestI/Integration name filter is chairlift-only
• 0039 — Widen maintenance_programs within repository schema v1
• 0040 — Publish the repository settings contract
• 0041 — Retire copilot-review-apply where Snowcat gates review
• 0042 — Adopt a merge queue on the default branch
• 0043 — Pin repository tools in mise and name the verify gate
• 0044 — Expose the make gate triad in every repository
• 0045 — Guard Actions-secret expiry with a committed record
• 0046 — Rename the cayo server image to floe
• 0047 — Retire NBC on a proportional four-user fast path
• 0048 — Publish Debian packages to explicit codenames (superseded by 0055)
• 0049 — Retire omarchy-apps without breaking Snosi
• 0050 — Replace the NBC/native-A/B retention date with a completion condition
• 0051 — ADRs state facts only, not the process that produced them
• 0052 — Remove NBC/native-A/B artifact retention gates
• 0053 — Name the svu config file .svu.yml
• 0054 — Remove four-known-users gates from suite migration (superseded by 0055)
• 0055 — Publish Debian packages through the apt-publisher single writer
• 0056 — The APT publisher triggers image rebuilds after packages are live

Design

• Quality loop
• Shared skills
• Skills sync operations
• Organization authority
• Stable repository drift alarm
• Debian publication

Specs

• PR review rubric
• PR acceptance metric
• Organization repository enrollment
• Organization verification profiles
• Organization goals
• Stable repository drift alarm

Plans

• Org docs-shape and skills rollout
• Organization portfolio stewardship
• Firn skills sync onboarding
• Dev release concurrency rollout
• Organization authority rollout
• Debian suite migration fast path (superseded by Plan 0009)
• Support suites in Repogen (superseded by Plan 0009)
• Post-NBC bootc-only transition (Snosi/Firn)
• Debian publication through apt-publisher

Conventions

• New docs start from their category's TEMPLATE.md (in each directory).
• New decision → new ADR with the next number; if it reverses an old one, mark the old one Superseded by NNNN rather than editing it.
• Link-only repairs to Accepted or Superseded ADRs follow ADR-0033; semantic changes always require a new ADR.
• Design docs are updated in place to always reflect reality.
• Specs change only alongside the code that implements them.
• Cross-links between categories are mandatory in both directions — see the documentation rules in AGENTS.md (CLAUDE.md/GEMINI.md are symlinks to it, ADR-0002).
• Adding a doc means adding it to the index above.
• Conformance alias symlinks (docs/quality.md, docs/metrics.md, docs/review-rubric.md — ADR-0029) are not docs and are not indexed — edit their canonical targets.