The naapp /reference page

A naapp's reference is an engineering API reference, not a marketing page. Its reader is a developer or an agent looking up an operation. It is generated by the toolkit (aweb_naapp.render_reference(manifest, site, verb=…, …)) from the app's manifest — you don't hand-write it per app. This skill is what "correct" looks like and how an app tunes it.

Voice

• It is a reference: dense, scannable, precise. Favor information density over whitespace and persuasion.
• The canonical interface is the aw <verb> command. The raw HTTP / curl wire form is a secondary detail for someone porting a client — it is anecdotal, not the message. Never present curl as a co-equal headline.
• No marketing hero, no "two ways" framing, no CTA buttons on the reference.

Shape

• Compact header — a plain "API reference" title + one mono provenance line ("Generated from aweb-app.json · llms.txt"). No centered hero, no CTAs, no counts that don't earn their place.
• Sticky left sidebar = operation index — operations grouped Public / Authenticated / Events (only the groups that exist), mono verb names as jump links, an "Authentication" link at the bottom. Scroll-spy highlights the operation in view (an IntersectionObserver in the site script; no-op off the reference page).
• Flat divider-separated entries (NOT cards) — one per operation:
  • Signature line: aw <verb> <name> (primary, mono) + METHOD (muted; bolder for mutating POST/PUT) + /path (faint) + subdued mono tags (scope like library:read, and public / team cert) grouped on the right.
  • One-line description.
  • A typed params table: Parameter / In (path|query|body) / Type / Required (required in ink, optional faint).
  • The primary aw <verb> command in a copy block.
  • The HTTP wire form demoted into a collapsed <details> ("HTTP wire format") — for signed ops it also holds the aw id request form. Closed by default; natively keyboard-accessible.
• Authentication at the bottom — the team-auth-envelope-v2 spec (the four signed headers, the canonical-JSON envelope, the encoding/reserved-field notes), linked from each signed op via #auth. Out of the way of someone just looking up a call; one section-level "aw signs these for you" note, not repeated per op.
• One terracotta accent only (sidebar active state + hover anchors). Auth/scope tags are muted, not loud colored pills.

The data model (so overrides are implementable)

The manifest's tools carry: name, method, path, description, params (each {name, in}), input_schema (properties[name].type, required), auth (none = public), scopes, mutation. public_tools / cert_tools split by auth; events render as their own group. The generator already surfaces all of this — if a field exists, show it; if it doesn't (e.g. there are no response schemas in the manifest), do NOT invent it. A reference with made-up response shapes is worse than one without.

Per-app tuning

Apps don't restyle the page; they pass ReferenceCopy overrides (the section headings/blurbs in their own nouns), the plugin verb namespace, and example_path_values so a public read renders a genuinely runnable curl. Keep overrides domain-accurate; the defaults are domain-neutral so a new naapp gets a correct generic reference out of the box.

Anti-patterns (what a bad reference looks like)

• Centered marketing hero ("Every operation, two ways") + CTAs → compact header.
• curl/wire shown co-equal with the verb → demote it into <details>.
• A long monotonous stack of tall cards, no index → flat entries + sidebar index.
• Loud status-colored auth pills → subdued mono tags, distinguished by label not color.
• required:/optional: as loose prose → a typed params table.
• Jargon dump in prose → the structured signature + table + the auth section.

Verify live

As with every aweb surface: the generated reference can be correct in the build and broken in production (a stale image served the old stylesheet with no styles). After deploy, open the live /reference, confirm the sidebar + entries render and the wire <details> opens — don't trust the golden or the deploy report.