Design library
This folder is the documentation site. The guides, screens and operations pages are for the person running NoticeOS; the numbered docs below are the design library: why the product works the way it does. Build the site with pnpm --filter @noticeos/docs dev. Start with 00 (what the product is for) and 01 (how it is built). scripts/docs-index.test.mjs fails when a numbered doc is missing here.
| Doc | What it covers |
|---|---|
| 00 — Objective & the ROI ledger | What "better" means: ROI, the ledger, the booking rules, unit economics |
| 01 — Architecture | The closed loop around the ledger, access and security, what passing CI does not show |
| 02 — Signal contract | Reports, central signals, revenue and cost collection, volume-aware alerts, annotations |
| 03 — Attribution & evaluation | Measurability tiers, cohort tests, holdouts, winner's-curse discipline |
| 04 — Decision policy & context | The scoring function, allocation, Goodhart guards, context packs |
| 05 — Execution, autonomy & accountability | Evidence-based completion, the autonomy ladder, canary and revert, incidents |
| 06 — Operations & self-observability | How NoticeOS monitors itself, budget caps, the kill switch, secrets, vendor failure |
| 07 — Roadmap | Phases with numeric exit criteria and standing kill criteria |
| 08 — SEO/GEO signal reference | The search-signal families under the contract |
| 09 — Onboarding a site | What a new site's report counts, what its signal panel tracks, what a deploy could break |
| 10 — Control Tower UX | The Wall, the review queue, undo, phone mode |
| 11 — Integrations & economics | Every data source: what it costs, its quotas, how it fails |
| 13 — Opportunity scouting | Finding new opportunities: scheduled scouting sweeps, news and trend intake, the playbook |
| 14 — Design | The Tower's stack, tokens, principles, surfaces, the Wall, operator flows, lexicon and components |
| 16 — Replacing the chat workflow | Which parts of an operator's weekly work the Tower covers (File task, New task, the palette) and which are not built |
| 20 — Signal panels | The read contract a site's own repository uses |
| 22 — Workflows | Workflow operations, execution visibility, later LLM steps |
| 23 — Configuration ownership | Where each setting lives, and what accounts would need |
| 24 — Integration monitoring | How each data source's health is observed |
| 26 — Storage capacity | How big the store is, how fast it grows, and how that sizes the move to Postgres |
| 27 — Codebase health | What the codebase report measures and why, the unmeasured rule, the alert rules, and how a report reaches the store |
Doc numbers never change: a retired doc's number stays unused and the other docs keep theirs. Git history contains the retired docs.
The Notice identity (logo, palette, type) is in brand.
The design, in eight principles
- Measure success as ROI. Optimize a signal (traffic, positions, engagement) only through a written causal path to a ledger family. Activity metrics, such as the number of changes shipped, never count as success.
- Improvement comes from calibration and scouting. Calibration compares each change's predicted value with its realized value and adjusts the next estimates; opportunity scouting finds new opportunities and methods (13).
- Grant autonomy per change class on evidence; revoke it automatically. A change class is promoted when its numbers meet the criteria, and demoted after a single sev-1 incident or a single falsified claim.
- Verify every completion claim independently. A task is complete only when re-executed checks pass and each claim points to an artifact; the builder, the verifier and the scorer are three different parties (05).
- Constrain the optimizer instead of refining the proxy metric. A metric that agents optimize directly stops tracking the goal (Goodhart's law), so hard invariants, guarded metric bundles and holdouts are kept outside what agents can change.
- Fail closed on money and access. Budget caps stop spending at runtime instead of only raising an alert, and one rehearsed action stops the whole system.
- Keep agent context in each repository. Each repository contains its own
AGENTS.md, with freshness enforcement. - Turn recurring work into deterministic tools. When a task recurs, a capable model writes a deterministic tool for it, and cheaper models run that tool from then on (05).
The dated repository state is in AGENTS.md § STATE; what is hosted, demoed or standalone is in the release policy.