Kami

kami · 紙

紙 · かみ - the paper your deliverables land on.

Good content deserves good paper. One design language across eight document types: warm parchment canvas, ink-blue accent, serif-led hierarchy, tight editorial rhythm.

Part of Kaku · Waza · Kami - Kaku writes code, Waza drills habits, Kami delivers documents.

Update check (non-blocking). At the start of a task, run bash scripts/check-update.sh. It does a read-only version check at most once per day and prints one line when a newer kami is available; relay that line to the user, then continue. It sends no data, and fails silently when offline, sandboxed, or without curl. Never let it block the work.

Step 0 · Load brand profile (if exists)

Check ~/.config/kami/brand.md (preferred) or ~/.kami/brand.md (legacy fallback). If found, read references/brand-profile.md for the full four-layer application spec (placeholder substitution, session defaults, visual customization, habit notes) and its six guardrails. If no profile exists, continue without interruption.

Key rule: explicit prompt > editorial judgment > habit notes > frontmatter defaults > built-in defaults. Profile fills gaps silently; it never overrides the current conversation.

Step 0.5 · User project style scan (opt-in)

Run this only when the user explicitly references a sibling project as a visual reference: "like my <project> site", "match the style of <repo>", "use the look from <directory>". Skip silently when no such reference exists.

When triggered, before generating:

1. Locate the referenced project's style files:

   find <referenced-path> -maxdepth 4 \( -name "*.css" -o -name "tailwind.config.*" -o -name "theme.*" -o -name "tokens.*" \) | head -20

2. Extract: dominant color values (hex / hsl), font stack, spacing scale, border-radius scale. Prefer values declared in CSS variables or design tokens over inline literals. 3. Merge into the in-session brand profile as Layer C (visual customization), not Layer B (session defaults). Do not override an explicit --brand flag or values that the user typed in this turn. 4. Report back in one line before continuing: "scanned <project>, extracted N colors / M fonts; using as visual reference."

Skip and fall back to the brand profile defaults if the referenced path does not exist, no CSS-like files are found, or the extraction would conflict with the user's explicit values in the current message.

---

Step 1 · Decide the language

Match the user's language. Chinese -> *.html / slides-weasy.html. English -> *-en.html / slides-weasy-en.html. Japanese -> CJK path (.html / slides-weasy.html) as best-effort, JP Mincho first, visual QA before shipping. Korean -> dedicated *-ko.html / slides-weasy-ko.html family as best-effort, visual QA before shipping. Reference docs are shared English specs.

When ambiguous (e.g. a one-word command like "resume"), ask a one-liner rather than guess.

Default to the WeasyPrint HTML path; fall back to PPTX (slides*.py) only when the user explicitly needs an editable deck.

Always use CHEATSHEET.md and references/*.md for design, writing, production, and diagram guidance.

Code blocks with class="language-*" are highlighted only when optional Pygments is installed in the build environment. Without it, PDFs still render and code blocks stay monochrome.

Step 1.5 · Intent extraction (silent checklist)

Before choosing a template, verify these four dimensions are clear. Do not ask unless 2+ are missing and cannot be inferred from context.

Rules:

• If the conversation already answered a dimension, skip it silently.
• If a dimension can be inferred from the document type (e.g. resume purpose is always "get an interview"), skip it.
• If 2+ dimensions are genuinely unclear, ask in a single compact question (max 2 sub-questions).
• Never ask all four as a checklist. This is a background verification, not a form.

Execution contract

Before creating or modifying an output, lock the contract: language, template, output format, page or length target, visual acceptance check, and verification command. Infer from the user's request when clear; ask only when missing fields materially change the deliverable.

Use the nearest existing template and verification path. Do not add a new template, shared CSS layer, dependency, script flag, or optional mode unless the current request cannot be satisfied without it.

If a change touches SKILL.md, templates, scripts, references, or package inputs, decide whether dist/kami.zip must be refreshed before handoff. Shipped behavior is not ready until the package contains the changed files.

---

Step 2 · Pick the document type

Changelog vs. release notes: The changelog template above is for styled document output. GitHub release notes are a separate deliverable; use /write with Release Note Template Mode.

Landing Page: Screen-first interactive template. No PDF output. Includes gallery carousel with auto-rotate, hero entrance animation, responsive breakpoints (880px / 480px), and prefers-reduced-motion support. Deploy as static HTML to Vercel / Netlify / any host. The agent fills {{PLACEHOLDER}} values and HTML comment blocks, then saves as a ready-to-serve .html file.

Landing Page companion files: For a production multilingual deploy, copy the five landing-page-*.example files alongside the main HTML, remove the .example suffix, and fill the placeholders. They cover Vercel rewrites and headers, sitemap hreflang, robots AI allowlist, and llms.txt + llms-full.txt for AI assistants. The main HTML already ships matching hreflang and og:locale in <head>; an Accept-Language redirect at the end of landing-page-en.html is commented out for opt-in. {{SITE_ORIGIN}} is the scheme + host of your {{CANONICAL_URL}} (e.g. https://example.com). See references/design.md Section 11 «Companion assets».

Production product site mode: If the user needs docs, help, releases, changelog, roadmap, legal pages, or more than two locales, treat it as a site system. Lock product category, real screenshot slots, locale list, companion files, long-content pages, and generator/check needs before filling templates. Keep project-specific release artifacts, payment providers, appcast rules, and private local paths out of Kami. See references/design.md Section 11 «Product site system».

Documentation pages: When a landing page grows into a docs or help site, use the doc shell in references/design.md Section 11 «Documentation site»: a sticky sidebar nav with a 2px brand rail (not a dark underline), an on-this-page TOC hidden below the tablet breakpoint, a constrained prose measure, and a quiet borderless prev/next pager (text links, not bordered cards). Highlight code at build time with zero runtime JS on a dark code surface; plain code stays the source of truth.

Slides: default to slides-weasy.html / slides-weasy-en.html / slides-weasy-ko.html (WeasyPrint HTML → PDF). Use slides.py / slides-en.py only when the user explicitly requires an editable PPTX file. Use assets/templates/marp/slides-marp(.md|.css) only when the user explicitly asks for Marp / markdown slides / a deck that lives in a .md file.

Deck recipe: read design.md Section 8 before drafting slides. Sketch title sequence, evidence shape, and image slot before generating or cropping visuals. Keep audience copy separate from visual briefs. Marp-specific constraints live in design.md §8 «Marp variant».

Decision tree (use before asking)

Walk this tree before reaching for a one-liner question. Ask only when two cells genuinely both fit.

Ambiguity examples that justify a one-liner:

• "1.5 page career story with heavy visuals" -> ask "resume or portfolio?"
• "2 page exec summary with metric tiles" -> ask "one-pager or equity-report?"
• "5 page argument with several charts" -> ask "long-doc or portfolio?"

Pick from the tree first. Ask only when the tree is genuinely silent.

Diagrams (primitives, not a separate template type)

When the user asks for a diagram inside a long-doc / portfolio / slide (not a standalone document), route to assets/diagrams/ rather than a template:

Read references/diagrams.md before drawing - it has the selection guide, kami token map, and the AI-slop anti-pattern table. Extract the <svg> block from the template and drop it into a <figure> inside long-doc / portfolio.

Before drawing, always ask: would a well-written paragraph teach the reader less than this diagram? If no, don't draw.

Auto-select charts from data. When content contains numerical data, choose the chart type and embed it without waiting for the user to specify. Decision tree (first match wins):

When data fits multiple types, prefer the one that shows variance most clearly. Always embed inside a <figure> with a caption that states the insight, not just the data range.

Step 2.1 · Source and material pass

Run this before distilling or filling content when the document depends on facts or materials outside the user's draft. Skip it only for personal drafts where the user already supplied everything needed.

Source check

Trigger when the document mentions a specific company, product, person, release date, version, funding round, metric, market fact, technical spec, or any current fact likely to change.

• Use primary sources before writing: user-provided material, official site, docs, filings, press release, app store page, or repo release
• Keep a short note of source names and dates for facts that drive the document
• If sources conflict or a fact cannot be checked quickly, ask the user instead of choosing silently
• Avoid current-sounding claims such as "latest", "recent", "new", version numbers, launch dates, or financial figures unless they are checked

Material check

Trigger when the document is about a company, product, project, venue, or personal brand.

Confirm the materials that make the subject recognizable before layout:

If a required item is missing, use a compact gap table and ask once. Do not replace missing material with generic imagery, approximate logo drawings, or invented values.

Logo fallback: when the request names no logo but the brand profile has a logo path, fill the commented .brand-logo slot in one-pager / portfolio / slides-weasy per references/brand-profile.md Layer C. Expand ~ to an absolute path, and if the file is missing or the template has no slot, leave it commented and render without a logo (never insert a broken image). An explicit logo in the current request always wins.

Materials status block

After the material check, output a structured status block before continuing. This is a one-shot transparency display, not a question:

Materials status:
- Logo: OK assets/client-logo.svg
- Brand colors: OK #1B365D mapped to --brand
- Product screenshot: MISSING (proceeding with kami default placeholder)
- UI screenshot: not required for this doc type

Use OK, MISSING, or not required. If a required item is missing and no user input arrived, ask once with the gap table; otherwise continue silently.

Step 2.5 · Distill raw content (if applicable)

Auto-detect whether to distill. Do not ask the user; judge from the input:

When in doubt, run distill. Distill is cheap; rebuilding a misaligned doc is not.

When the user hands over raw material (meeting notes, brain dump, existing doc in different format, chat transcript, scattered points):

1. Extract: pull out every factual claim, number, date, name, source, material reference, and action item 2. Classify: map each extract to the target template's sections (see references/writing.md for section structure per doc type) 3. Gap-check: list what the template needs but the raw content doesn't have - include missing facts, missing proof, and missing materials 4. Ask once: share the gap table with the user. Do not guess to fill gaps.

Example gap-check:

Then proceed to Step 2.6 (slides) or the layout note (all other doc types) with structured, distilled content.

Step 2.6 · Deck pre-flight (slides only)

Skip this step for every doc type except slides.

Path selection

Default to the WeasyPrint HTML path. Switch to pptx only if the user explicitly requires an editable PPTX file. Switch to Marp only when the user explicitly asks for Marp / markdown slides.

Page size

Default is 280mm 158mm. Ask only if the user has mentioned length or density constraints.

Content pre-flight

Before drafting any slide, confirm these points with the user. Ask all at once, skip any already answered:

Before drafting any landing page or product site, lock these points from the source material. Ask once only when a missing item would change the deliverable:

Content rules for slides

• Ghost deck test: read only the slide titles in order. They must tell the argument; if not, fix titles or structure before styling
• One evidence shape per slide: chart, table, screenshot, code, quote, or conclusion. Split mixed evidence instead of crowding one slide
• Audience copy stays clean: titles, body, and captions never contain image prompts, crop instructions, or generation notes
• No section divider slides: use .eyebrow for section numbering, not a dedicated blue-background page
• No CJK parentheses: replace （...） with · or ,
• Each bullet fits one line: trim until it does
• 2×2 layouts: use table.t2x2, not CSS Grid
• Pinned conclusions: use .co at position: absolute; bottom: 12mm

These rules apply identically to Marp decks. Marp-specific syntax: see references/design.md §8 «Marp variant».

Step 2.7 · Layout note (transparent, non-blocking)

Before loading specs and filling the template, write a short editor-style note stating the layout intent: template choice, length target, narrative arc, embedded diagrams, material status, and output formats. Match the document's language. Keep it under 80 words, written as prose, not a status panel. Continue immediately after; do not wait.

Example (CN):

排版意图：Equity Report 中文版，2 页 A4。先立论与目标价，进入估值 (DCF 与可比公司)，落于催化剂与风险。中段嵌一张营收趋势折线和 FY26 收入桥瀑布。Logo 已就位，产品图暂缺，header 改走纯文字。输出 HTML 与 PDF。

Example (EN):

Layout intent: Equity Report (EN), two pages A4. Open with thesis and price target, run through valuation (DCF and comparables), close on catalysts and risks. A revenue line chart and an FY26 waterfall sit mid-doc. Logo is in hand; product image is absent, so the header stays text-only. Output: HTML and PDF.

The note is for transparency, not approval. If the user pushes back, adjust; otherwise proceed to Step 3.

---

Step 3 · Load the right amount of spec

Pick the tier that matches the task. Default to the lowest tier that covers the work.

You can always escalate mid-task if the work turns out to need more than the initial tier.

The full spec files for reference:

• Design: references/design.md
• Writing (general): references/writing.md
• Writing (resume-specific): references/resume-writing.md
• Production: references/production.md
• Diagrams: references/diagrams.md
• Anti-patterns: references/anti-patterns.md

Step 4 · Fill content into the template

• Copy the template into your working directory; don't write HTML from scratch
• CSS stays untouched, only edit the body
• Content follows writing.md: data over adjectives, distinctive phrasing over industry clichés
• Avoid patterns listed in references/anti-patterns.md: emptiness, fabrication, mimicry, excess, source gaps, tone contamination
• Before filling, read the quality bar for your document type in writing.md section "Quality bars by document type". Structure is necessary but not sufficient: a resume bullet needs Action + Scope + Result + Business Outcome; an equity report needs variant perception + quantified catalysts; slides need assertion-evidence titles. Meeting the quality bar is as important as filling every placeholder.

Do not generate

These are the most common AI document failures. Cross-reference references/anti-patterns.md for the full list.

• Do not leave placeholder text in the final document ("Lorem ipsum", "[Insert here]", "TBD")
• Do not invent metrics, financial data, or statistics; mark gaps with [DATA NEEDED: description]
• Do not use stock-image descriptions as image placeholders ("A diverse team collaborating in a modern office")
• Do not pad content to fill template slots (a resume with 3 real projects does not need 5 fabricated ones)
• Do not write a paragraph that merely restates its own heading in sentence form

Fill PDF metadata (WeasyPrint reads these into the PDF)

Every template has meta placeholders in <head>. Fill all four before building:

<meta name="generator" content="Kami"> is already fixed in the template; do not change it.

Author inference: build.py automatically sets PDF /Author metadata from: 1. git config user.name (primary) 2. KAMI_AUTHOR environment variable (fallback) 3. "Kami" (final fallback)

For personal documents (resume/letter/portfolio), the HTML <meta name="author"> should match the person's name in the content. For non-personal documents (one-pager/long-doc), leave the placeholder as-is and let the build script infer it.

Step 4.1 · Per-page density target (multi-page templates only)

适用：slides-weasy / long-doc / portfolio / equity-report / changelog。不适用 resume / one-pager / letter（这些有独立的长度合约）。

正文页填充率目标 60-80%。封面 / 目录 / 末尾署名页豁免。这条规则解决的是 AI 生成多页文档时最常见的 draft 缺陷：把内容拆得太散，结果几页都填不满。

Items-per-page contract

Sparse-page merge rule

Before finalizing, scan the draft. Any body page that would render under 50% full → apply one of, in order:

1. Merge upward into the previous section. 2. Merge downward into the next section. 3. Promote a list to a small diagram or table that earns the space. 4. Pin a .co callout to bottom (slides-weasy only). Whitespace above a pinned callout is intentional, not sparse.

Forbidden ways to "fill" a sparse page: padding with filler prose, repeating the heading as a sentence, inventing statistics, restating the prior page in different words. If the merge options don't apply, the page itself shouldn't exist.

Last-page exemption

The last body page is allowed to run 40-60% fill. Forcing balance on the last page usually means padding. The colophon / closing slide may have any fill level.

Verify after build

python3 scripts/build.py --check-density   # flags >25% (WARN) / >50% (SPARSE) trailing whitespace

If a body page (not cover, not last page) gets a SPARSE warning, treat it as a draft defect and re-author with the merge rule.

Step 4.5 · Auto-select output format

Do not ask the user which format to export. Decide from context:

PDF always ships for document templates. Landing pages ship as a ready-to-serve static HTML file. PPTX follows slides. PNG follows sharing context. The user should never need to think about formats.

Step 5 · Build & verify

python3 scripts/build.py --verify           # build all templates + page count + font check + slides
python3 scripts/build.py --verify resume-en # single target full verification
python3 scripts/build.py landing-page        # screen-first static HTML template check
python3 scripts/build.py --verify slides    # single slide deck verification
python3 scripts/build.py --check-placeholders path/to/filled.html
python3 scripts/build.py --check-resume-balance path/to/resume.pdf
python3 scripts/build.py --check-density              # page whitespace scanner (skips cover)
python3 scripts/build.py --check            # CSS rule violations only (fast, no build)
python3 scripts/build_metadata.py --check   # Codex plugin mirror + marketplace drift check

Screen verify: --check-density is a print gate. For screen output (landing or docs pages) instead screenshot the rendered page at 375px and 1280px in every locale and scan for line widows before shipping. See references/design.md Section 11 «Responsive screenshot verification».

Source templates intentionally keep {{...}} fields. Run placeholder checks on completed documents, not on the template library.

Visual anomalies (tag double rectangle, font fallback, page break issues) -> production.md Part 4.

Maintainer-mode checks

Use these only when maintaining this repository or release package, not for ordinary document generation.

• If marketplace metadata, generated plugin mirrors, version selection, or install paths change, run python3 scripts/build_metadata.py --check; for Codex install behavior, also smoke with an isolated CODEX_HOME=/tmp/... using codex plugin marketplace add <path>, codex plugin add kami@kami, and codex plugin list.
• If SKILL.md, templates, scripts, references, or other package inputs change and the behavior ships through the skill package, run bash scripts/package-skill.sh and inspect dist/kami.zip before handoff.
• If a GitHub release asset is refreshed, download the uploaded kami.zip and compare ZIP entry names plus per-entry SHA-256 digests against local dist/kami.zip; page text, file size, and the container hash are not enough.

Fonts

Chinese

• Main serif: TsangerJinKai02-W04.ttf (400 weight) + TsangerJinKai02-W05.ttf (500 weight, real bold)
• Templates use dual @font-face declarations: W04 for body text, W05 for headings
• Both files are commercial fonts. Keep them available in the repository for local preview and CDN fallback, but do not bundle them inside Claude Desktop skill ZIPs
• Fallback chain baked into templates: Source Han Serif SC -> Noto Serif CJK SC -> Songti SC -> STSong -> Georgia

Japanese (best-effort)

• Uses CJK template path, no dedicated -ja templates yet
• JP Mincho-first stack: YuMincho -> Hiragino Mincho ProN -> Noto Serif CJK JP -> Source Han Serif JP -> TsangerJinKai02 -> serif
• Visually verify line breaks, punctuation rhythm, and emphasis weight before shipping

Korean (best-effort)

• Dedicated -ko templates use Source Han Serif K Regular / Medium, with the real OTF family name Source Han Serif KR kept in every fallback stack
• Fallback: Noto Serif KR / Apple SD Gothic Neo / AppleMyungjo / Charter / Georgia
• The OTFs are OFL-licensed and tracked for local preview / CDN fallback, but excluded from Claude Desktop skill ZIPs to keep the package small

English

• Single serif: Charter (system-bundled, macOS/iOS), used for both headlines and body
• No separate sans: --sans: var(--serif), one font per page
• Fallback: Georgia (cross-platform) / Palatino / Times New Roman

Font files next to HTML with relative @font-face paths is the most stable setup. scripts/package-skill.sh excludes large CJK font files from the Claude Desktop ZIP, so the uploaded package stays under the 6MB package ceiling. Always upload that package-skill.sh output, never a hand-zipped checkout (the tracked CJK fonts make it too large and Claude Desktop rejects the upload).

Font auto-recovery (Claude Desktop)

Before building Chinese or Korean documents, ensure fonts are present. The script tries multiple CDN sources with retry and size validation:

bash scripts/ensure-fonts.sh

It downloads to the XDG user font dir (${XDG_DATA_HOME:-~/.local/share}/fonts/kami, override with KAMI_FONT_DIR), not into the skill's assets/fonts -- that keeps the installed skill small so Claude Desktop never trips its size limit. fontconfig scans that dir by default, so WeasyPrint finds TsangerJinKai02 and Source Han Serif K there; online renders fall back to the jsDelivr @font-face URL. Run once before building. If all sources fail, the script prints per-language alternatives.

Feedback protocol

When the user gives vague visual feedback ("looks off", "太挤了", "not elegant"), do not guess. Ask back with current values:

Template response: "X is currently set to Y. Would you like (a) [specific alternative within spec] or (b) [another option]?"

Never say "I'll adjust the spacing" without naming the exact property and its new value.

---

When not to use this skill

• User explicitly wants Material / Fluent / Tailwind default - different design language
• Need dark / cyberpunk / futurist aesthetic (this is deliberately anti-future)
• Need saturated multi-color (this has one accent)
• Need cartoon / animation / illustration style (this is editorial)
• Web dynamic app UI (this is for print / static documents)

---

Next: apply Step 3's tier table to decide what to read, then copy the matching template and start filling.

Kami Agent Guide

Personal/global agent rules may live outside this repository. This file records Kami-specific repository maps, Working Rules, Current Risk Areas, Verification, Release Flow, and Fonts.

Project

Kami is a document-generation skill and template system. It ships editorial HTML templates, reference guides, demo assets, and a packaged skill archive.

Repository Map

• SKILL.md - skill routing and operating rules.
• CHEATSHEET.md - quick design reference.
• CLAUDE.md - Claude-specific notes pointing to AGENTS.md.
• references/ - design, writing, diagram, and production guidance.
• references/design.md, writing.md, production.md, diagrams.md - full specs.
• references/resume-writing.md - resume-specific bullet/project framing rules.
• references/anti-patterns.md - six-category checklist for reviewing drafts.
• references/mermaid.md - Mermaid diagram support: the two render paths (PDF vs browser) and the authoring pipeline.
• references/mermaid-theme.json - canonical Kami↔beautiful-mermaid color/font theme (kept in sync with tokens.json).
• references/tokens.json - canonical color tokens (drift-checked by scripts/tokens.py).
• references/checks_thresholds.json - rhythm / density / orphan check thresholds (loaded by scripts/checks.py).
• references/brand-profile.md and references/brand.example.md - optional brand profile behavior and public example.
• .claude-plugin/marketplace.json - Claude Code plugin marketplace metadata.
• .agents/plugins/marketplace.json - generated Codex repo marketplace. Points Codex at plugins/kami; never hand-edit.
• plugins/kami/ - generated Codex plugin tree. Mirrors the lightweight skill package under plugins/kami/skills/kami/; edit source files and run python3 scripts/build_metadata.py.
• assets/templates/ - document templates including browser-only landing page variants.
• scripts/highlight.py - Pygments-based syntax highlighting for code blocks at build time.
• assets/demos/ - README showcase demos.
• assets/showcase/ - README and public-site-only screenshots; excluded from dist/kami.zip.
• assets/diagrams/ - diagram prototypes and generated diagram assets; src/*.mmd records the Mermaid source of the sequence / class / er diagrams.
• scripts/mermaid_normalize.py - re-themes any beautiful-mermaid SVG to the Kami palette and makes it WeasyPrint-safe (resolves color-mix()/var() to static hex, rewrites fonts). Pure Python, no Node; ships in the package.
• assets/fonts/ and assets/illustrations/ - bundled visual assets.
• styles.css - shared web-facing styles.
• index.html, index-zh.html, index-en.html, index-ja.html, index-ko.html, index-tw.html - public site entrypoints.
• robots.txt, sitemap.xml, and vercel.json - public crawler, deployment, and AI visibility files.
• llms.txt - AI crawler and model-facing project summary.
• scripts/build.py - CLI shell: build targets and dispatch to lint / verify / checks / tokens modules.
• scripts/verify.py - end-to-end render verification (page count, embedded fonts, advisory density scan).
• scripts/lint.py - template CSS lint rules and base/variant cross-template :root consistency check (CN↔EN and CN↔KO).
• scripts/tokens.py - tokens.json drift check across HTML templates and PPTX slide scripts.
• scripts/checks.py - PDF-side checks: placeholders, orphans, density, slide-deck rhythm.
• scripts/optional_deps.py - centralized loader for weasyprint / pypdf / PyMuPDF with consistent install hints.
• scripts/shared.py - shared constants and the canonical HTML_TEMPLATES registry used by the build scripts.
• scripts/ensure-fonts.sh - verified font recovery helper (portable across bash 3.2+).
• scripts/package-skill.sh - package builder for the release archive.
• scripts/build_metadata.py - codegen for Codex marketplace metadata and plugin mirror files. Run after changing SKILL.md, CHEATSHEET.md, VERSION, references/, scripts/, or shipped lightweight assets.
• scripts/draft-release-notes.py - bilingual release notes scaffold from git log.
• scripts/tests/test_build.py - zero-dependency test suite for build and shared helpers.
• .github/workflows/check.yml - PR/push CI that runs --check and the test suite.
• .github/workflows/release.yml - tag-triggered workflow that builds and attaches dist/kami.zip to the release.
• dist/kami.zip - tracked release archive.

Reference docs are English-only. Language-specific output differences (CN/EN/KO) belong in templates, not duplicated reference files.

Commands

python3 scripts/build.py
python3 scripts/build.py --check
python3 scripts/build.py --verify
python3 scripts/build.py --check-placeholders path/to/filled.html
python3 scripts/build.py --check-orphans path/to/doc.pdf
python3 scripts/build.py --check-density path/to/doc.pdf
python3 scripts/build.py --check-rhythm slides slides-en
python3 scripts/build_metadata.py
python3 scripts/build_metadata.py --check
python3 scripts/tests/test_build.py
# Re-theme + WeasyPrint-safe a beautiful-mermaid SVG (no Node), then embed in a diagram shell:
python3 scripts/mermaid_normalize.py raw.svg -o clean.svg
python3 scripts/draft-release-notes.py V1.4.0..HEAD --version V1.4.1 --title "Steadier Hand"
bash scripts/ensure-fonts.sh
bash scripts/package-skill.sh

Working Rules

• Style changes must update references/design.md and the matching template tokens.
• Landing or documentation-site work follows references/design.md Section 11: «Documentation site» for the doc shell (sidebar rail, on-this-page TOC, borderless prev/next pager, build-time zero-JS code highlighting) and «Responsive screenshot verification» (screenshot at 375px / 1280px per locale, objective line-widow scan) before shipping.
• For hosted Kami site or public landing changes, first separate generic template work from Kami's own website. Generic behavior lives in assets/templates/landing-page* and references/; Kami site facts live across index*.html, styles.css, README, llms.txt, robots.txt, sitemap.xml, and vercel.json.
• Public facts are wider than the hero. Pricing, install path, version, release, support, analytics, FAQ, and positioning claims must move together across pages, metadata, AI files, and download links. Do not leave site-only analytics or tracking changes contradicting "no analytics" or app/package privacy copy.
• Content changes should avoid CSS churn unless layout behavior is part of the task.
• For document or template tasks, lock the output contract before editing: language, template, output format, page or length target, visual acceptance check, and verification command.
• Prefer the nearest existing template and deterministic verifier. Do not add a template, shared CSS layer, dependency, script flag, or optional mode unless the current request cannot be satisfied without it.
• New templates should copy the nearest existing template, stay aligned with references/design.md, and add demo coverage.
• Do not use graphic emoticons in docs, template comments, or script output.
• Use OK: and ERROR: for status text in scripts.
• Use scripts/ensure-fonts.sh to recover required fonts with retry and size validation when local font files are missing or truncated. It downloads to the XDG user font dir (${XDG_DATA_HOME:-~/.local/share}/fonts/kami), never into the skill's assets/fonts, so an installed Claude Desktop skill stays small; inside a repo checkout it is a no-op because the committed large fonts already satisfy the templates' relative path.
• Do not bundle large CJK font files into dist/kami.zip; package scripts should exclude them while templates keep stable local-preview paths. The skill ZIP uploaded to Claude Desktop must be the scripts/package-skill.sh output under the 6MB package ceiling; a hand-zipped checkout includes the tracked large fonts and Claude Desktop rejects it.
• Do not bundle README/public-site-only showcase screenshots into dist/kami.zip; keep them under assets/showcase/ and exclude that directory in scripts/package-skill.sh.
• Keep multilingual public pages, llms.txt, robots.txt, sitemap, JSON-LD, and FAQ content aligned when changing public positioning or install instructions.
• Brand profile support is optional context. Keep public examples in references/; do not hard-code a maintainer's private local profile content.
• Slides default to WeasyPrint HTML-to-PDF templates unless the user explicitly needs editable PPTX output.
• Templates intentionally inline their CSS rather than share a _kami.css partial: each template must remain a single self-contained HTML file so users can copy-paste it without a build step. When fixing CSS drift, apply the same change across affected templates rather than introducing a build-time include.
• All template registries live in scripts/shared.py: HTML_TEMPLATES (PDF docs), SCREEN_TEMPLATES (browser-only), and DIAGRAM_TEMPLATES (assets/diagrams). build.py derives its target dicts from them via build_targets() / screen_targets() / diagram_targets(). Update the registry, not the per-script dicts, when adding or removing a template or diagram.
• Mermaid diagrams: never embed raw beautiful-mermaid SVG into a PDF-bound template. WeasyPrint cannot resolve color-mix(), render <foreignObject>, or fetch a runtime web font, so always pipe through scripts/mermaid_normalize.py first (--check lint enforces this). It is pure Python, no Node bundled. xychart-beta is browser-only (it styles via <style> class selectors); use the hand-drawn chart diagrams for PDF. Full flow in references/mermaid.md.

Refactor And Packaging Hard Stops

• When refactoring scripts/build.py or package helpers into new modules, confirm every new helper file is tracked by Git. scripts/package-skill.sh packages from git ls-files, so untracked modules pass local imports but disappear from dist/kami.zip.
• Any source change that adds scripts, templates, reference JSON, workflows, or package inputs must refresh and inspect dist/kami.zip; package freshness is part of release readiness, not a later cleanup step.
• Changes to SKILL.md, templates, scripts, references, or package inputs must decide explicitly whether dist/kami.zip needs refresh. If the behavior is shipped through the skill package, rebuild and inspect the ZIP before handoff.
• Marketplace, plugin path, version, or generated mirror changes require runtime installation proof, not metadata proof only. For Codex changes, use an isolated CODEX_HOME=/tmp/... smoke with codex plugin marketplace add <path>, codex plugin add kami@kami, and codex plugin list; keep the generator, mirror tree, package audit, and install path aligned.
• If python3 scripts/build.py --verify fails only because the host Python lacks PPTX fallback dependencies such as python-pptx, verify slides and slides-en from a temporary venv instead of treating the environment miss as a source regression.
• Do not commit one-off review reports or diagnostic snapshots as durable docs. Extract stable rules into AGENTS.md, CLAUDE.md, SKILL.md, or references/ and discard the stale report.

CI And Verification Discipline

• Tests that need weasyprint / pypdf / PyMuPDF must run in a CI job that installs those deps (currently verify-render). The lint-and-test job ships only Pygments, so a find_spec(...) is not None skip-guard there silently skips the test while still printing OK:. A green lint-and-test does not mean the solver / render tests ran.
• Edits to .github/workflows/*.yml should be validated on a feature branch (push, watch the run go green) before merging to main. Local font / dependency / runner assumptions diverge from CI more often than expected: this project has already burned commits on pip cache requiring a manifest, the fallback_present set missing Ubuntu defaults (DejaVu / Liberation), and CI never having commercial fonts (Charter / TsangerJinKai02).
• Differences between CI and host behavior are expressed as a single explicit opt-in env var (KAMI_ALLOW_FALLBACK_ONLY=1 for missing primary fonts). When a third such flag is needed, migrate to references/verify_profile.json or a --ci-mode CLI flag instead of letting KAMI_* env vars sprawl.

Current Risk Areas

• WeasyPrint rendering is sensitive to font availability, solid hex tag backgrounds, page breaks, CJK fallback, and synthetic bold. Verify visually for template changes.
• Slide output has three paths: slides-weasy*.html for default PDF decks, slides*.py for editable PPTX fallback, and assets/templates/marp/slides-marp*.{md,css} for Markdown-first Marp decks.
• Marp theme CSS (assets/templates/marp/slides-marp.css and -en) inlines a full copy of the design tokens (--parchment, --brand, --serif, rhythm modules) because Marp themes must be self-contained. build.py --sync / --check now token-sync the marp/*.css files (tokens.py globs them), so token-value drift from references/design.md / tokens.json is caught, not silent. The remaining gap: the CSS lint and off-palette guard still scan only .html templates, so non-token CSS in the Marp themes (new rules, off-palette colors) is not lint-checked, review those by hand.
• AI/public visibility spans index*.html, llms.txt, robots.txt, sitemap.xml, FAQ JSON-LD, README install text, diagram counts, and release archive links.
• scripts/shared.py centralizes constants used by the build scripts; keep paths and target names in sync before adding templates or diagrams.
• dist/kami.zip is a tracked release archive. Packaging changes must update and inspect it deliberately.
• Codex plugin files are generated artifacts. Do not edit plugins/kami/ or .agents/plugins/marketplace.json directly; regenerate from the root source files and let python3 scripts/build_metadata.py --check catch drift.

Hotspot Ownership

• references/design.md and plugins/kami/skills/kami/references/design.md own the Kami visual system, including large landing-page and documentation-site rules. Boundary: edit only the root source, and use the plugin path only as a generated mirror. Verification: python3 scripts/build.py --check plus screenshots for screen surfaces, then python3 scripts/build_metadata.py --check.
• styles.css owns the hosted Kami public site shell, language switcher, gallery, and shared responsive behavior. Boundary: do not move generic template rules here. Verification: serve the site and screenshot 375px / 1280px per locale touched.
• assets/templates/landing-page.html, assets/templates/landing-page-en.html, assets/templates/landing-page-ko.html, plugins/kami/skills/kami/assets/templates/landing-page.html, plugins/kami/skills/kami/assets/templates/landing-page-en.html, and plugins/kami/skills/kami/assets/templates/landing-page-ko.html own the generic screen-first template shipped to users. Boundary: edit root templates, keep real product-site facts in filled sites, and treat plugin paths as generated mirrors. Verification: python3 scripts/build.py landing-page, browser screenshots for changed breakpoints, and python3 scripts/build_metadata.py --check.
• references/production.md and plugins/kami/skills/kami/references/production.md own production troubleshooting, pre-ship review, and known render pitfalls. Boundary: add stable invariants only, not dated review notes. Verification: python3 scripts/build.py --check, python3 scripts/build_metadata.py --check, and the relevant render command named by the rule.
• assets/templates/resume.html, assets/templates/resume-ko.html, plugins/kami/skills/kami/assets/templates/resume.html, and plugins/kami/skills/kami/assets/templates/resume-ko.html own high-density resume layout. Boundary: preserve the two-page contract and do not fix overflow by generic shrinking first. Verification: python3 scripts/build.py --verify resume and python3 scripts/build.py --verify resume-ko.
• assets/demos/demo-resume-ko.html owns the Korean resume demo content, not the template contract. Boundary: regenerate demo outputs when the demo changes, but put durable resume rules in templates or references. Verification: build the affected demo and confirm page count plus rendered screenshot.
• scripts/tests/test_build.py and plugins/kami/skills/kami/scripts/tests/test_build.py own the zero-dependency test suite. Boundary: edit the root test file and regenerate the plugin mirror. Verification: python3 scripts/tests/test_build.py and python3 scripts/build_metadata.py --check.

High-Risk Pitfalls

See references/production.md Part 4.

1. Tag rgba double rectangle: use solid hex backgrounds. 2. Thin border plus border-radius double ring: border < 1pt with border-radius can trigger it. 3. Resume 2-page overflow: tiny font, fallback, line-height, or margin changes can break it. 4. break-inside fails inside flex: wrap content in a block wrapper. 5. height: 100vh is unreliable under @page: use explicit mm values. 6. SVG marker orient="auto" does not rotate in WeasyPrint: draw arrowheads manually. 7. Section body text should not use max-width: .manifesto, .section-lede, and similar text should fill the .page container. Exceptions: .type-sample and .footer .colophon. 8. Diagram template changes must sync to index showcase SVGs: any visual fix to assets/diagrams/*.html must also be applied to the matching mini SVG in index.html, index-zh.html, index-ja.html, index-ko.html, index-tw.html.

Demo Screenshots

All demo PNG files use 1241x1754px (first A4 portrait page at 150dpi).

For one-page and multi-page documents (one-pager / letter / resume / portfolio / long-doc / equity-report), capture page 1:

pdftoppm -r 150 -f 1 -l 1 -png <pdf> /tmp/p && cp /tmp/p-1.png <target>.png

For landscape slides, capture the first 2 pages, resize each to 867px high, add a 20px gap, then extend to 1241px wide:

pdftoppm -r 150 -f 1 -l 2 -png <pdf> /tmp/sl
magick /tmp/sl-1.png -resize x867 /tmp/sl1.png
magick /tmp/sl-2.png -resize x867 /tmp/sl2.png
magick -size $(identify -format '%w' /tmp/sl1.png)x20 xc:'#f5f4ed' /tmp/gap.png
magick /tmp/sl1.png /tmp/gap.png /tmp/sl2.png -append /tmp/stacked.png
magick /tmp/stacked.png -gravity Center -background '#f5f4ed' -extent 1241x1754 <target>.png

Verification Details

• Expected page counts: one-pager 1, letter 1, resume 2 strict, long-doc 7 plus or minus 2, portfolio 6 plus or minus 2, slides 7 plus or minus 3, equity-report 2 to 3, changelog 1 to 2. Landing pages are browser-only HTML with no PDF page count.
• scripts/build.py sets PDF /Author from git config user.name or KAMI_AUTHOR only when the template still has an author placeholder. /Producer and /Creator should remain Kami.
• Demo PNGs under assets/demos/ are first-page previews at 1241x1754px. For slide demos, capture the first two landscape pages, stack them with a parchment gap, then extend to 1241x1754px.
• Diagram count and names must stay aligned across SKILL.md, CHEATSHEET.md, README.md, index*.html, and assets/diagrams/.

Verification

• Template, CSS, or script changes: run python3 scripts/build.py --check (CSS lint + token sync + base/variant cross-template :root consistency, currently CN↔EN and CN↔KO) and python3 scripts/build.py --verify.
• Demo changes: regenerate the affected demo outputs and confirm page counts stay in range.
• Font issues: run bash scripts/ensure-fonts.sh, then rebuild the affected target.
• Slide rhythm or deck changes: run python3 scripts/build.py --check-rhythm slides slides-en plus the affected render command.
• Public site or AI visibility changes: check index*.html, README, llms.txt, robots.txt, sitemap.xml, JSON-LD, FAQ, install links, and release/download links together. Serve the page and screenshot 375px / 1280px per locale, plus 320px when CTA width or mobile nav changes.
• Packaging changes: run bash scripts/package-skill.sh and confirm dist/kami.zip stays small enough for release upload. Inspect unzip -l dist/kami.zip for accidental large fonts, showcase screenshots, cache files, or missing new helper files.
• Codex marketplace changes: run python3 scripts/build_metadata.py --check and confirm plugins/kami/.codex-plugin/plugin.json plus .agents/plugins/marketplace.json stay generated. If install behavior, version selection, or source path changed, also run an isolated Codex install smoke.
• Documentation-only changes: check links and references.

Release Notes

• For public releases, keep notes concise and bilingual. Use one-to-one English and Chinese changelog items, 5 to 8 items, one sentence each.
• Generate the scaffold with python3 scripts/draft-release-notes.py V<prev>..V<new> --version V<new> --title "<Codename>", then regroup the raw commit list into 5 to 8 product-themed bullets and translate each to Chinese. Do not paste raw commit subjects.
• Match the established shape: title is V<x.y.z> <Two-Word Codename> (e.g. V1.7.2 Cleaner Resumes), body is the centered logo block + ### Changelog (English numbered list) + ### 更新日志 (Chinese numbered list) + the closing tagline line.

Release Flow

• bash scripts/package-skill.sh writes the tracked dist/kami.zip release archive and excludes large TsangerJinKai / Source Han Serif K font files plus README/public-site-only showcase screenshots.
• dist/kami.zip should be committed with release changes and uploaded to the latest GitHub release asset when refreshing the Claude Desktop package.
• When refreshing a GitHub release asset, download the uploaded kami.zip and compare ZIP entry names plus per-entry SHA-256 digests against local dist/kami.zip; do not rely on release-page text, file size, or container SHA alone.
• README and public site download links use https://github.com/tw93/kami/releases/latest/download/kami.zip; prefer refreshing that asset for small packaging or documentation fixes instead of creating a new tag.
• Create a new version tag only when the maintainer explicitly wants a versioned release. Tag the commit that already contains the final refreshed dist/kami.zip; do not tag a source-only commit and refresh the archive afterward.
• On tag push, .github/workflows/release.yml builds and attaches dist/kami.zip, creates the release if missing, and adds the house-style reactions (+1 eyes heart hooray laugh rocket, one each). Do not gh release create by hand; let CI create the placeholder, then set the real title and notes with gh release edit V<x> --title "V<x> <Codename>" --notes-file <file>.
• If reactions are ever missing (older release, CI skipped), add them manually: rid=$(gh api repos/tw93/Kami/releases/tags/V<x> --jq .id); for r in +1 eyes heart hooray laugh rocket; do gh api -X POST repos/tw93/Kami/releases/$rid/reactions -f content="$r"; done.

Fonts

• Chinese templates use TsangerJinKai02 W04/W05. Commercial use requires the appropriate font license.
• If TsangerJinKai is unavailable, fall back through Source Han Serif SC, Noto Serif CJK SC, Songti SC, STSong, then Georgia.
• English templates use Charter serif. Japanese output uses YuMincho first, then Hiragino Mincho ProN, Noto Serif CJK JP, Source Han Serif JP, TsangerJinKai02, and generic serif.
• Korean templates use Source Han Serif K (Adobe, also distributed as Noto Serif KR by Google). Fallback chain: Source Han Serif K, Source Han Serif KR, Noto Serif KR, Apple SD Gothic Neo, AppleMyungjo, Charter, Georgia. Source Han Serif KR is the actual family name inside the bundled OTFs and must stay in the chain so fontconfig can resolve the ensure-fonts.sh-downloaded font by name on an offline Linux skill install.
• Claude Desktop ZIPs do not bundle TsangerJinKai TTF or Source Han Serif K OTF files (the OTFs are OFL-licensed and git-tracked for the CDN @font-face fallback, but excluded from the package to keep it small). Run bash scripts/ensure-fonts.sh before building Chinese or Korean documents when fonts are missing; it drops them in the XDG user font dir (fontconfig-scanned, outside the skill), so the installed skill stays small and online renders still use the jsDelivr @font-face fallback.