| name | product-docs |
| description | 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. |
| when_to_use | update website, update docs, 更新官网, 完善官网, 产品说明, 使用文档, 上手指南, product guide, document a feature, refresh kaku.fun, write user docs, site 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 → 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
- 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).
- 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.
- 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-...).
- 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).
- 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:.
- 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.
Adding the next feature later
- Decide the home: a daily-use behavior → a bullet/step in the Guide; a configurable surface or new tool → a section in Features (+ 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.
