Bluedoc

---
name: bluedoc
description: Generate self-contained HTML engineering docs (setup guides, change proposals, implementation plans, PR review findings, UI mockups, slide decks, website reviews) with zoomable blueprint canvases that open into each system's internals and play animated data/control flows, persistent checklists, plans, designs and websites the reader approves or sends back from the page, a board of sandboxed HTML screens for watch, phone, desktop, web and slides, a site's live dev-server pages with comments pointing at the source, and a code browser that pins review findings to their lines. Use when asked for an HTML doc, architecture page, system walkthrough, runbook, onboarding guide, a plan, an implementation plan, a design doc, UI mockups, wireframes, screen designs, slide decks, a website or landing page to review or edit together, "plan mode", "make a plan", "propose a plan", "peer review results", "review findings", "review comments in a bluedoc", "open threads", or "a bluedoc".
---

# bluedoc

You write one `*.bluedoc.json`; the local server renders it as a page (blueprint canvases, checklists, plans to approve, code review, revisions) and hands the reader's replies back to you. `<skill>` is this folder; scripts need Python 3.9+, stdlib only.

## Workflow

1. **Gather facts from the source.** Read the code, configs and runs the doc describes. Every node, step and finding maps to a file, symbol, queue or command; keep `path:line` anchors for `refs`. Mark what you did not observe `unverified`.
2. **Scaffold:** `python3 <skill>/scripts/build.py new <type> docs/<topic>/<name>.bluedoc.json --title "…" [--kind Runbook]`. Plans go in `docs/plans/<topic>.bluedoc.json`; a review of a PR adds `--of post` when someone else owns it (the reader can only post your comments or not) or when the reader asked you to review their own PR, and `--of threads` for peers' comments on the reader's own PR (check the author with `gh pr view`); a codebase review by area, not by PR, adds `--shape area`; a design adds `--target watch,mobile,desktop,web --framework …`, and `--icons` for an app icon; a deck is `new presentation`; a site is `new website --url http://localhost:<port>/`; an app's store listing is `new storelisting`. Then read the type's guide (table below), once.
3. **Fill every `<<…>>`**, adding or dropping blocks as the guide says: write the doc once (one `write` of minified JSON on one line, never pretty-printed) or `build.py patch` it. Images and videos go next to the JSON (`media/…`), referenced by relative path. You may set a top-level `emoji` (one emoji, e.g. `"🛒"`); the reader may rename the doc and change its emoji, which you never see: don't undo it.
4. **Validate:** `python3 <skill>/scripts/build.py <doc>`. Fix every `ERROR`; fix every `WARN` unless it is a false positive you can name. This records the revision. A passing build is the whole verification: no browser check.
5. **Open:** `python3 <skill>/scripts/serve.py open <doc> --to <your model family>` (Claude, Codex, Copilot, Gemini, GLM…: never the user's name) starts the server if needed and prints the URL with a `?key=` token good for an hour; later edits show on reload. Give the reader that exact link (it lets their browser save) and what stays unverified. A page that says "This browser can't save yet": run `serve.py unlock` and send its link.
6. **Wait** in the background, no timeout: `python3 <skill>/scripts/serve.py wait <doc> --kind any`. It prints `--- bluedoc <kind> (reply <id>, …) ---`, the reader's Markdown, `--- end ---`. Replies sent while nobody waits are queued; `serve.py reply <id>` reprints one.

| Type | Guide | When |
|---|---|---|
| `plan` | `types/plan.md` | Anything you'd hand over before implementing: plan mode, "make/propose a plan", a technical design doc. |
| `design` | `types/design.md` | UI mockups: app screens for watch, phone, tablet, desktop or web, as HTML on a board. |
| `website` | `types/website.md` | A website's pages to review or change together (marketing site, landing page, blog), live from its dev server: comments point at the source. |
| `storelisting` | `types/storelisting.md` | An app's store listing on Google Play and the App Store: screenshots per device, store text, locales. |
| `presentation` | `types/presentation.md` | Slides: a deck, a talk, a review or pitch to present, as HTML slides with speaker notes. |
| `review` | `types/review.md` | Review results (peer, agent, open PR threads), always, without being asked. |
| `docs` | `types/docs.md` | Architecture, walkthrough, runbook, setup guide, change proposal. |
| `other` | `types/other.md` | Anything else: status page, report, inventory. |

After `new`, never read or hand-edit the JSON: `build.py get <doc>` lists every key, `build.py get <doc> <key>` prints one object, `build.py patch <doc> <key> --set a/b/c=v` changes it, `build.py schema <block>` shows a block's fields. Once the doc has been built, bluedoc's hook refuses edit and write tools on it (patch-only edits).

## Replies

When `wait` returns, read `types/replies.md` once: how to answer, revise, resolve and record evidence.

## Writing

1. Answer first: `tldr` and each `lead` state the conclusion, not the topic.
2. Say it once: no section repeats another; prose never repeats a table.
3. Cut every sentence whose removal breaks nothing; no closing summary.
4. Same words: define terms once in a `terms` block and reuse them exactly.
5. Name the actor and the condition: "If the token expired, the server closes the socket."
6. Checkable, not vague: numbers, names, conditions, or "unknown".
7. Shape fits content: procedures are checklists (`text` an imperative action ≤ 90 chars, `sub` why); comparisons are tables (in an item's md, a Markdown table is fine); a `caution` (data, equipment) or `warning` (people, production) callout sits before the step it guards.
8. The reader chooses through decision items (`choices` + `recommend`), never "check if you agree". Every choice gets an `md` explanation, 1–3 sentences: what picking it means and what it costs (the build requires it on new docs). Use `multi: true` when several answers make sense (`recommend` may then be a list). Set `choice` only to carry over the reader's own pick. A checklist is either a decision list (every item has `choices`) or a progress list (none has): never both; put decision lists before progress lists.
9. Short is not cryptic: keep commands, risks and real uncertainty.
10. Sound like a colleague: no ceremony, flattery or hedges.

The linter warns on filler, vague words, sentences over 32 words, titles over 90 and `sub`s over 120 characters, option labels over 28, topic-first leads, a closing summary section, numbered-list procedures, checklist items that don't start with a verb, and "check if you agree" items; the rules still apply beyond it.

## Never

- Read or write HTML, `assets/` (template, home page, kits) or `examples/`; a design's own screen files (`<name>.design/*.html`) are the one exception. `build.py <doc> -o out.html` writes a file only when someone needs one to send.
- Read or grep `references/schema.md` for fields: run `build.py schema <block|type>`.
- Rename ids across revisions: they key the reader's ticks and the revision diff.