Happier Docs

Happier Documentation

Keep documentation truthful, useful, current, and owned without turning every code change into prose churn. Follow the root constitution and, for published docs, apps/docs/AGENTS.md. For an explicit deep review or QA request, use .agents/skills/happier-review as the orchestrator and apply this skill as the documentation-domain standard; this skill does not create a competing general review workflow.

1. Classify the documentation impact

For the changed behavior or contract, decide whether it affects:

• internal technical/product architecture under docs/**;
• published user/operator/self-hoster/contributor behavior under apps/docs/content/docs/**;
• both surfaces;
• neither surface, with a concrete reason.

A refactor that leaves every documented contract unchanged may need no docs edit. A behavior, command, setting, support status, workflow, failure/recovery path, protocol, persistence shape, compatibility rule, deployment requirement, or canonical owner change normally does.

2. Identify audience, page type, and canonical owner

Classify published pages as task guide, concept, reference, troubleshooting, or development documentation. Internal docs explain architecture, contracts, ownership, and contributor-facing implementation constraints.

Search by the feature, command, setting, route, schema, provider/agent id, UI label, error, and reader phrasing before creating a page. Update, move, consolidate, or retire the canonical page instead of adding a parallel explanation. Map links, navigation, related pages, examples, and translations or screenshots that depend on the changed documentation contract.

Placement is part of authorship, not cleanup afterwards. A published page belongs to exactly one section, is listed in that section's meta.json at the point a reader should meet it, and is linked from that section's index.mdx. A page missing from either is unreachable in a way that breaks no link and shows up in no diff. Moving a page is the same four edits in reverse. The section inventory is in apps/docs/AGENTS.md.

3. Establish product truth and release basis

Documentation is a claim, not proof. For Happier behavior:

• inspect the reachable implementing producer and consumer, not only a matching string;
• identify gates, defaults, platform/provider variation, failure/recovery behavior, and compatibility seams material to the claim;
• establish the page's target stable, preview, development, or explicitly future basis from immutable release/artifact evidence when availability is release-sensitive;
• distinguish shipped, preview, development-only, experimental, deprecated, planned, and merely possible behavior.

README files, existing docs, changelogs, plans, issues, PR descriptions, commit messages, comments, and generated summaries are orientation. They do not independently prove that behavior is reachable or released.

For vendor-owned behavior, use current official vendor documentation and keep attribution with the claim. Do not state a competitor's limitation as Happier's own conclusion. Never invent product names, capabilities, support levels, guarantees, dates, quotes, or personal experience. Cut unsupported superlatives and comparisons.

Use .agents/skills/happier-compatibility when documentation claims depend on released/predecessor formats, mixed versions, upgrades, rollback, migrations, or persisted historical data.

4. Choose the edit contract

Use the narrowest mode that serves the reader. Every added section or sentence must improve a decision, action, mental model, evidence boundary, or material caveat; prose that only restates another canonical owner does not earn its place:

• Patch: add or correct bounded material and preserve every unaffected claim, example, link, caveat, and structural choice.
• Polish: improve clarity and flow while preserving structure, information density, factual scope, and recognizable voice.
• Rewrite: redesign structure or framing only when explicitly requested or when the current document cannot serve its audience.

An approved or preferred version becomes the baseline for later edits. A high change count in a correction pass is a warning sign, not evidence of quality. Every correction is a new claim: verify it as carefully as the text it replaces and do not swap one unsupported absolute for its opposite.

Before a substantial rewrite, inventory every material claim involving behavior, commands, settings, support, platforms, providers, compatibility, security, failure/recovery, readiness, and exact names. Account for each in the result. Humanizing is not summarizing.

5. Prefer generating over writing

Before drafting a reference table, check whether the same list already exists as structured data. Agent capabilities, feature flags, keyboard shortcuts, rate limits, download links and — where the plugin platform is present — runtime events, bundled plugins and the SDK's public surface all do. apps/docs/scripts/generateReference.mjs is the registry of what is generated today. Hand-maintained restatements of code are the single largest source of documentation drift in this repository, because nothing connects the data changing to the prose describing it.

Generate it, or link to the generated page. A generated page is compared against a fresh render on every build, so drift fails instead of shipping. Reserve hand-written prose for what a generator cannot produce: the mental model, the reason the mechanism exists, the failure modes, the judgement calls.

Two traps live inside the generators themselves. A hand-kept map of display names inside a generator drifts exactly like one inside a page — read the names from the source the app reads. And a declared field is not behaviour until you have found its consumer: publishing a flag whose value contradicts what the product does is worse than publishing nothing.

Where a capability is gated — a server feature flag, an experimental toggle, the account-level Experiments switch, a platform, a channel — the gate is part of the claim. Read uiFeatureRegistry.ts and features/catalog.ts rather than assuming availability, and state the gate where the reader meets the feature.