AaaS — Oversight & Context

§1 · The status banner at the top of this page

Every page now advertises its own state.

That colored bar you see at the very top of this page is the same bar on every page under aaas-design.web.app. It reads from registry.json and tells you whether the content you're reading is current, stale, deprecated, archived, or broken — without anyone having to remember to update a banner by hand.

🟢 Live

Current and accurate. Trust it, cite it.

🟡 Stale

Not re-verified in the last 30 days. Re-read the actual file before trusting.

🟠 Deprecated

Superseded by a replacement. Kept for reference — don't use for new work.

🔴 Archived

Legacy decision. Never deleted; listed under /archive.

⚫ Broken

Known broken, pending fix. See the linked issue before acting.

§2 · The context vault

Six short files AI loads before changing anything.

Previously an AI touching the repo had to derive context from 15 000+ lines of code. Now it reads AGENTS.md at the repo root, picks the matching vault file below, runs its pre-flight checklist, and respects the what must NOT break list at the bottom. Each file is < 300 lines and describes the system as it is today — no aspirational framing.

Universal

before-any-change.md

Non-negotiable rules, engineering laws, status vocabulary, decision tree. Read every time.

Scoped

auth-changes.md

Firebase Auth reality, UserAccount shape, firestore.rules for users/{uid}, session cookies, gotchas.

Scoped

design-changes.md

Design tokens, typography classes, theme system, @aaas/ui exports, no-shared-navbar fact.

Scoped

data-model-changes.md

Firestore collections, write patterns, serverTimestamp() rule, CF triggers, index patterns.

Scoped

new-surface.md

The 8 manual mechanical steps to add a new subdomain today. No scaffolding CLI exists yet.

Scoped

foundry-agent-changes.md

Foundry module inventory, MicroAgentStatus union, single-write champion promotion (no staging gate yet).

§3 · The machine-readable registry

One JSON, 113 entries, both humans and AI consume it.

registry.json indexes every surface under design/ with status, lastVerified, owner, the markdown source that generated it, sha256 checksum, and tags. It's regenerated deterministically by scripts/build-design-registry.ts and validated against registry.schema.json.

{
  "id": "strategy/verticalisation",
  "url": "https://aaas-design.web.app/strategy/verticalisation",
  "title": "Extend AaaS Infinitely — Strategy For Tobias Review",
  "status": "live",
  "statusReason": "Pending Tobias review (6 decision asks — see issue 340)",
  "lastVerified": null,
  "lastModified": "2026-04-19T13:15:47+00:00",
  "owner": "jorian@intrinsic.com.de",
  "markdownSource": "docs/strategy/verticalisation-strategy-for-review.md",
  "tags": ["strategy", "review-pending"]
}

Open registry.json → Schema

§4 · The workflow

What the rules look like in practice.

For humans

Navigate. Click any page under aaas-design.web.app. The status bar at the top tells you whether to trust what you're reading.

Find source. The banner links to the markdown source (on GitHub) and the tracking issue if there is one.

Audit freshness. When a page is 🟡 Stale, re-verify and update lastVerified via design/registry.overrides.yaml.

For AI agents

Load AGENTS.md. The entry point at the repo root. It points to the vault and the registries.

Pick vault file. Match your task type using the decision tree in §3 of AGENTS.md. Read before-any-change.md first, then the scoped file.

Run pre-flight. Each vault file ends with a short checklist (emulator run, design-audit, grep for anti-patterns).

Respect constraints. Each vault file ends with a what must NOT break list. Treat as hard constraints.

Verify freshness. If the vault file says status: stale, re-read the actual code — don't trust the summary.

§5 · Never delete — always mark

Legacy keeps its URL.

When something becomes outdated, the answer is never to remove it. We flip its status to deprecated or archived, add a replacedBy pointer, and let the banner + /archive index-of-archived-things surface it. This lets us track every legacy decision we've made without ever 404-ing a historical link.

§6 · Enforcement

What keeps this system honest over time.

Auto-freshness. Pages whose lastVerified ages past 30 days auto-flip 🟢 → 🟡. AI agents re-verify before trusting.

Auto-deploy. .github/workflows/deploy-design.yml redeploys design/ from main on every push that touches it. No more silent races between sessions.

Lint gate. scripts/lint-status-banner.ts fails CI if any new HTML page in design/ is missing the banner markers.

Registry drift. scripts/build-design-registry.ts --check fails CI if the committed registry.json drifts from what the generator would produce.

§7 · Where to go next

Three doors.

Open AGENTS.md → All deliveries Ecosystem context

AGENTS.md is the machine-readable companion to this page — AI agents load it first; the content you're reading here is the same information rendered for humans. If you see drift between the two, the markdown source is authoritative and this page should be regenerated.