/manual

name: manual
description: Build and maintain a branded, interactive user's manual for this codebase. First run walks a setup flow (brand assets, codebase orientation, optional issue-tracker link to Jira or GitHub Issues, push-time guard); later runs update the manual to match the user-facing surfaces that have changed. Use for "/manual", "build the manual", "update the manual", when the pre-push guard reports the manual is stale, or when a <reorder> or <recopy> payload from the manual needs applying.

The living manual

One HTML file, self-contained, brand-styled, interactive: clickable headings file notes that become tickets, roadmap previews show planned changes, a glossary explains novel concepts on first use, and readers rearrange the manual by dragging its contents or correct its prose in place. The browser keeps a reader's order and their edits; an optional payload makes either one committed. This skill builds it once, then keeps it matched to the released code.

All prose you generate follows `reference/writing-style.md` in this plugin. Read it before writing any manual content. It is binding.

Token discipline: the scripts in `scripts/` exist so you never do their work by hand. Run them, read their compact output, act on it. Do not re-read the whole codebase on update runs; `stale.sh` tells you exactly what changed.

`$LM` below is the plugin root. This file lives at `$LM/skills/manual/SKILL.md`, so resolve it from the path this skill loaded from.

Every question you ask during setup must be answerable from what is on the user's screen. Print the thing you are asking about (the feature map, the palette and its proposed roles, the tracker's projects, labels, and milestones) in your reply first, then ask. Answer choices never reference content the user has not been shown.

Every invocation starts the same way

sh $LM/scripts/state.sh

Branch on the JSON: `configured: false` → setup flow. Otherwise → update flow (or the specific request the user made).

Setup flow (first run)

Work through these in order. Each step ends with something written to disk, so an interrupted setup resumes cleanly (state.sh shows what exists).

**1. Orient to the codebase.** Run `sh $LM/scripts/inventory.sh <repo-root>`. From its output plus the README and any changelog/roadmap docs, build the feature map: user-facing surfaces and the shipped features on each. Read the main UI entry point and each surface component; the manual documents what users experience, so ground every section in the code that renders it. **Print the full map in your reply** (a plain nested list: surface → features), then ask the user to confirm or correct it — missing features, wrong groupings, things that aren't user-facing. A wrong map here costs the whole document.

**2. Locate brand.** inventory.sh lists brand-candidate directories. Read what's there: style guides, palettes, logo files, design docs. Extract: palette (with semantic roles), typography, shape language, voice. Print the extracted palette with each hex value and its proposed role before asking the user to confirm; when roles are ambiguous, the question names the specific colors in its options. No brand assets: offer the neutral default palette (scaffold.py's fallback) and note it in the config so a later brand pass knows. A logo file becomes a data URI (downscale to ~96px first: `sips -Z 96 in.png --out small.png`, then base64) so the manual stays self-contained.

**3. Issue tracker link (optional).** Read `$LM/reference/trackers.md` first; it defines the supported providers, the config schema, and the inspect-propose-commit discipline this step follows. Run each provider's detect step (Jira: Atlassian MCP via ToolSearch; GitHub Issues: `gh` authenticated and the repo resolves). None usable: record `"tracker": {"provider": "none"}` with the reason and the enable path. Otherwise ask which provider receives tickets, offering only the usable ones plus "none".

Then, for the chosen provider: run its inspect step and print what the project already has (Jira: issue types, components; GitHub: labels, milestones) before proposing anything. Propose a mapping of ticket types (`bug`, `idea`, `feedback`) onto that existing taxonomy, plus any optional routing (component, milestone, extra labels) drawn from the same lists. Never assume the defaults in trackers.md fit.

Map a type onto an existing label only when that label means what the type means, not when it is merely the closest thing available. When nothing fits, lead with creating a label named for the type, marked "would be created", and offer reuse as the alternative to it rather than as an equal option. When you do propose reuse under a different name, say so in the proposal and say what the existing label actually means, so the user is choosing the compromise rather than inheriting it. Create nothing without explicit confirmation.

A type may map to several labels when the project routes that kind of work with more than one; see the config schema in trackers.md. Verify write permission the provider's way; never create a test issue to probe. Record the confirmed mapping in the `tracker` block. Write access missing: record `"provider": "none"` with the reason, in the user's terms.

**4. Write the config.** `.living-manual.json` at repo root:

{
  "product": "...",
  "tagline": "...",
  "tagline_pill": "...",
  "manual_path": "docs/USER_MANUAL.html",
  "tickets_dir": "docs/tickets",
  "ticket_skill": "/living-manual:ticket",
  "user_facing_paths": ["src/", "app/src/"],
  "brand": { "ink": "...", "surface": "...", "deep": "...", "accent": "...",
             "warn": "...", "caution": "...", "font_stack": "...",
             "hero_gradient_css": "...", "logo_data_uri": "..." },
  "tracker": { "provider": "github",
               "github": { "repo": "acme/app",
                           "labels": { "bug": "bug", "idea": "enhancement",
                                       "feedback": "feedback