> ## Documentation Index
> Fetch the complete documentation index at: https://meganharrisonconsulting.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How These Docs Stay Current

> The freshness system — why you can trust what you read here, and how to tell at a glance.

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

<CardGroup cols={1}>
  <Card title="🟢 Generated" icon="robot">
    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).
  </Card>

  <Card title="🟡 Gated" icon="lock">
    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.
  </Card>

  <Card title="⚪ Authored" icon="pen">
    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.
  </Card>
</CardGroup>

## How to read a page

Every page's frontmatter declares its tier and provenance:

```yaml theme={null}
---
title: "Commitments"
owner: "jane@alleatogroup.com"
freshness: "authored"      # generated | gated | authored
last_verified: "2026-06-22"
---
```

* **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.

| Content             | Canonical source                                  | How it reaches this site                                             |
| ------------------- | ------------------------------------------------- | -------------------------------------------------------------------- |
| 🟢 Reference        | The codebase                                      | Generated into `reference/*` by a script + gate                      |
| 🟡 Architecture     | This site                                         | Authored here; a gate forces updates when tied code changes          |
| ⚪ Product / guides  | This site                                         | Authored here, with owner + review cadence                           |
| Operations/runbooks | This site plus `docs/ops/**` evidence             | Current guidance here; detailed task evidence stays in `docs/ops/**` |
| Working notes       | App repo `docs/**` outside `docs/alleato-os-docs` | Reference only unless linked from this site                          |

<Note>
  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.
</Note>

## 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.