ADR 0002 — The system model is a navigation axis, not a surface

  • Status: proposed
  • Date: 2026-08-19
  • Scope: putnami.dev (sites/putnami.dev)

Context

The docs information architecture had exactly one axis: choose your surface. Tooling, TypeScript, Go, Python, and the managed Platform were the first-level entry points, on the reasoning that those are the questions readers arrive with.

That axis answers "where do I work". It cannot answer "what is this system, and why should I trust it" — and the site had no published answer to the second question at all:

  • the protocol layer, which is what stops the frameworks, the tooling, and the platform from integrating through shared assumptions, appeared nowhere;
  • the agent-operability surface — the orientation documents, the blast-radius graph, the MCP tool contracts — was represented on the home page by four cards about conventions and editor compatibility;
  • the reasoning behind the constraints, and their cost, existed only as a principles page reachable through a secondary link.

The consequence was measurable in the copy. The home page described Putnami as "branch-native, local-first monorepo tooling for TypeScript", which is an accurate description of one axis and a poor description of the system.

Two smaller signals pointed the same way. Cross-cutting pages were rendered as cards inside the surface grid, which teaches a reader that "Concepts" is a sixth surface alongside Go. And src/lib/tools.ts carried UNIVERSAL, an exported list of "cross-cutting sections that apply to every tool" that nothing imported — the axis had been intended and never built.

Decision

The site has two navigation axes.

The system model — Why Putnami, Concepts & principles, Protocols, Agents — is read once and applies everywhere. It is presented as its own row on the docs hub, above the surface grid, and its pages are first-level nav entries. Reading order is deliberate: the bet, the layers, the contracts that make the layers checkable, and what those contracts enable.

Product surfaces — Tooling, TypeScript, Go, Python, Platform — are chosen per task, and the sidebar narrows after that choice. Unchanged.

Three constraints follow.

A model page is never a TOOLS entry. It carries no glyph, no page count, and no support subject. protocols/support classifies packages, protocols, and features — things a reader depends on. A page that describes the system is not one of those, and giving it a badge would invent a promise no catalog holds. This is the same reasoning ADR 0001 applied to the managed platform.

Python is browseable, but not a first-level anchor. PRIMARY_TOOL_ORDER drives top-level navigation and excludes it; TOOL_ORDER drives every browseable listing — the docs hub, the home strip, the surface menu, the command palette — and keeps it in its documented position between Go and the Platform. An anchor beside TypeScript and Go implies a parity the workspace does not offer. The spec requirement stands unchanged: every published surface that presents Python still states that it is experimental, requires explicit opt-in, is not default, and carries no Go or TypeScript parity promise.

Model pages are documentation, not marketing routes. They live under /docs/, so they are indexed by search, listed in llms.txt, and available through Copy as Markdown and the raw-markdown endpoint. These are precisely the pages an agent should be able to read.

Consequences

  • The site-owned section prefixes are renumbered to place the model pages in reading order: 00-why, 05-protocols, 06-agents, with tooling and frameworks shifting to 07 and 08. Published URLs are unaffected — toUrlPath strips the numeric prefix — but the asset entries in putnami.json move with the folders, and stale numbered directories under .gen/public/docs must be cleared before a rebuild or each section renders twice.
  • Adding a model page means editing two places by hand: MODEL_CARDS in src/app/docs/page.tsx and SYSTEM_LINKS plus the nav links in src/components/navbar.tsx. Nothing auto-registers.
  • UNIVERSAL and UniversalSection are removed from src/lib/tools.ts. They described this axis without implementing it; MODEL_CARDS supersedes them.
  • The home page still describes the product on the surface axis alone. That is now a visible inconsistency with the docs hub, and is left to a separate change rather than folded into this one.

Alternatives considered

Keep cross-cutting pages as cards in the surface grid. Rejected. With four model pages the grid reaches nine cards with no visual distinction between "a language you write in" and "the reasoning behind the system", and the ordering implies the model pages are the leftovers.

Publish the model pages as top-level routes outside /docs/. Rejected. It would exclude them from the search index, llms.txt, and Copy as Markdown — the machine-readable surfaces the pages themselves describe. A page arguing that agents should be able to read the system, which an agent cannot read, is not an argument.

Fold Protocols and Agents into Concepts. Rejected. Concepts is a mental map of the layers; the protocol layer is the evidence that the map is enforced, and the agent surface is what the evidence buys. Collapsing them produces one page nobody finishes.