# Product Docs

> Keep the Kaku website (kaku.fun, the vercel-branch worktree) accurate and user-facing: gather verified features from the current commit, refresh the docs and the plain-language Guide, keep EN/ZH parity, bump version pointers on release, and verify before handing the diff to the maintainer.

- Skill: `tw93/product-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add tw93/product-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tw93/product-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tw93 (https://skillmd.com/u/tw93)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tw93/product-docs

---


# Kaku Product Docs

Use this skill to write or update the user-facing product documentation on the Kaku website. The site is the deliverable; this skill is the repeatable flow for keeping it correct and adding the next feature without drift.

The audience is normal users, not contributors. Explain what each page/button/shortcut **is**, how to **reach** it, and what happens **after** you use it. Avoid implementation detail. No em dashes, no emoji (project + global rules).

## Where things live

- **Site worktree**: `~/www/kaku-site` on the `vercel` branch (NOT `main`). Vercel serves `kaku.fun` by pushing that branch. `git worktree list` confirms the path.
- **Design system**: Kami parchment system. Read `~/www/kaku-site/DESIGN.md` before any visual change. Match the existing pages; do not invent new components.
- **Doc pages** (EN under `docs/`, ZH under `zh/docs/`, kept in lockstep):
  Install (`index.html`), Guide (`guide.html`), Features (`features.html`), CLI Reference (`cli.html`), Configuration (`configuration.html`), Keybindings (`keybindings.html`), FAQ (`faq.html`), Contributing (`contributing.html`).
- **Guide vs Features**: Guide is the narrative onboarding walkthrough (first launch, then tabs/panes, shell, AI, tools, settings). Features is feature-by-feature reference. Keep the Guide short and link out to the reference pages; do not duplicate config tables there.
- **Screenshots**: `shots/kaku-dark.webp` and `shots/kaku-light.webp` (1920x1192). Reuse them with `<figure class="shot">`. Kaku is a native terminal, so CDP/browser screenshots do not apply to the app; only capture new app shots if the maintainer explicitly asks (build `make app` or use `/Applications/Kaku.app`, then `screencapture`).

## Source of truth: verify, never infer

User-facing docs are public. Do not copy feature claims from a subagent summary or from a feature's name. Confirm each claim against the running code before publishing:

- Defaults and behavior flips: grep `config/src/config.rs` (and its tests, e.g. `*_defaults_to_*`) and bundled config in `assets/`. Example caught this way: v23 flipped `smart_tab_mode` default to `suggestion_first`; the site still said `completion_first`.
- Shell behavior: `assets/shell-integration/setup_zsh.sh`.
- Keybindings / menus: the existing `keybindings.html` is the maintainer's authored ground truth; reuse its wording rather than re-deriving.
- The existing site docs are authoritative for tone and naming. When you add something new, verify it; when you echo something existing, match it.

## Workflow

1. **Scope**: read `git log`/`gh release list` for the current version and what changed. Read the nearest crate `AGENTS.md` and `CLAUDE.md` for feature notes (e.g. `config_version` changes).
2. **Inventory the site**: read the target page(s) raw to clone exact markup. Note `site-nav`, `docs-sidebar > docs-menu`, `section-toc`, `doc-content`, `doc-pager`, `footer`. ZH footer/skip-link wording differs from EN; copy the ZH variants verbatim from an existing ZH page.
3. **Write/edit content** in plain language. New page: clone an existing doc page's full scaffold, change `<title>`/`description`/`canonical`/`hreflang`/hero/`docs-menu` current item/`section-toc`/`doc-pager`. Anchors use a `page-` prefix (`guide-...`).
4. **Wire navigation** (a new page touches every doc page):
   - Insert the new `<a href="/docs/<page>"><span>Label</span></a>` into the `docs-menu` block of all EN doc pages, and the `/zh/docs/...` variant into all ZH pages. The page where the neighbor link carries `aria-current="page"` needs a separate sed (the attribute breaks a naive anchor match).
   - Fix the `doc-pager` prev/next chain on the two neighbor pages only (scope per-file so you do not rewrite the new page's own pager).
   - Add both URLs to `sitemap.xml` and a line to `llms.txt` (and `llms-full.txt` if it enumerates pages).
5. **Version pointers** (only when a release shipped): bump the current-version pointer, not historical references.
   - Bump: nav `>v0.X.Y</a>` (every page), JSON-LD `"softwareVersion"` (both `index.html`), AppleScript `get version` example, `llms-full.txt` `Latest version:`, and the version in `agent.json`. `python3 scripts/check_public_facts.py` (network) fails when `agent.json` or `llms-full.txt` disagree with the latest GitHub release.
   - Leave alone: roadmap narrative ("V0.X.0 is out", "after V0.X.0") and any "this version added" history.
   - Confirm the release is actually public first (`gh release list`), or the site will document an unreleased default.
6. **Verify before declaring done**:
   - `python3 scripts/highlight.py --check` (0 files need highlighting).
   - `python3 scripts/build_markdown.py --check` and `python3 scripts/build_feed.py --check`: the `.md` twin beside every page and `feeds/pages.jsonl` are generated from the HTML, so run both without `--check` after editing HTML and commit the regenerated files with it. A new page also needs the `<link rel="alternate" type="text/markdown">` head tag (`DESIGN.md`).
   - Internal links resolve under `cleanUrls` (every `/docs/x` has `docs/x.html`).
   - HTML well-formed (no unclosed/stray tags) on new/edited pages.
   - EN and ZH parity: same sections, same anchors, same tables.
   - **Browser screenshot of key pages (CDP / browser-debug)**: capture each changed/new page rendered in a real browser engine. The Kaku app is a native terminal, so app screenshots need `make app` / `/Applications/Kaku.app` + `screencapture` and are only done on explicit request; the website pages, however, are browser-debuggable and should be screenshotted as standard verification. On a machine with only Safari (no Chromium), use the Preview MCP's bundled engine:
     - Build a temp root so a deep page renders at `/`: `cp docs/<page>.html /tmp/prev/index.html` and symlink the assets it references by absolute path (`ln -sf <site>/styles.css <site>/shots <site>/img /tmp/prev/`).
     - Add a `.claude/launch.json` config running `python3 -m http.server <port> --directory /tmp/prev`, then `preview_start`, take a screenshot, and resize the preview to the `mobile` preset for the 375px check (DESIGN.md mandates desktop + 375px).
     - The bundled browser caches the loaded page, so after swapping the temp `index.html` to the next page (e.g. the ZH variant), `preview_stop` then `preview_start` to force a fresh load before the next screenshot. Confirm the live nav version, the current-page sidebar highlight, and EN/ZH typography all render.
7. **Hand off**: show the diff. Do NOT commit or push the `vercel` branch unless the maintainer says so this turn (git safety rules). Pushing `vercel` deploys to production immediately.

## Adding the next feature later

- Decide the home: a daily-use behavior becomes a bullet/step in the **Guide**; a configurable surface or new tool becomes a section in **Features** (plus Keybindings/Configuration if it adds a shortcut or option).
- Always update EN and ZH together. Mirror anchors and tables exactly.
- Re-run the verify checklist. Keep diffs minimal and atomic per behavior.