Skip to main content
Docs rot because nobody can tell which pages are current. This site fixes that by giving every page a freshness tier in its frontmatter, and by tying the trustworthy tiers to automation instead of good intentions.

​
The three tiers

🟢 Generated

Produced from the codebase by a script — never hand-edited. A pre-commit/CI gate regenerates it when the code changes, so it cannot drift. This is the most trustworthy tier. Everything under Reference is generated (routes, API endpoints, AI tools, database tables, design-system components).

🟡 Gated

Authored prose, but tied to a specific code path. If that code changes, a pre-commit gate blocks the commit until the doc is updated in the same change (the same mechanism that keeps the RAG architecture docs honest). Most of How It’s Built is gated.

⚪ Authored

Concepts, guides, and decisions a human owns. These can drift, so each carries an owner and a last_verified date, and shows a warning banner once it’s past its review window. Most of Product is authored.

​
How to read a page

Every page’s frontmatter declares its tier and provenance:
  • Generated → trust it; if it looks wrong, the code changed and the page will catch up on the next regen.
  • Gated → trust it; it was verified against the code at the last commit that touched that area.
  • Authored → trust it up to last_verified; treat as stale past the review window.

​
Where the source of truth lives

This site is the current product and engineering documentation source of truth. It is mounted in the app repo at docs/alleato-os-docs, which points to the frontend docs app at /Users/meganharrison/Documents/github/alleato-os/apps/docs. The larger app repo docs/** tree is a working evidence/control-plane area. It contains PRPs, handoffs, reports, plans, archives, generated inventories, and task ledgers. Those files can be valuable evidence, but they are not current product documentation unless this site links to them.
The generated Reference pages are wired to the same machinery that keeps docs/architecture/PROJECT-MAP.md and TABLE-LIST.md fresh in the repo. If a Reference page is ever stale, that’s a broken gate — report it, don’t hand-edit it.

​
Deprecated paths

Do not treat these as live docs-site paths:
  • docs/index/
  • docs/pages-directory.md
  • docs/infographic.png
  • docs/infographic2.png
  • generated screenshot/evidence folders under frontend/tests/**
The repo-control guard fails if these deleted roots reappear.