{"owner":"tw93","repo":"Kami","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md","llms.txt"],"skills":{"AGENTS.md":"# Kami Agent Guide\n\n## Project\n\nKami is a document-generation skill and template system: self-contained editorial HTML\ntemplates rendered to PDF / PPTX / PNG, plus reference specs, demo assets, and a\npackaged skill archive. `SKILL.md` is the runtime manual for producing a document.\nThis file is the maintenance guide for changing the repository itself, and it records\nthe traps that a fresh read of the code does not reveal.\n\n## Repository Map\n\nOnly the entries whose role is not obvious from the filename:\n\n- `SKILL.md` - skill routing plus the document-side build and verify commands.\n  `CHEATSHEET.md` - quick design reference. Both ship inside the package.\n- `references/design.md`, `writing.md`, `production.md`, `diagrams.md` - full specs.\n  `production.md` Part 4 is the single source of truth for render failures, their\n  verified causes, and their fixes; add pitfalls there, not here.\n  `docs/release.md` - release notes, release flow, demo screenshot regeneration.\n  `anti-patterns.md`, `resume-writing.md`, `mermaid.md`, `deck-preflight.md`,\n  `brand-profile.md` and `brand.example.md` - scoped guides.\n- `references/tokens.json` (color tokens, drift-checked by `scripts/tokens.py`),\n  `references/mermaid-theme.json` (Kami to beautiful-mermaid theme, kept in sync with\n  `tokens.json`), `references/checks_thresholds.json` (rhythm / density / orphan /\n  visual thresholds read by `checks.py` and `visual.py`). These are live inputs to\n  gates: editing a number changes what passes.\n- `references/schemas/` - one JSON Schema subset per document type. The `$comment`\n  fields carry the per-field quality bar distilled from `writing.md`, so schema edits\n  and `writing.md` edits move together.\n- `scripts/shared.py` - the canonical registries (`HTML_TEMPLATES`,\n  `SCREEN_TEMPLATES`, `PPTX_TEMPLATES`, `MARP_TEMPLATES`, `DIAGRAM_TEMPLATES`) and each template's\n  `build_max_pages`. `build.py` derives its internal build targets from them;\n  Marp stays discovery-only because it uses an external CLI. Add or remove a\n  template or diagram here, never in a per-script dict.\n- `scripts/render.py` - the single render entry (`render_pdf`, `build_slides`, PDF\n  metadata stamping). `build.py`, `verify.py`, and `mcp_server.py` all call it; never\n  open a second WeasyPrint call site.\n- `scripts/mermaid_normalize.py` - re-themes a beautiful-mermaid SVG to the Kami\n  palette and makes it WeasyPrint-safe. Pure Python, no Node, ships in the package.\n- `scripts/mcp_server.py` - zero-dependency MCP stdio server exposing\n  `kami_templates` / `kami_doctor` / `kami_render` / `kami_check` /\n  `kami_screenshot`, so an MCP-capable agent can diagnose, render, and verify\n  without reading `SKILL.md`. Register\n  with `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`.\n- `scripts/site_facts.py` - public-site fact drift checks (install commands, version,\n  template and diagram counts across `index*.html`, `README.md`, `llms.txt`), wired\n  into `build.py --check`.\n- `scripts/check-update.sh` - quiet daily update check invoked from `SKILL.md`;\n  read-only VERSION compare, silent on any failure.\n- `assets/showcase/` - README and public-site screenshots only. `assets/demos/` -\n  README showcase demos. `scripts/package-skill.sh` excludes both from the ZIP.\n- `assets/diagrams/src/*.mmd` - Mermaid source of the sequence / class / er diagrams.\n  `assets/templates/marp/` - the Markdown-first Marp deck variant.\n- `dist/kami.zip` - **tracked** release archive, committed with release changes.\n- `plugins/kami/`, `.claude-plugin/marketplace.json`, and\n  `.agents/plugins/marketplace.json` are **generated**; see Generated Mirrors below.\n- Public site surface: `index.html` plus `index-zh|en|ja|ko|tw.html`, the English-only\n  prose pages `developers|about|contact|privacy.html`, `styles.css`, `llms.txt`,\n  `robots.txt`, `sitemap.xml`, `vercel.json`. `styles.css` is Kami's own site shell\n  (language switcher, gallery, responsive behavior, `.hero.doc` / `.prose` for the\n  prose pages); generic template rules never belong there.\n- Agent-facing site surface: `index.md` (Markdown twin of the homepage; `vercel.json`\n  *redirects* `/` here for `Accept: text/markdown` and `/?mode=agent`, because Vercel\n  applies `rewrites` only after the filesystem and `/` always matches `index.html`),\n  `developers|about|contact|privacy.md`, `developers/llms.txt`, and the generated\n  `.well-known/agent-skills/index.json`, `.well-known/mcp/server-card.json`,\n  `feeds/catalog.jsonld`, `schemamap.xml`. Every new prose page needs its `.md` twin,\n  a `rewrites` entry for the extensionless URL, and a `sitemap.xml` row.\n  The `has`-conditioned redirects and the `Link` headers are only observable on a\n  deploy: verify them with `curl -sI` against the preview URL, never locally.\n- `.github/workflows/check.yml` (PR/push CI) and `release.yml` (tag-triggered build\n  and asset upload).\n\nReference docs are English-first and never forked per language. Inline CJK examples\nare fine where the rule itself is about CJK typography (term annotation, punctuation,\nspacing); language-specific output differences (CN/EN/KO) live in templates, not in\nduplicated reference files.\n\n## Commands\n\n`python3 scripts/build.py --help` prints the authoritative flag list and the module\nmap. Read it instead of trusting any copy; hand-maintained lists here have gone stale\nbefore. The commands it does not cover:\n\n```bash\npython3 scripts/build_metadata.py            # regenerate plugin mirror + marketplace metadata\npython3 scripts/build_metadata.py --check    # drift check for the same\nbash scripts/package-skill.sh                # build the tracked dist/kami.zip\nbash scripts/ensure-fonts.sh                 # recover missing or truncated CJK fonts\npython3 scripts/mcp_server.py                # MCP stdio server (render / check / screenshot)\npython3 scripts/mermaid_normalize.py raw.svg -o clean.svg\npython3 scripts/draft-release-notes.py V1.4.0..HEAD --version V1.4.1 --title \"Steadier Hand\"\npython3 scripts/tests/test_build.py          # zero-dependency test suite\n```\n\n## Working Rules\n\n- Style changes must update `references/design.md` and the matching template tokens.\n- A CSS snippet in a reference doc is a shipped artifact, not prose: an agent copies\n  it before it reads a template. Every fenced `css` / `html` block is scanned by\n  `--check-docs` (inside `--check`) with the template rule set, and every `var()` it\n  names must resolve to a registered token or one a shipped template defines. Teach\n  from a component a template actually has; a recipe for assembling a new container\n  is how a document ends up carrying three unrelated emphasis languages. Tag a\n  deliberate counter-example inline with `/* avoid */` so the scan reads it as the\n  lesson rather than the violation.\n- A change touching template tokens, shared CSS gestures, or `references/design.md`\n  visual rules must rebuild the affected demo outputs (`assets/demos/*.pdf` / `*.png`)\n  in the same change, not as a later cleanup. Demos inline their CSS by copy, so they\n  silently keep the old style otherwise. Report the sweep: rebuilt N demos, K\n  unaffected. The off-palette guard in `scripts/lint.py` scans `assets/demos/*.html`\n  for stale hexes as a backstop, but it cannot see rendered PDFs or PNGs.\n- Templates intentionally inline their CSS rather than share a `_kami.css` partial:\n  each template must stay a single self-contained HTML file the user can copy-paste\n  with no build step. Fix CSS drift by applying the same change across the affected\n  templates, never by introducing a build-time include.\n- For document or template tasks, lock the output contract before editing: language,\n  template, output format, page or length target, visual acceptance check, and\n  verification command.\n- Prefer the nearest existing template and deterministic verifier. Do not add a\n  template, shared CSS layer, dependency, script flag, or optional mode unless the\n  current request cannot be satisfied without it. A new template copies the nearest\n  existing one, stays aligned with `references/design.md`, and adds demo coverage; a\n  new document type also needs a schema in `references/schemas/`.\n- Slides default to WeasyPrint HTML-to-PDF templates unless the user explicitly needs\n  editable PPTX output.\n- Mermaid diagrams: never embed raw beautiful-mermaid SVG into a PDF-bound template.\n  WeasyPrint cannot resolve `color-mix()`, render `<foreignObject>`, or fetch a\n  runtime web font, so always pipe through `scripts/mermaid_normalize.py` first\n  (`--check` enforces this). `xychart-beta` is browser-only because it styles through\n  `<style>` class selectors; use the hand-drawn chart diagrams for PDF. Full flow in\n  `references/mermaid.md`.\n- Do not use graphic emoticons in docs, template comments, or script output. Use `OK:`\n  and `ERROR:` for script status text.\n- Do not use em dashes (U+2014) in repository docs, generated documents, template\n  comments, or site copy; use colons, commas, periods, or parentheses. Self-check:\n  `grep -rn \"$(printf '\\342\\200\\224')\" README.md llms.txt index*.html`. Teaching\n  counter-examples inside `references/anti-patterns.md` are exempt; its rule #28\n  covers the generated-document side.\n- For hosted-site or public-landing work, separate generic template work from Kami's\n  own website first. Generic behavior lives in `assets/templates/landing-page*` and\n  `references/`; Kami site facts live across `index*.html`, `styles.css`, `README.md`,\n  `llms.txt`, `robots.txt`, `sitemap.xml`, and `vercel.json`. Public facts are wider\n  than the hero: pricing, install path, version, release, support, analytics, FAQ, and\n  positioning claims move together across pages, metadata, AI files, and download\n  links. Do not leave a site-only analytics or tracking change contradicting the\n  \"no analytics\" copy elsewhere.\n- Landing or documentation-site work follows `references/design.md` Section 11 «Landing\n  Page (screen-first)»: its «Documentation site» subsection for the doc shell (sidebar\n  rail, on-this-page TOC, borderless prev/next pager), then Section 12 «Responsive\n  screenshot verification» (screenshot at 375px / 1280px per locale, objective\n  line-widow scan) before shipping.\n- Content changes should avoid CSS churn unless layout behavior is part of the task.\n- Brand profile support is optional context. Keep public examples in `references/`; do\n  not hard-code a maintainer's private local profile.\n- Demo, reference-example, and handoff content distilled from a maintainer's private\n  documents (resume, business proposal, pricing, client names) must be de-identified\n  before it lands in the repo: swap in public figures, public projects, or invented\n  generic data. Job-search, quote, and engagement-period fields count as sensitive\n  even without names. List the swapped-out identifying signals in the handoff report;\n  do not rely on the maintainer to spot leftovers.\n- Do not commit one-off review reports or diagnostic snapshots as durable docs.\n  Extract the stable rule into `AGENTS.md`, `SKILL.md`, or `references/`, then discard\n  the report.\n\n## Generated Mirrors\n\n`plugins/kami/`, `.claude-plugin/marketplace.json`, and `.agents/plugins/marketplace.json`\nare generated from the root sources. Edit the root file only, treat every\n`plugins/kami/skills/kami/...` path as a mirror, and let\n`python3 scripts/build_metadata.py --check` catch drift. Regenerate after changing\n`SKILL.md`, `CHEATSHEET.md`, `VERSION`, `references/`, `scripts/`, or shipped\nlightweight assets.\n\nThe same generator owns the site's machine-readable discovery files:\n`.well-known/agent-skills/index.json` (carries a SHA-256 digest of `SKILL.md`, so any\nskill edit changes it), `.well-known/mcp/server-card.json` (version plus the tool list\nparsed out of `scripts/mcp_server.py` without importing it), `feeds/catalog.jsonld`\n(built from `HTML_TEMPLATES` / `DIAGRAM_TEMPLATES`), and `schemamap.xml`. Never\nhand-edit these four; change the source and regenerate.\n\nMarketplace, plugin path, version, or install-path changes need runtime installation\nproof, not metadata proof. Claude Code: an isolated `HOME=/tmp/...` smoke with\n`claude plugin marketplace add <path>`, `claude plugin install kami@kami`,\n`claude plugin details kami@kami`, confirming the installed cache is the lightweight\n`plugins/kami` tree. Codex: an isolated `CODEX_HOME=/tmp/...` smoke with\n`codex plugin marketplace add <path>`, `codex plugin add kami@kami`,\n`codex plugin list`.\n\n## Refactor And Packaging Hard Stops\n\n- The shipped archive must be the output of `bash scripts/package-skill.sh`: a\n  top-level `kami/` directory under a 6 MB ceiling. A hand-zipped checkout is\n  rejected on size.\n- `scripts/package-skill.sh` packages from `git ls-files`, so an untracked new module\n  passes every local import and silently disappears from `dist/kami.zip`. When\n  splitting `build.py` or a package helper into new modules, confirm each new file is\n  tracked by Git and added to the scripts allowlist in `package-skill.sh` (its\n  coverage gate fails the build otherwise).\n- Any source change to `SKILL.md`, scripts, templates, reference JSON, workflows, or\n  package inputs must refresh and inspect `dist/kami.zip`. Package freshness is release\n  readiness, not later cleanup. It is also the precondition for telling a reporter a fix\n  has shipped: a commit on `main` reaches `npx skills add` and plugin installs right\n  away, but Claude Desktop users download\n  `releases/latest/download/kami.zip`, so name the channel that actually carries the fix\n  and confirm that asset was refreshed before saying \"fixed, please update\".\n- If `python3 scripts/build.py --verify` fails only because the host Python lacks PPTX\n  fallback dependencies such as `python-pptx`, verify `slides` and `slides-en` from a\n  temporary venv instead of treating the environment miss as a source regression.\n- Resume templates (`assets/templates/resume.html`, `resume-ko.html`) carry a two-page\n  contract. Do not fix overflow by shrinking type or spacing globally first. Verify\n  with `python3 scripts/build.py --verify resume` and `--verify resume-ko`.\n- Demo files such as `assets/demos/demo-resume-ko.html` own demo content, not the\n  template contract. Durable rules go into templates or `references/`.\n\n## CI Gotchas\n\nApplies when editing `.github/workflows/*.yml` or adding a test with a heavy\ndependency.\n\n- `check.yml` has two jobs. `lint-and-test` runs dependency-light lint, metadata,\n  and package gates. `verify-render` installs `weasyprint` / `pypdf` / `PyMuPDF` /\n  `Pygments`, then runs the full test suite before template verification. Tests that\n  need an optional render dependency use the suite's explicit `SKIP:` counter and\n  fail when a CI-required dependency is unavailable; never turn a skip into `OK:`.\n- Validate workflow edits on a feature branch (push, watch the run go green) before\n  merging to `main`. Local font and dependency assumptions diverge from CI more often\n  than expected; this project has already burned commits on `pip` cache requiring a\n  manifest, the `fallback_present` set missing Ubuntu defaults (DejaVu / Liberation),\n  and CI never having commercial fonts (Charter / TsangerJinKai02).\n- Host-versus-CI differences are expressed as explicit opt-in env vars, currently\n  `KAMI_ALLOW_FALLBACK_ONLY` (accept fallback fonts), `KAMI_AUTHOR`, `KAMI_FONT_DIR`,\n  `KAMI_PACKAGE_ROOT_NAME`, `KAMI_PACKAGE_MAX_BYTES`, and `KAMI_UPDATE_URL`. That is\n  already the ceiling: before adding another, move the behavior into a `--ci-mode`\n  flag or a config file rather than letting `KAMI_*` sprawl.\n\n## Current Risk Areas\n\n- WeasyPrint rendering is sensitive to font availability, solid hex tag backgrounds,\n  page breaks, CJK fallback, and synthetic bold. Verify visually for template changes.\n- Slide output has three paths: `slides-weasy*.html` for default PDF decks,\n  `slides*.py` for the editable PPTX fallback, and\n  `assets/templates/marp/slides-marp*.{md,css}` for Markdown-first Marp decks.\n- Marp theme CSS inlines a full copy of the design tokens because Marp themes must be\n  self-contained. `build.py --sync` / `--check` token-sync those files and the CSS\n  lint rules scan them (both walk `shared.iter_template_files`), so token drift is\n  caught. The remaining hole: the off-palette hex guard globs `*.html` only\n  (`TEMPLATES/*.html` and `assets/demos/*.html`), so an off-palette color in Marp CSS\n  still needs eyeball review.\n- Page counts are a ceiling, never a floor. `build.py --verify` fails only when a PDF\n  exceeds `build_max_pages` in `scripts/shared.py` (one-pager 1, letter 1, resume 2,\n  changelog 2, equity-report 3; long-doc, portfolio, and slides-weasy are `0` =\n  unlimited). An undershooting document is never flagged, so \"this long-doc came out\n  at 3 pages\" is an authoring judgment call, not a gate failure. Landing pages are\n  browser-only HTML with no page count at all.\n- `scripts/render.py` sets PDF `/Author` from `git config user.name` or `KAMI_AUTHOR`\n  only when the template still holds an author placeholder. `/Producer` and `/Creator`\n  stay `Kami`.\n- Long-doc TOCs use WeasyPrint `target-counter()` and stable chapter ids for rendered\n  page numbers; do not reintroduce hand-written `.toc-page` spans. Running headers\n  default to `h1`. If a filled document does not use `h1` for chapter titles, add\n  `.running-title` to the element that should drive the header.\n- AI and public visibility spans `index*.html`, `llms.txt`, `robots.txt`,\n  `sitemap.xml`, FAQ JSON-LD, README install text, diagram counts, and release archive\n  links. Diagram count and names must stay aligned across `SKILL.md`, `CHEATSHEET.md`,\n  `README.md`, `index*.html`, and `assets/diagrams/`.\n\n## Critical Line-Break Scan\n\nApplies before handing off any user-visible typeset deliverable (rendered PDF,\n`README.md`, public site page).\n\n- Scan page by page for three critical wrap states: a trailing line of only 1-2 words\n  (orphan), a line one word away from wrapping, and a line that wraps early without\n  filling its container.\n- Split the work: `python3 scripts/build.py --check-orphans <pdf>` and\n  `--check-density <pdf>` catch PDF orphans and sparse pages deterministically; the\n  manual pass covers what they cannot see, near-wrap and premature-wrap states inside\n  a page, plus non-PDF surfaces (README, `index*.html` at 375px / 1280px).\n- One hit means a whole-document sweep for that class, not a single-spot fix. Fix by\n  adjusting content length first; changing font size or spacing to dodge a wrap is the\n  last resort and must re-pass `python3 scripts/build.py --check` and the page-count\n  contract.\n\n## Verification\n\n`SKILL.md` Step 5 owns the document-side commands (render, placeholders, markdown\nresidue, content IR, visual, rhythm, resume balance). This section covers the\nmaintenance side only.\n\n- Template or CSS changes: `python3 scripts/build.py --check` (CSS lint, token sync,\n  base/variant cross-template `:root` consistency, currently CN to EN and CN to KO)\n  plus `--verify` for the affected targets, or full `--verify` when the change is\n  cross-template.\n- Script changes: `python3 scripts/tests/test_build.py` and\n  `python3 scripts/build.py --check`. Run full `--verify` only when the render\n  pipeline itself changed (`render.py`, `verify.py`, WeasyPrint handling).\n- Font-stack changes (any `--serif` / `--mono` / SVG `text` chain): rebuild the\n  examples, then `python3 scripts/build.py --check-fonts assets/examples/*.pdf`. The\n  page-count contract cannot see which family actually drew the text, and a wrong one\n  renders cleanly; this is how the diagram labels were found splitting mid-word across\n  two faces.\n- Demo changes: regenerate the affected demo outputs and confirm page counts stay in\n  range. Font issues: `bash scripts/ensure-fonts.sh`, then rebuild the target.\n- MCP server changes: smoke the stdio protocol end to end (initialize, tools/list, one\n  tools/call per changed tool) through a scripted stdin session, and check that output\n  stays newline-delimited JSON with no stray prints on stdout.\n- Packaging changes: `bash scripts/package-skill.sh`, then `unzip -l dist/kami.zip` to\n  inspect for accidental large fonts, showcase screenshots, cache files, or a missing\n  new helper.\n- Marketplace or plugin changes: `python3 scripts/build_metadata.py --check` plus the\n  isolated install smoke described under Generated Mirrors.\n- Public site or AI visibility changes: check `index*.html`, README, `llms.txt`,\n  `robots.txt`, `sitemap.xml`, JSON-LD, FAQ, install links, and download links\n  together, then serve the page and screenshot 375px / 1280px per locale, plus 320px\n  when CTA width or mobile nav changes.\n\n## Fonts\n\n`references/production.md` Part 1 «Fonts» owns the full stack: per-language family\nchains, fallbacks, `@font-face` paths, and the recovery flow. Two facts that must not\ndrift out of it:\n\n- `Source Han Serif KR` is the real family name inside the bundled OTFs and must stay\n  in every Korean fallback chain, otherwise fontconfig cannot resolve the\n  `ensure-fonts.sh`-downloaded font by name on an offline Linux skill install.\n- CJK families lead every stack that CJK text can reach, Latin faces trail. A leading\n  Latin serif ends the stack walk for characters it lacks, which sends each ideograph\n  to fontconfig separately and splits words across two faces inside inline SVG\n  (`production.md` pitfall #4.1). The `-en` templates are the deliberate exception:\n  they are Latin documents, so `Charter` stays first there.\n- The commercial TsangerJinKai02 files never ship inside the skill package, so a\n  sandboxed install has no primary CJK serif and falls through the chain. Keep the\n  chain wide (Source Han Serif SC and CN, Noto Serif CJK SC and Noto Serif SC, Songti\n  SC, STSong, SimSun) so it lands on some serif rather than a system sans.\n- `bash scripts/ensure-fonts.sh` downloads into the XDG user font dir\n  (`${XDG_DATA_HOME:-~/.local/share}/fonts/kami`, override with `KAMI_FONT_DIR`),\n  never into the skill's `assets/fonts`, so an installed Claude Desktop skill stays\n  small. Inside a repo checkout it is a no-op because the committed fonts already\n  satisfy the templates' relative paths. Commercial use of TsangerJinKai02 requires\n  the appropriate license.\n\n## Releasing\n\n`docs/release.md` owns release notes format, the tag and asset flow, and demo\nscreenshot regeneration commands. Read it when cutting or refreshing a release.\n","CLAUDE.md":"# Kami\n\nDocument-generation skill and template system. Editorial HTML templates plus a PDF / PPTX / PNG build pipeline.\n\n## Where things live\n\n- **`AGENTS.md` owns every repository maintenance rule**: repo map, working rules, generated mirrors, packaging hard stops, CI gotchas, risk areas, verification, fonts. This file does not restate them. The Claude-specific section below is the only overlap, and it exists because those steps are Claude-side workflow rather than repository policy.\n- Producing a document: `SKILL.md` is the runbook. Template design spec: `references/design.md`. Writing spec: `references/writing.md`. Draft review checklist: `references/anti-patterns.md`. Render troubleshooting: `references/production.md` Part 4. Release flow: `docs/release.md`.\n- `python3 scripts/build.py --help` is the authoritative command list. Do not trust a hand-written copy; the Commands section in `AGENTS.md` covers only the scripts `--help` cannot reach.\n\n## Claude-specific\n\n- This repo ships plugins for both Claude Code and Codex. `plugins/kami/` and `.claude-plugin/marketplace.json` are generated: after editing a root file, run `python3 scripts/build_metadata.py --check`.\n- The Claude Desktop skill package must be the output of `bash scripts/package-skill.sh` (top-level `kami/` directory, 6 MB ceiling). A hand-zipped checkout is rejected on size.\n- To let Claude drive rendering and verification directly: `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`.\n- Plugin install changes need an isolated smoke run: under `HOME=/tmp/...`, `claude plugin marketplace add <path>` then `claude plugin install kami@kami`. Reading metadata is not verification.\n","llms.txt":"# Kami\n\n> A warm parchment design system for AI-assisted professional documents. One accent color, serif-led hierarchy, and editorial whitespace.\n\n## Author\n- Name: Tw93\n- Site: https://tw93.fun\n\n## What is Kami\nKami is a layout design system for the AI era. Give Claude (or any LLM) a brief, and it produces polished documents: one-pagers, resumes, portfolios, slides, long docs, letters, equity reports, and changelogs. The system uses a warm parchment canvas (#f5f4ed), ink-blue accent (#1B365D), and Charter/TsangerJinKai serif fonts. Parchment is the default canvas; an opt-in white-paper variant renders any document on a white background for home or office printers while keeping the warmth in cards and tables.\n\nKami installs into the agent that uses it and runs on that machine. There is no hosted Kami API, no account, and no API key: the integration surface is a local MCP server, JSON content schemas, and CLI checks.\n\n## When to use Kami\nReach for Kami when the user wants a finished document whose appearance matters, and a plain text answer would not be enough:\n- \"Make me a resume / CV\" -> `resume`\n- \"Turn this into a one-pager, product brief, or intro sheet\" -> `one-pager`\n- \"Write a formal letter, offer, or notice\" -> `letter`\n- \"Build a slide deck for this talk\" -> `slides` (PDF, or editable PPTX)\n- \"Write this research, spec, or report up as a document\" -> `long-doc`\n- \"Show my work, case studies, or portfolio\" -> `portfolio`\n- \"Analyze this company or stock and produce a report\" -> `equity-report`\n- \"Write release notes for this version\" -> `changelog`\n- \"Draw an architecture diagram, flowchart, timeline, or chart to embed\" -> one of 18 inline SVG diagram types\n- \"Build a landing page in this style\" -> browser-only `landing-page` template\n\nDo not reach for Kami for chat answers, code files, or content where the user only wants the text. Kami's cost is layout work; it pays off when the artifact is handed to someone else.\n\nHow an agent should call Kami: install the skill, fill the matching content schema, fill the template HTML, then verify with `python3 scripts/build.py --check-content content.json filled.html` and `--check-visual`, or drive the same steps as tools through the local MCP server. Judgment lives in SKILL.md; execution lives in the scripts.\n\n## Key Pages\n- [English showcase](https://kami.tw93.fun): Design system overview with live demos\n- [Developers](https://kami.tw93.fun/developers): Agent and developer integration surface\n- [About](https://kami.tw93.fun/about): What Kami is and who maintains it\n- [Contact](https://kami.tw93.fun/contact): Support and reporting channels\n- [Privacy](https://kami.tw93.fun/privacy): What this site and the skill collect\n- [Chinese showcase](https://kami.tw93.fun/index-zh.html): Chinese version\n- [Japanese showcase](https://kami.tw93.fun/index-ja.html): Japanese version (best-effort CJK path)\n- [Korean showcase](https://kami.tw93.fun/index-ko.html): Korean version (best-effort CJK path)\n- [Traditional Chinese showcase](https://kami.tw93.fun/index-tw.html): Traditional Chinese version\n- [GitHub](https://github.com/tw93/kami): Source code and templates\n\n## Install\n- Claude Code (v2.1.142+): `/plugin marketplace add tw93/kami && /plugin install kami@kami`\n- Codex plugin marketplace: `codex plugin marketplace add tw93/kami && codex plugin add kami@kami`\n- Generic agents (`~/.agents`): `npx skills add tw93/kami/plugins/kami -a universal -g -y`\n- Claude Desktop: download the release asset `kami.zip` from GitHub Releases (not the source-code ZIP) and upload it in Skills settings\n- MCP client: `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`\n\n## Templates\n- 8 document template types: One-pager, Letter, Resume, Long document, Portfolio, Slides, Equity report, Changelog\n- 18 diagram types: architecture, architecture board, flowchart, quadrant, bar chart, line chart, donut chart, state machine, timeline, swimlane, tree, layer stack, venn, candlestick, waterfall, sequence, class, ER\n\n## Agent Interfaces\n- Content contracts: `references/schemas/<type>.json` carries the per-type structure and quality bar; new `content.json` files also carry an artifact `brief` with target, preserve boundary, evidence, and acceptance checks; validate before layout and check coverage after filling with `python3 scripts/build.py --check-content content.json [filled.html]`\n- Deterministic checks: placeholders, markdown residue, page density, orphan lines, slide rhythm, and a perceptual pass that exports page images with a fixed review checklist (`--check-visual`)\n- MCP server: `python3 scripts/mcp_server.py` speaks MCP over stdio with tools kami_templates / kami_doctor / kami_render / kami_check / kami_screenshot, so agents can diagnose, render, and verify without loading the skill prompt\n\n## Machine-Readable Files\n- MCP server card: https://kami.tw93.fun/.well-known/mcp/server-card.json\n- Agent Skills index: https://kami.tw93.fun/.well-known/agent-skills/index.json\n- Skill definition: https://kami.tw93.fun/SKILL.md\n- Homepage as Markdown: https://kami.tw93.fun/index.md (a request to `/` carrying `Accept: text/markdown`, or `/?mode=agent`, redirects here)\n- Developer surface: https://kami.tw93.fun/developers.md and https://kami.tw93.fun/developers/llms.txt\n- Template and diagram catalog: https://kami.tw93.fun/feeds/catalog.jsonld (indexed by https://kami.tw93.fun/schemamap.xml)\n\n## Links\n- GitHub: https://github.com/tw93\n- Blog: https://tw93.fun\n- AI Profile: https://tw93.fun/llms-full.txt\n"},"files":{"AGENTS.md":"# Kami Agent Guide\n\n## Project\n\nKami is a document-generation skill and template system: self-contained editorial HTML\ntemplates rendered to PDF / PPTX / PNG, plus reference specs, demo assets, and a\npackaged skill archive. `SKILL.md` is the runtime manual for producing a document.\nThis file is the maintenance guide for changing the repository itself, and it records\nthe traps that a fresh read of the code does not reveal.\n\n## Repository Map\n\nOnly the entries whose role is not obvious from the filename:\n\n- `SKILL.md` - skill routing plus the document-side build and verify commands.\n  `CHEATSHEET.md` - quick design reference. Both ship inside the package.\n- `references/design.md`, `writing.md`, `production.md`, `diagrams.md` - full specs.\n  `production.md` Part 4 is the single source of truth for render failures, their\n  verified causes, and their fixes; add pitfalls there, not here.\n  `docs/release.md` - release notes, release flow, demo screenshot regeneration.\n  `anti-patterns.md`, `resume-writing.md`, `mermaid.md`, `deck-preflight.md`,\n  `brand-profile.md` and `brand.example.md` - scoped guides.\n- `references/tokens.json` (color tokens, drift-checked by `scripts/tokens.py`),\n  `references/mermaid-theme.json` (Kami to beautiful-mermaid theme, kept in sync with\n  `tokens.json`), `references/checks_thresholds.json` (rhythm / density / orphan /\n  visual thresholds read by `checks.py` and `visual.py`). These are live inputs to\n  gates: editing a number changes what passes.\n- `references/schemas/` - one JSON Schema subset per document type. The `$comment`\n  fields carry the per-field quality bar distilled from `writing.md`, so schema edits\n  and `writing.md` edits move together.\n- `scripts/shared.py` - the canonical registries (`HTML_TEMPLATES`,\n  `SCREEN_TEMPLATES`, `PPTX_TEMPLATES`, `MARP_TEMPLATES`, `DIAGRAM_TEMPLATES`) and each template's\n  `build_max_pages`. `build.py` derives its internal build targets from them;\n  Marp stays discovery-only because it uses an external CLI. Add or remove a\n  template or diagram here, never in a per-script dict.\n- `scripts/render.py` - the single render entry (`render_pdf`, `build_slides`, PDF\n  metadata stamping). `build.py`, `verify.py`, and `mcp_server.py` all call it; never\n  open a second WeasyPrint call site.\n- `scripts/mermaid_normalize.py` - re-themes a beautiful-mermaid SVG to the Kami\n  palette and makes it WeasyPrint-safe. Pure Python, no Node, ships in the package.\n- `scripts/mcp_server.py` - zero-dependency MCP stdio server exposing\n  `kami_templates` / `kami_doctor` / `kami_render` / `kami_check` /\n  `kami_screenshot`, so an MCP-capable agent can diagnose, render, and verify\n  without reading `SKILL.md`. Register\n  with `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`.\n- `scripts/site_facts.py` - public-site fact drift checks (install commands, version,\n  template and diagram counts across `index*.html`, `README.md`, `llms.txt`), wired\n  into `build.py --check`.\n- `scripts/check-update.sh` - quiet daily update check invoked from `SKILL.md`;\n  read-only VERSION compare, silent on any failure.\n- `assets/showcase/` - README and public-site screenshots only. `assets/demos/` -\n  README showcase demos. `scripts/package-skill.sh` excludes both from the ZIP.\n- `assets/diagrams/src/*.mmd` - Mermaid source of the sequence / class / er diagrams.\n  `assets/templates/marp/` - the Markdown-first Marp deck variant.\n- `dist/kami.zip` - **tracked** release archive, committed with release changes.\n- `plugins/kami/`, `.claude-plugin/marketplace.json`, and\n  `.agents/plugins/marketplace.json` are **generated**; see Generated Mirrors below.\n- Public site surface: `index.html` plus `index-zh|en|ja|ko|tw.html`, the English-only\n  prose pages `developers|about|contact|privacy.html`, `styles.css`, `llms.txt`,\n  `robots.txt`, `sitemap.xml`, `vercel.json`. `styles.css` is Kami's own site shell\n  (language switcher, gallery, responsive behavior, `.hero.doc` / `.prose` for the\n  prose pages); generic template rules never belong there.\n- Agent-facing site surface: `index.md` (Markdown twin of the homepage; `vercel.json`\n  *redirects* `/` here for `Accept: text/markdown` and `/?mode=agent`, because Vercel\n  applies `rewrites` only after the filesystem and `/` always matches `index.html`),\n  `developers|about|contact|privacy.md`, `developers/llms.txt`, and the generated\n  `.well-known/agent-skills/index.json`, `.well-known/mcp/server-card.json`,\n  `feeds/catalog.jsonld`, `schemamap.xml`. Every new prose page needs its `.md` twin,\n  a `rewrites` entry for the extensionless URL, and a `sitemap.xml` row.\n  The `has`-conditioned redirects and the `Link` headers are only observable on a\n  deploy: verify them with `curl -sI` against the preview URL, never locally.\n- `.github/workflows/check.yml` (PR/push CI) and `release.yml` (tag-triggered build\n  and asset upload).\n\nReference docs are English-first and never forked per language. Inline CJK examples\nare fine where the rule itself is about CJK typography (term annotation, punctuation,\nspacing); language-specific output differences (CN/EN/KO) live in templates, not in\nduplicated reference files.\n\n## Commands\n\n`python3 scripts/build.py --help` prints the authoritative flag list and the module\nmap. Read it instead of trusting any copy; hand-maintained lists here have gone stale\nbefore. The commands it does not cover:\n\n```bash\npython3 scripts/build_metadata.py            # regenerate plugin mirror + marketplace metadata\npython3 scripts/build_metadata.py --check    # drift check for the same\nbash scripts/package-skill.sh                # build the tracked dist/kami.zip\nbash scripts/ensure-fonts.sh                 # recover missing or truncated CJK fonts\npython3 scripts/mcp_server.py                # MCP stdio server (render / check / screenshot)\npython3 scripts/mermaid_normalize.py raw.svg -o clean.svg\npython3 scripts/draft-release-notes.py V1.4.0..HEAD --version V1.4.1 --title \"Steadier Hand\"\npython3 scripts/tests/test_build.py          # zero-dependency test suite\n```\n\n## Working Rules\n\n- Style changes must update `references/design.md` and the matching template tokens.\n- A CSS snippet in a reference doc is a shipped artifact, not prose: an agent copies\n  it before it reads a template. Every fenced `css` / `html` block is scanned by\n  `--check-docs` (inside `--check`) with the template rule set, and every `var()` it\n  names must resolve to a registered token or one a shipped template defines. Teach\n  from a component a template actually has; a recipe for assembling a new container\n  is how a document ends up carrying three unrelated emphasis languages. Tag a\n  deliberate counter-example inline with `/* avoid */` so the scan reads it as the\n  lesson rather than the violation.\n- A change touching template tokens, shared CSS gestures, or `references/design.md`\n  visual rules must rebuild the affected demo outputs (`assets/demos/*.pdf` / `*.png`)\n  in the same change, not as a later cleanup. Demos inline their CSS by copy, so they\n  silently keep the old style otherwise. Report the sweep: rebuilt N demos, K\n  unaffected. The off-palette guard in `scripts/lint.py` scans `assets/demos/*.html`\n  for stale hexes as a backstop, but it cannot see rendered PDFs or PNGs.\n- Templates intentionally inline their CSS rather than share a `_kami.css` partial:\n  each template must stay a single self-contained HTML file the user can copy-paste\n  with no build step. Fix CSS drift by applying the same change across the affected\n  templates, never by introducing a build-time include.\n- For document or template tasks, lock the output contract before editing: language,\n  template, output format, page or length target, visual acceptance check, and\n  verification command.\n- Prefer the nearest existing template and deterministic verifier. Do not add a\n  template, shared CSS layer, dependency, script flag, or optional mode unless the\n  current request cannot be satisfied without it. A new template copies the nearest\n  existing one, stays aligned with `references/design.md`, and adds demo coverage; a\n  new document type also needs a schema in `references/schemas/`.\n- Slides default to WeasyPrint HTML-to-PDF templates unless the user explicitly needs\n  editable PPTX output.\n- Mermaid diagrams: never embed raw beautiful-mermaid SVG into a PDF-bound template.\n  WeasyPrint cannot resolve `color-mix()`, render `<foreignObject>`, or fetch a\n  runtime web font, so always pipe through `scripts/mermaid_normalize.py` first\n  (`--check` enforces this). `xychart-beta` is browser-only because it styles through\n  `<style>` class selectors; use the hand-drawn chart diagrams for PDF. Full flow in\n  `references/mermaid.md`.\n- Do not use graphic emoticons in docs, template comments, or script output. Use `OK:`\n  and `ERROR:` for script status text.\n- Do not use em dashes (U+2014) in repository docs, generated documents, template\n  comments, or site copy; use colons, commas, periods, or parentheses. Self-check:\n  `grep -rn \"$(printf '\\342\\200\\224')\" README.md llms.txt index*.html`. Teaching\n  counter-examples inside `references/anti-patterns.md` are exempt; its rule #28\n  covers the generated-document side.\n- For hosted-site or public-landing work, separate generic template work from Kami's\n  own website first. Generic behavior lives in `assets/templates/landing-page*` and\n  `references/`; Kami site facts live across `index*.html`, `styles.css`, `README.md`,\n  `llms.txt`, `robots.txt`, `sitemap.xml`, and `vercel.json`. Public facts are wider\n  than the hero: pricing, install path, version, release, support, analytics, FAQ, and\n  positioning claims move together across pages, metadata, AI files, and download\n  links. Do not leave a site-only analytics or tracking change contradicting the\n  \"no analytics\" copy elsewhere.\n- Landing or documentation-site work follows `references/design.md` Section 11 «Landing\n  Page (screen-first)»: its «Documentation site» subsection for the doc shell (sidebar\n  rail, on-this-page TOC, borderless prev/next pager), then Section 12 «Responsive\n  screenshot verification» (screenshot at 375px / 1280px per locale, objective\n  line-widow scan) before shipping.\n- Content changes should avoid CSS churn unless layout behavior is part of the task.\n- Brand profile support is optional context. Keep public examples in `references/`; do\n  not hard-code a maintainer's private local profile.\n- Demo, reference-example, and handoff content distilled from a maintainer's private\n  documents (resume, business proposal, pricing, client names) must be de-identified\n  before it lands in the repo: swap in public figures, public projects, or invented\n  generic data. Job-search, quote, and engagement-period fields count as sensitive\n  even without names. List the swapped-out identifying signals in the handoff report;\n  do not rely on the maintainer to spot leftovers.\n- Do not commit one-off review reports or diagnostic snapshots as durable docs.\n  Extract the stable rule into `AGENTS.md`, `SKILL.md`, or `references/`, then discard\n  the report.\n\n## Generated Mirrors\n\n`plugins/kami/`, `.claude-plugin/marketplace.json`, and `.agents/plugins/marketplace.json`\nare generated from the root sources. Edit the root file only, treat every\n`plugins/kami/skills/kami/...` path as a mirror, and let\n`python3 scripts/build_metadata.py --check` catch drift. Regenerate after changing\n`SKILL.md`, `CHEATSHEET.md`, `VERSION`, `references/`, `scripts/`, or shipped\nlightweight assets.\n\nThe same generator owns the site's machine-readable discovery files:\n`.well-known/agent-skills/index.json` (carries a SHA-256 digest of `SKILL.md`, so any\nskill edit changes it), `.well-known/mcp/server-card.json` (version plus the tool list\nparsed out of `scripts/mcp_server.py` without importing it), `feeds/catalog.jsonld`\n(built from `HTML_TEMPLATES` / `DIAGRAM_TEMPLATES`), and `schemamap.xml`. Never\nhand-edit these four; change the source and regenerate.\n\nMarketplace, plugin path, version, or install-path changes need runtime installation\nproof, not metadata proof. Claude Code: an isolated `HOME=/tmp/...` smoke with\n`claude plugin marketplace add <path>`, `claude plugin install kami@kami`,\n`claude plugin details kami@kami`, confirming the installed cache is the lightweight\n`plugins/kami` tree. Codex: an isolated `CODEX_HOME=/tmp/...` smoke with\n`codex plugin marketplace add <path>`, `codex plugin add kami@kami`,\n`codex plugin list`.\n\n## Refactor And Packaging Hard Stops\n\n- The shipped archive must be the output of `bash scripts/package-skill.sh`: a\n  top-level `kami/` directory under a 6 MB ceiling. A hand-zipped checkout is\n  rejected on size.\n- `scripts/package-skill.sh` packages from `git ls-files`, so an untracked new module\n  passes every local import and silently disappears from `dist/kami.zip`. When\n  splitting `build.py` or a package helper into new modules, confirm each new file is\n  tracked by Git and added to the scripts allowlist in `package-skill.sh` (its\n  coverage gate fails the build otherwise).\n- Any source change to `SKILL.md`, scripts, templates, reference JSON, workflows, or\n  package inputs must refresh and inspect `dist/kami.zip`. Package freshness is release\n  readiness, not later cleanup. It is also the precondition for telling a reporter a fix\n  has shipped: a commit on `main` reaches `npx skills add` and plugin installs right\n  away, but Claude Desktop users download\n  `releases/latest/download/kami.zip`, so name the channel that actually carries the fix\n  and confirm that asset was refreshed before saying \"fixed, please update\".\n- If `python3 scripts/build.py --verify` fails only because the host Python lacks PPTX\n  fallback dependencies such as `python-pptx`, verify `slides` and `slides-en` from a\n  temporary venv instead of treating the environment miss as a source regression.\n- Resume templates (`assets/templates/resume.html`, `resume-ko.html`) carry a two-page\n  contract. Do not fix overflow by shrinking type or spacing globally first. Verify\n  with `python3 scripts/build.py --verify resume` and `--verify resume-ko`.\n- Demo files such as `assets/demos/demo-resume-ko.html` own demo content, not the\n  template contract. Durable rules go into templates or `references/`.\n\n## CI Gotchas\n\nApplies when editing `.github/workflows/*.yml` or adding a test with a heavy\ndependency.\n\n- `check.yml` has two jobs. `lint-and-test` runs dependency-light lint, metadata,\n  and package gates. `verify-render` installs `weasyprint` / `pypdf` / `PyMuPDF` /\n  `Pygments`, then runs the full test suite before template verification. Tests that\n  need an optional render dependency use the suite's explicit `SKIP:` counter and\n  fail when a CI-required dependency is unavailable; never turn a skip into `OK:`.\n- Validate workflow edits on a feature branch (push, watch the run go green) before\n  merging to `main`. Local font and dependency assumptions diverge from CI more often\n  than expected; this project has already burned commits on `pip` cache requiring a\n  manifest, the `fallback_present` set missing Ubuntu defaults (DejaVu / Liberation),\n  and CI never having commercial fonts (Charter / TsangerJinKai02).\n- Host-versus-CI differences are expressed as explicit opt-in env vars, currently\n  `KAMI_ALLOW_FALLBACK_ONLY` (accept fallback fonts), `KAMI_AUTHOR`, `KAMI_FONT_DIR`,\n  `KAMI_PACKAGE_ROOT_NAME`, `KAMI_PACKAGE_MAX_BYTES`, and `KAMI_UPDATE_URL`. That is\n  already the ceiling: before adding another, move the behavior into a `--ci-mode`\n  flag or a config file rather than letting `KAMI_*` sprawl.\n\n## Current Risk Areas\n\n- WeasyPrint rendering is sensitive to font availability, solid hex tag backgrounds,\n  page breaks, CJK fallback, and synthetic bold. Verify visually for template changes.\n- Slide output has three paths: `slides-weasy*.html` for default PDF decks,\n  `slides*.py` for the editable PPTX fallback, and\n  `assets/templates/marp/slides-marp*.{md,css}` for Markdown-first Marp decks.\n- Marp theme CSS inlines a full copy of the design tokens because Marp themes must be\n  self-contained. `build.py --sync` / `--check` token-sync those files and the CSS\n  lint rules scan them (both walk `shared.iter_template_files`), so token drift is\n  caught. The remaining hole: the off-palette hex guard globs `*.html` only\n  (`TEMPLATES/*.html` and `assets/demos/*.html`), so an off-palette color in Marp CSS\n  still needs eyeball review.\n- Page counts are a ceiling, never a floor. `build.py --verify` fails only when a PDF\n  exceeds `build_max_pages` in `scripts/shared.py` (one-pager 1, letter 1, resume 2,\n  changelog 2, equity-report 3; long-doc, portfolio, and slides-weasy are `0` =\n  unlimited). An undershooting document is never flagged, so \"this long-doc came out\n  at 3 pages\" is an authoring judgment call, not a gate failure. Landing pages are\n  browser-only HTML with no page count at all.\n- `scripts/render.py` sets PDF `/Author` from `git config user.name` or `KAMI_AUTHOR`\n  only when the template still holds an author placeholder. `/Producer` and `/Creator`\n  stay `Kami`.\n- Long-doc TOCs use WeasyPrint `target-counter()` and stable chapter ids for rendered\n  page numbers; do not reintroduce hand-written `.toc-page` spans. Running headers\n  default to `h1`. If a filled document does not use `h1` for chapter titles, add\n  `.running-title` to the element that should drive the header.\n- AI and public visibility spans `index*.html`, `llms.txt`, `robots.txt`,\n  `sitemap.xml`, FAQ JSON-LD, README install text, diagram counts, and release archive\n  links. Diagram count and names must stay aligned across `SKILL.md`, `CHEATSHEET.md`,\n  `README.md`, `index*.html`, and `assets/diagrams/`.\n\n## Critical Line-Break Scan\n\nApplies before handing off any user-visible typeset deliverable (rendered PDF,\n`README.md`, public site page).\n\n- Scan page by page for three critical wrap states: a trailing line of only 1-2 words\n  (orphan), a line one word away from wrapping, and a line that wraps early without\n  filling its container.\n- Split the work: `python3 scripts/build.py --check-orphans <pdf>` and\n  `--check-density <pdf>` catch PDF orphans and sparse pages deterministically; the\n  manual pass covers what they cannot see, near-wrap and premature-wrap states inside\n  a page, plus non-PDF surfaces (README, `index*.html` at 375px / 1280px).\n- One hit means a whole-document sweep for that class, not a single-spot fix. Fix by\n  adjusting content length first; changing font size or spacing to dodge a wrap is the\n  last resort and must re-pass `python3 scripts/build.py --check` and the page-count\n  contract.\n\n## Verification\n\n`SKILL.md` Step 5 owns the document-side commands (render, placeholders, markdown\nresidue, content IR, visual, rhythm, resume balance). This section covers the\nmaintenance side only.\n\n- Template or CSS changes: `python3 scripts/build.py --check` (CSS lint, token sync,\n  base/variant cross-template `:root` consistency, currently CN to EN and CN to KO)\n  plus `--verify` for the affected targets, or full `--verify` when the change is\n  cross-template.\n- Script changes: `python3 scripts/tests/test_build.py` and\n  `python3 scripts/build.py --check`. Run full `--verify` only when the render\n  pipeline itself changed (`render.py`, `verify.py`, WeasyPrint handling).\n- Font-stack changes (any `--serif` / `--mono` / SVG `text` chain): rebuild the\n  examples, then `python3 scripts/build.py --check-fonts assets/examples/*.pdf`. The\n  page-count contract cannot see which family actually drew the text, and a wrong one\n  renders cleanly; this is how the diagram labels were found splitting mid-word across\n  two faces.\n- Demo changes: regenerate the affected demo outputs and confirm page counts stay in\n  range. Font issues: `bash scripts/ensure-fonts.sh`, then rebuild the target.\n- MCP server changes: smoke the stdio protocol end to end (initialize, tools/list, one\n  tools/call per changed tool) through a scripted stdin session, and check that output\n  stays newline-delimited JSON with no stray prints on stdout.\n- Packaging changes: `bash scripts/package-skill.sh`, then `unzip -l dist/kami.zip` to\n  inspect for accidental large fonts, showcase screenshots, cache files, or a missing\n  new helper.\n- Marketplace or plugin changes: `python3 scripts/build_metadata.py --check` plus the\n  isolated install smoke described under Generated Mirrors.\n- Public site or AI visibility changes: check `index*.html`, README, `llms.txt`,\n  `robots.txt`, `sitemap.xml`, JSON-LD, FAQ, install links, and download links\n  together, then serve the page and screenshot 375px / 1280px per locale, plus 320px\n  when CTA width or mobile nav changes.\n\n## Fonts\n\n`references/production.md` Part 1 «Fonts» owns the full stack: per-language family\nchains, fallbacks, `@font-face` paths, and the recovery flow. Two facts that must not\ndrift out of it:\n\n- `Source Han Serif KR` is the real family name inside the bundled OTFs and must stay\n  in every Korean fallback chain, otherwise fontconfig cannot resolve the\n  `ensure-fonts.sh`-downloaded font by name on an offline Linux skill install.\n- CJK families lead every stack that CJK text can reach, Latin faces trail. A leading\n  Latin serif ends the stack walk for characters it lacks, which sends each ideograph\n  to fontconfig separately and splits words across two faces inside inline SVG\n  (`production.md` pitfall #4.1). The `-en` templates are the deliberate exception:\n  they are Latin documents, so `Charter` stays first there.\n- The commercial TsangerJinKai02 files never ship inside the skill package, so a\n  sandboxed install has no primary CJK serif and falls through the chain. Keep the\n  chain wide (Source Han Serif SC and CN, Noto Serif CJK SC and Noto Serif SC, Songti\n  SC, STSong, SimSun) so it lands on some serif rather than a system sans.\n- `bash scripts/ensure-fonts.sh` downloads into the XDG user font dir\n  (`${XDG_DATA_HOME:-~/.local/share}/fonts/kami`, override with `KAMI_FONT_DIR`),\n  never into the skill's `assets/fonts`, so an installed Claude Desktop skill stays\n  small. Inside a repo checkout it is a no-op because the committed fonts already\n  satisfy the templates' relative paths. Commercial use of TsangerJinKai02 requires\n  the appropriate license.\n\n## Releasing\n\n`docs/release.md` owns release notes format, the tag and asset flow, and demo\nscreenshot regeneration commands. Read it when cutting or refreshing a release.\n","CLAUDE.md":"# Kami\n\nDocument-generation skill and template system. Editorial HTML templates plus a PDF / PPTX / PNG build pipeline.\n\n## Where things live\n\n- **`AGENTS.md` owns every repository maintenance rule**: repo map, working rules, generated mirrors, packaging hard stops, CI gotchas, risk areas, verification, fonts. This file does not restate them. The Claude-specific section below is the only overlap, and it exists because those steps are Claude-side workflow rather than repository policy.\n- Producing a document: `SKILL.md` is the runbook. Template design spec: `references/design.md`. Writing spec: `references/writing.md`. Draft review checklist: `references/anti-patterns.md`. Render troubleshooting: `references/production.md` Part 4. Release flow: `docs/release.md`.\n- `python3 scripts/build.py --help` is the authoritative command list. Do not trust a hand-written copy; the Commands section in `AGENTS.md` covers only the scripts `--help` cannot reach.\n\n## Claude-specific\n\n- This repo ships plugins for both Claude Code and Codex. `plugins/kami/` and `.claude-plugin/marketplace.json` are generated: after editing a root file, run `python3 scripts/build_metadata.py --check`.\n- The Claude Desktop skill package must be the output of `bash scripts/package-skill.sh` (top-level `kami/` directory, 6 MB ceiling). A hand-zipped checkout is rejected on size.\n- To let Claude drive rendering and verification directly: `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`.\n- Plugin install changes need an isolated smoke run: under `HOME=/tmp/...`, `claude plugin marketplace add <path>` then `claude plugin install kami@kami`. Reading metadata is not verification.\n","llms.txt":"# Kami\n\n> A warm parchment design system for AI-assisted professional documents. One accent color, serif-led hierarchy, and editorial whitespace.\n\n## Author\n- Name: Tw93\n- Site: https://tw93.fun\n\n## What is Kami\nKami is a layout design system for the AI era. Give Claude (or any LLM) a brief, and it produces polished documents: one-pagers, resumes, portfolios, slides, long docs, letters, equity reports, and changelogs. The system uses a warm parchment canvas (#f5f4ed), ink-blue accent (#1B365D), and Charter/TsangerJinKai serif fonts. Parchment is the default canvas; an opt-in white-paper variant renders any document on a white background for home or office printers while keeping the warmth in cards and tables.\n\nKami installs into the agent that uses it and runs on that machine. There is no hosted Kami API, no account, and no API key: the integration surface is a local MCP server, JSON content schemas, and CLI checks.\n\n## When to use Kami\nReach for Kami when the user wants a finished document whose appearance matters, and a plain text answer would not be enough:\n- \"Make me a resume / CV\" -> `resume`\n- \"Turn this into a one-pager, product brief, or intro sheet\" -> `one-pager`\n- \"Write a formal letter, offer, or notice\" -> `letter`\n- \"Build a slide deck for this talk\" -> `slides` (PDF, or editable PPTX)\n- \"Write this research, spec, or report up as a document\" -> `long-doc`\n- \"Show my work, case studies, or portfolio\" -> `portfolio`\n- \"Analyze this company or stock and produce a report\" -> `equity-report`\n- \"Write release notes for this version\" -> `changelog`\n- \"Draw an architecture diagram, flowchart, timeline, or chart to embed\" -> one of 18 inline SVG diagram types\n- \"Build a landing page in this style\" -> browser-only `landing-page` template\n\nDo not reach for Kami for chat answers, code files, or content where the user only wants the text. Kami's cost is layout work; it pays off when the artifact is handed to someone else.\n\nHow an agent should call Kami: install the skill, fill the matching content schema, fill the template HTML, then verify with `python3 scripts/build.py --check-content content.json filled.html` and `--check-visual`, or drive the same steps as tools through the local MCP server. Judgment lives in SKILL.md; execution lives in the scripts.\n\n## Key Pages\n- [English showcase](https://kami.tw93.fun): Design system overview with live demos\n- [Developers](https://kami.tw93.fun/developers): Agent and developer integration surface\n- [About](https://kami.tw93.fun/about): What Kami is and who maintains it\n- [Contact](https://kami.tw93.fun/contact): Support and reporting channels\n- [Privacy](https://kami.tw93.fun/privacy): What this site and the skill collect\n- [Chinese showcase](https://kami.tw93.fun/index-zh.html): Chinese version\n- [Japanese showcase](https://kami.tw93.fun/index-ja.html): Japanese version (best-effort CJK path)\n- [Korean showcase](https://kami.tw93.fun/index-ko.html): Korean version (best-effort CJK path)\n- [Traditional Chinese showcase](https://kami.tw93.fun/index-tw.html): Traditional Chinese version\n- [GitHub](https://github.com/tw93/kami): Source code and templates\n\n## Install\n- Claude Code (v2.1.142+): `/plugin marketplace add tw93/kami && /plugin install kami@kami`\n- Codex plugin marketplace: `codex plugin marketplace add tw93/kami && codex plugin add kami@kami`\n- Generic agents (`~/.agents`): `npx skills add tw93/kami/plugins/kami -a universal -g -y`\n- Claude Desktop: download the release asset `kami.zip` from GitHub Releases (not the source-code ZIP) and upload it in Skills settings\n- MCP client: `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`\n\n## Templates\n- 8 document template types: One-pager, Letter, Resume, Long document, Portfolio, Slides, Equity report, Changelog\n- 18 diagram types: architecture, architecture board, flowchart, quadrant, bar chart, line chart, donut chart, state machine, timeline, swimlane, tree, layer stack, venn, candlestick, waterfall, sequence, class, ER\n\n## Agent Interfaces\n- Content contracts: `references/schemas/<type>.json` carries the per-type structure and quality bar; new `content.json` files also carry an artifact `brief` with target, preserve boundary, evidence, and acceptance checks; validate before layout and check coverage after filling with `python3 scripts/build.py --check-content content.json [filled.html]`\n- Deterministic checks: placeholders, markdown residue, page density, orphan lines, slide rhythm, and a perceptual pass that exports page images with a fixed review checklist (`--check-visual`)\n- MCP server: `python3 scripts/mcp_server.py` speaks MCP over stdio with tools kami_templates / kami_doctor / kami_render / kami_check / kami_screenshot, so agents can diagnose, render, and verify without loading the skill prompt\n\n## Machine-Readable Files\n- MCP server card: https://kami.tw93.fun/.well-known/mcp/server-card.json\n- Agent Skills index: https://kami.tw93.fun/.well-known/agent-skills/index.json\n- Skill definition: https://kami.tw93.fun/SKILL.md\n- Homepage as Markdown: https://kami.tw93.fun/index.md (a request to `/` carrying `Accept: text/markdown`, or `/?mode=agent`, redirects here)\n- Developer surface: https://kami.tw93.fun/developers.md and https://kami.tw93.fun/developers/llms.txt\n- Template and diagram catalog: https://kami.tw93.fun/feeds/catalog.jsonld (indexed by https://kami.tw93.fun/schemamap.xml)\n\n## Links\n- GitHub: https://github.com/tw93\n- Blog: https://tw93.fun\n- AI Profile: https://tw93.fun/llms-full.txt\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Kami Agent Guide\n\n## Project\n\nKami is a document-generation skill and template system: self-contained editorial HTML\ntemplates rendered to PDF / PPTX / PNG, plus reference specs, demo assets, and a\npackaged skill archive. `SKILL.md` is the runtime manual for producing a document.\nThis file is the maintenance guide for changing the repository itself, and it records\nthe traps that a fresh read of the code does not reveal.\n\n## Repository Map\n\nOnly the entries whose role is not obvious from the filename:\n\n- `SKILL.md` - skill routing plus the document-side build and verify commands.\n  `CHEATSHEET.md` - quick design reference. Both ship inside the package.\n- `references/design.md`, `writing.md`, `production.md`, `diagrams.md` - full specs.\n  `production.md` Part 4 is the single source of truth for render failures, their\n  verified causes, and their fixes; add pitfalls there, not here.\n  `docs/release.md` - release notes, release flow, demo screenshot regeneration.\n  `anti-patterns.md`, `resume-writing.md`, `mermaid.md`, `deck-preflight.md`,\n  `brand-profile.md` and `brand.example.md` - scoped guides.\n- `references/tokens.json` (color tokens, drift-checked by `scripts/tokens.py`),\n  `references/mermaid-theme.json` (Kami to beautiful-mermaid theme, kept in sync with\n  `tokens.json`), `references/checks_thresholds.json` (rhythm / density / orphan /\n  visual thresholds read by `checks.py` and `visual.py`). These are live inputs to\n  gates: editing a number changes what passes.\n- `references/schemas/` - one JSON Schema subset per document type. The `$comment`\n  fields carry the per-field quality bar distilled from `writing.md`, so schema edits\n  and `writing.md` edits move together.\n- `scripts/shared.py` - the canonical registries (`HTML_TEMPLATES`,\n  `SCREEN_TEMPLATES`, `PPTX_TEMPLATES`, `MARP_TEMPLATES`, `DIAGRAM_TEMPLATES`) and each template's\n  `build_max_pages`. `build.py` derives its internal build targets from them;\n  Marp stays discovery-only because it uses an external CLI. Add or remove a\n  template or diagram here, never in a per-script dict.\n- `scripts/render.py` - the single render entry (`render_pdf`, `build_slides`, PDF\n  metadata stamping). `build.py`, `verify.py`, and `mcp_server.py` all call it; never\n  open a second WeasyPrint call site.\n- `scripts/mermaid_normalize.py` - re-themes a beautiful-mermaid SVG to the Kami\n  palette and makes it WeasyPrint-safe. Pure Python, no Node, ships in the package.\n- `scripts/mcp_server.py` - zero-dependency MCP stdio server exposing\n  `kami_templates` / `kami_doctor` / `kami_render` / `kami_check` /\n  `kami_screenshot`, so an MCP-capable agent can diagnose, render, and verify\n  without reading `SKILL.md`. Register\n  with `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`.\n- `scripts/site_facts.py` - public-site fact drift checks (install commands, version,\n  template and diagram counts across `index*.html`, `README.md`, `llms.txt`), wired\n  into `build.py --check`.\n- `scripts/check-update.sh` - quiet daily update check invoked from `SKILL.md`;\n  read-only VERSION compare, silent on any failure.\n- `assets/showcase/` - README and public-site screenshots only. `assets/demos/` -\n  README showcase demos. `scripts/package-skill.sh` excludes both from the ZIP.\n- `assets/diagrams/src/*.mmd` - Mermaid source of the sequence / class / er diagrams.\n  `assets/templates/marp/` - the Markdown-first Marp deck variant.\n- `dist/kami.zip` - **tracked** release archive, committed with release changes.\n- `plugins/kami/`, `.claude-plugin/marketplace.json`, and\n  `.agents/plugins/marketplace.json` are **generated**; see Generated Mirrors below.\n- Public site surface: `index.html` plus `index-zh|en|ja|ko|tw.html`, the English-only\n  prose pages `developers|about|contact|privacy.html`, `styles.css`, `llms.txt`,\n  `robots.txt`, `sitemap.xml`, `vercel.json`. `styles.css` is Kami's own site shell\n  (language switcher, gallery, responsive behavior, `.hero.doc` / `.prose` for the\n  prose pages); generic template rules never belong there.\n- Agent-facing site surface: `index.md` (Markdown twin of the homepage; `vercel.json`\n  *redirects* `/` here for `Accept: text/markdown` and `/?mode=agent`, because Vercel\n  applies `rewrites` only after the filesystem and `/` always matches `index.html`),\n  `developers|about|contact|privacy.md`, `developers/llms.txt`, and the generated\n  `.well-known/agent-skills/index.json`, `.well-known/mcp/server-card.json`,\n  `feeds/catalog.jsonld`, `schemamap.xml`. Every new prose page needs its `.md` twin,\n  a `rewrites` entry for the extensionless URL, and a `sitemap.xml` row.\n  The `has`-conditioned redirects and the `Link` headers are only observable on a\n  deploy: verify them with `curl -sI` against the preview URL, never locally.\n- `.github/workflows/check.yml` (PR/push CI) and `release.yml` (tag-triggered build\n  and asset upload).\n\nReference docs are English-first and never forked per language. Inline CJK examples\nare fine where the rule itself is about CJK typography (term annotation, punctuation,\nspacing); language-specific output differences (CN/EN/KO) live in templates, not in\nduplicated reference files.\n\n## Commands\n\n`python3 scripts/build.py --help` prints the authoritative flag list and the module\nmap. Read it instead of trusting any copy; hand-maintained lists here have gone stale\nbefore. The commands it does not cover:\n\n```bash\npython3 scripts/build_metadata.py            # regenerate plugin mirror + marketplace metadata\npython3 scripts/build_metadata.py --check    # drift check for the same\nbash scripts/package-skill.sh                # build the tracked dist/kami.zip\nbash scripts/ensure-fonts.sh                 # recover missing or truncated CJK fonts\npython3 scripts/mcp_server.py                # MCP stdio server (render / check / screenshot)\npython3 scripts/mermaid_normalize.py raw.svg -o clean.svg\npython3 scripts/draft-release-notes.py V1.4.0..HEAD --version V1.4.1 --title \"Steadier Hand\"\npython3 scripts/tests/test_build.py          # zero-dependency test suite\n```\n\n## Working Rules\n\n- Style changes must update `references/design.md` and the matching template tokens.\n- A CSS snippet in a reference doc is a shipped artifact, not prose: an agent copies\n  it before it reads a template. Every fenced `css` / `html` block is scanned by\n  `--check-docs` (inside `--check`) with the template rule set, and every `var()` it\n  names must resolve to a registered token or one a shipped template defines. Teach\n  from a component a template actually has; a recipe for assembling a new container\n  is how a document ends up carrying three unrelated emphasis languages. Tag a\n  deliberate counter-example inline with `/* avoid */` so the scan reads it as the\n  lesson rather than the violation.\n- A change touching template tokens, shared CSS gestures, or `references/design.md`\n  visual rules must rebuild the affected demo outputs (`assets/demos/*.pdf` / `*.png`)\n  in the same change, not as a later cleanup. Demos inline their CSS by copy, so they\n  silently keep the old style otherwise. Report the sweep: rebuilt N demos, K\n  unaffected. The off-palette guard in `scripts/lint.py` scans `assets/demos/*.html`\n  for stale hexes as a backstop, but it cannot see rendered PDFs or PNGs.\n- Templates intentionally inline their CSS rather than share a `_kami.css` partial:\n  each template must stay a single self-contained HTML file the user can copy-paste\n  with no build step. Fix CSS drift by applying the same change across the affected\n  templates, never by introducing a build-time include.\n- For document or template tasks, lock the output contract before editing: language,\n  template, output format, page or length target, visual acceptance check, and\n  verification command.\n- Prefer the nearest existing template and deterministic verifier. Do not add a\n  template, shared CSS layer, dependency, script flag, or optional mode unless the\n  current request cannot be satisfied without it. A new template copies the nearest\n  existing one, stays aligned with `references/design.md`, and adds demo coverage; a\n  new document type also needs a schema in `references/schemas/`.\n- Slides default to WeasyPrint HTML-to-PDF templates unless the user explicitly needs\n  editable PPTX output.\n- Mermaid diagrams: never embed raw beautiful-mermaid SVG into a PDF-bound template.\n  WeasyPrint cannot resolve `color-mix()`, render `<foreignObject>`, or fetch a\n  runtime web font, so always pipe through `scripts/mermaid_normalize.py` first\n  (`--check` enforces this). `xychart-beta` is browser-only because it styles through\n  `<style>` class selectors; use the hand-drawn chart diagrams for PDF. Full flow in\n  `references/mermaid.md`.\n- Do not use graphic emoticons in docs, template comments, or script output. Use `OK:`\n  and `ERROR:` for script status text.\n- Do not use em dashes (U+2014) in repository docs, generated documents, template\n  comments, or site copy; use colons, commas, periods, or parentheses. Self-check:\n  `grep -rn \"$(printf '\\342\\200\\224')\" README.md llms.txt index*.html`. Teaching\n  counter-examples inside `references/anti-patterns.md` are exempt; its rule #28\n  covers the generated-document side.\n- For hosted-site or public-landing work, separate generic template work from Kami's\n  own website first. Generic behavior lives in `assets/templates/landing-page*` and\n  `references/`; Kami site facts live across `index*.html`, `styles.css`, `README.md`,\n  `llms.txt`, `robots.txt`, `sitemap.xml`, and `vercel.json`. Public facts are wider\n  than the hero: pricing, install path, version, release, support, analytics, FAQ, and\n  positioning claims move together across pages, metadata, AI files, and download\n  links. Do not leave a site-only analytics or tracking change contradicting the\n  \"no analytics\" copy elsewhere.\n- Landing or documentation-site work follows `references/design.md` Section 11 «Landing\n  Page (screen-first)»: its «Documentation site» subsection for the doc shell (sidebar\n  rail, on-this-page TOC, borderless prev/next pager), then Section 12 «Responsive\n  screenshot verification» (screenshot at 375px / 1280px per locale, objective\n  line-widow scan) before shipping.\n- Content changes should avoid CSS churn unless layout behavior is part of the task.\n- Brand profile support is optional context. Keep public examples in `references/`; do\n  not hard-code a maintainer's private local profile.\n- Demo, reference-example, and handoff content distilled from a maintainer's private\n  documents (resume, business proposal, pricing, client names) must be de-identified\n  before it lands in the repo: swap in public figures, public projects, or invented\n  generic data. Job-search, quote, and engagement-period fields count as sensitive\n  even without names. List the swapped-out identifying signals in the handoff report;\n  do not rely on the maintainer to spot leftovers.\n- Do not commit one-off review reports or diagnostic snapshots as durable docs.\n  Extract the stable rule into `AGENTS.md`, `SKILL.md`, or `references/`, then discard\n  the report.\n\n## Generated Mirrors\n\n`plugins/kami/`, `.claude-plugin/marketplace.json`, and `.agents/plugins/marketplace.json`\nare generated from the root sources. Edit the root file only, treat every\n`plugins/kami/skills/kami/...` path as a mirror, and let\n`python3 scripts/build_metadata.py --check` catch drift. Regenerate after changing\n`SKILL.md`, `CHEATSHEET.md`, `VERSION`, `references/`, `scripts/`, or shipped\nlightweight assets.\n\nThe same generator owns the site's machine-readable discovery files:\n`.well-known/agent-skills/index.json` (carries a SHA-256 digest of `SKILL.md`, so any\nskill edit changes it), `.well-known/mcp/server-card.json` (version plus the tool list\nparsed out of `scripts/mcp_server.py` without importing it), `feeds/catalog.jsonld`\n(built from `HTML_TEMPLATES` / `DIAGRAM_TEMPLATES`), and `schemamap.xml`. Never\nhand-edit these four; change the source and regenerate.\n\nMarketplace, plugin path, version, or install-path changes need runtime installation\nproof, not metadata proof. Claude Code: an isolated `HOME=/tmp/...` smoke with\n`claude plugin marketplace add <path>`, `claude plugin install kami@kami`,\n`claude plugin details kami@kami`, confirming the installed cache is the lightweight\n`plugins/kami` tree. Codex: an isolated `CODEX_HOME=/tmp/...` smoke with\n`codex plugin marketplace add <path>`, `codex plugin add kami@kami`,\n`codex plugin list`.\n\n## Refactor And Packaging Hard Stops\n\n- The shipped archive must be the output of `bash scripts/package-skill.sh`: a\n  top-level `kami/` directory under a 6 MB ceiling. A hand-zipped checkout is\n  rejected on size.\n- `scripts/package-skill.sh` packages from `git ls-files`, so an untracked new module\n  passes every local import and silently disappears from `dist/kami.zip`. When\n  splitting `build.py` or a package helper into new modules, confirm each new file is\n  tracked by Git and added to the scripts allowlist in `package-skill.sh` (its\n  coverage gate fails the build otherwise).\n- Any source change to `SKILL.md`, scripts, templates, reference JSON, workflows, or\n  package inputs must refresh and inspect `dist/kami.zip`. Package freshness is release\n  readiness, not later cleanup. It is also the precondition for telling a reporter a fix\n  has shipped: a commit on `main` reaches `npx skills add` and plugin installs right\n  away, but Claude Desktop users download\n  `releases/latest/download/kami.zip`, so name the channel that actually carries the fix\n  and confirm that asset was refreshed before saying \"fixed, please update\".\n- If `python3 scripts/build.py --verify` fails only because the host Python lacks PPTX\n  fallback dependencies such as `python-pptx`, verify `slides` and `slides-en` from a\n  temporary venv instead of treating the environment miss as a source regression.\n- Resume templates (`assets/templates/resume.html`, `resume-ko.html`) carry a two-page\n  contract. Do not fix overflow by shrinking type or spacing globally first. Verify\n  with `python3 scripts/build.py --verify resume` and `--verify resume-ko`.\n- Demo files such as `assets/demos/demo-resume-ko.html` own demo content, not the\n  template contract. Durable rules go into templates or `references/`.\n\n## CI Gotchas\n\nApplies when editing `.github/workflows/*.yml` or adding a test with a heavy\ndependency.\n\n- `check.yml` has two jobs. `lint-and-test` runs dependency-light lint, metadata,\n  and package gates. `verify-render` installs `weasyprint` / `pypdf` / `PyMuPDF` /\n  `Pygments`, then runs the full test suite before template verification. Tests that\n  need an optional render dependency use the suite's explicit `SKIP:` counter and\n  fail when a CI-required dependency is unavailable; never turn a skip into `OK:`.\n- Validate workflow edits on a feature branch (push, watch the run go green) before\n  merging to `main`. Local font and dependency assumptions diverge from CI more often\n  than expected; this project has already burned commits on `pip` cache requiring a\n  manifest, the `fallback_present` set missing Ubuntu defaults (DejaVu / Liberation),\n  and CI never having commercial fonts (Charter / TsangerJinKai02).\n- Host-versus-CI differences are expressed as explicit opt-in env vars, currently\n  `KAMI_ALLOW_FALLBACK_ONLY` (accept fallback fonts), `KAMI_AUTHOR`, `KAMI_FONT_DIR`,\n  `KAMI_PACKAGE_ROOT_NAME`, `KAMI_PACKAGE_MAX_BYTES`, and `KAMI_UPDATE_URL`. That is\n  already the ceiling: before adding another, move the behavior into a `--ci-mode`\n  flag or a config file rather than letting `KAMI_*` sprawl.\n\n## Current Risk Areas\n\n- WeasyPrint rendering is sensitive to font availability, solid hex tag backgrounds,\n  page breaks, CJK fallback, and synthetic bold. Verify visually for template changes.\n- Slide output has three paths: `slides-weasy*.html` for default PDF decks,\n  `slides*.py` for the editable PPTX fallback, and\n  `assets/templates/marp/slides-marp*.{md,css}` for Markdown-first Marp decks.\n- Marp theme CSS inlines a full copy of the design tokens because Marp themes must be\n  self-contained. `build.py --sync` / `--check` token-sync those files and the CSS\n  lint rules scan them (both walk `shared.iter_template_files`), so token drift is\n  caught. The remaining hole: the off-palette hex guard globs `*.html` only\n  (`TEMPLATES/*.html` and `assets/demos/*.html`), so an off-palette color in Marp CSS\n  still needs eyeball review.\n- Page counts are a ceiling, never a floor. `build.py --verify` fails only when a PDF\n  exceeds `build_max_pages` in `scripts/shared.py` (one-pager 1, letter 1, resume 2,\n  changelog 2, equity-report 3; long-doc, portfolio, and slides-weasy are `0` =\n  unlimited). An undershooting document is never flagged, so \"this long-doc came out\n  at 3 pages\" is an authoring judgment call, not a gate failure. Landing pages are\n  browser-only HTML with no page count at all.\n- `scripts/render.py` sets PDF `/Author` from `git config user.name` or `KAMI_AUTHOR`\n  only when the template still holds an author placeholder. `/Producer` and `/Creator`\n  stay `Kami`.\n- Long-doc TOCs use WeasyPrint `target-counter()` and stable chapter ids for rendered\n  page numbers; do not reintroduce hand-written `.toc-page` spans. Running headers\n  default to `h1`. If a filled document does not use `h1` for chapter titles, add\n  `.running-title` to the element that should drive the header.\n- AI and public visibility spans `index*.html`, `llms.txt`, `robots.txt`,\n  `sitemap.xml`, FAQ JSON-LD, README install text, diagram counts, and release archive\n  links. Diagram count and names must stay aligned across `SKILL.md`, `CHEATSHEET.md`,\n  `README.md`, `index*.html`, and `assets/diagrams/`.\n\n## Critical Line-Break Scan\n\nApplies before handing off any user-visible typeset deliverable (rendered PDF,\n`README.md`, public site page).\n\n- Scan page by page for three critical wrap states: a trailing line of only 1-2 words\n  (orphan), a line one word away from wrapping, and a line that wraps early without\n  filling its container.\n- Split the work: `python3 scripts/build.py --check-orphans <pdf>` and\n  `--check-density <pdf>` catch PDF orphans and sparse pages deterministically; the\n  manual pass covers what they cannot see, near-wrap and premature-wrap states inside\n  a page, plus non-PDF surfaces (README, `index*.html` at 375px / 1280px).\n- One hit means a whole-document sweep for that class, not a single-spot fix. Fix by\n  adjusting content length first; changing font size or spacing to dodge a wrap is the\n  last resort and must re-pass `python3 scripts/build.py --check` and the page-count\n  contract.\n\n## Verification\n\n`SKILL.md` Step 5 owns the document-side commands (render, placeholders, markdown\nresidue, content IR, visual, rhythm, resume balance). This section covers the\nmaintenance side only.\n\n- Template or CSS changes: `python3 scripts/build.py --check` (CSS lint, token sync,\n  base/variant cross-template `:root` consistency, currently CN to EN and CN to KO)\n  plus `--verify` for the affected targets, or full `--verify` when the change is\n  cross-template.\n- Script changes: `python3 scripts/tests/test_build.py` and\n  `python3 scripts/build.py --check`. Run full `--verify` only when the render\n  pipeline itself changed (`render.py`, `verify.py`, WeasyPrint handling).\n- Font-stack changes (any `--serif` / `--mono` / SVG `text` chain): rebuild the\n  examples, then `python3 scripts/build.py --check-fonts assets/examples/*.pdf`. The\n  page-count contract cannot see which family actually drew the text, and a wrong one\n  renders cleanly; this is how the diagram labels were found splitting mid-word across\n  two faces.\n- Demo changes: regenerate the affected demo outputs and confirm page counts stay in\n  range. Font issues: `bash scripts/ensure-fonts.sh`, then rebuild the target.\n- MCP server changes: smoke the stdio protocol end to end (initialize, tools/list, one\n  tools/call per changed tool) through a scripted stdin session, and check that output\n  stays newline-delimited JSON with no stray prints on stdout.\n- Packaging changes: `bash scripts/package-skill.sh`, then `unzip -l dist/kami.zip` to\n  inspect for accidental large fonts, showcase screenshots, cache files, or a missing\n  new helper.\n- Marketplace or plugin changes: `python3 scripts/build_metadata.py --check` plus the\n  isolated install smoke described under Generated Mirrors.\n- Public site or AI visibility changes: check `index*.html`, README, `llms.txt`,\n  `robots.txt`, `sitemap.xml`, JSON-LD, FAQ, install links, and download links\n  together, then serve the page and screenshot 375px / 1280px per locale, plus 320px\n  when CTA width or mobile nav changes.\n\n## Fonts\n\n`references/production.md` Part 1 «Fonts» owns the full stack: per-language family\nchains, fallbacks, `@font-face` paths, and the recovery flow. Two facts that must not\ndrift out of it:\n\n- `Source Han Serif KR` is the real family name inside the bundled OTFs and must stay\n  in every Korean fallback chain, otherwise fontconfig cannot resolve the\n  `ensure-fonts.sh`-downloaded font by name on an offline Linux skill install.\n- CJK families lead every stack that CJK text can reach, Latin faces trail. A leading\n  Latin serif ends the stack walk for characters it lacks, which sends each ideograph\n  to fontconfig separately and splits words across two faces inside inline SVG\n  (`production.md` pitfall #4.1). The `-en` templates are the deliberate exception:\n  they are Latin documents, so `Charter` stays first there.\n- The commercial TsangerJinKai02 files never ship inside the skill package, so a\n  sandboxed install has no primary CJK serif and falls through the chain. Keep the\n  chain wide (Source Han Serif SC and CN, Noto Serif CJK SC and Noto Serif SC, Songti\n  SC, STSong, SimSun) so it lands on some serif rather than a system sans.\n- `bash scripts/ensure-fonts.sh` downloads into the XDG user font dir\n  (`${XDG_DATA_HOME:-~/.local/share}/fonts/kami`, override with `KAMI_FONT_DIR`),\n  never into the skill's `assets/fonts`, so an installed Claude Desktop skill stays\n  small. Inside a repo checkout it is a no-op because the committed fonts already\n  satisfy the templates' relative paths. Commercial use of TsangerJinKai02 requires\n  the appropriate license.\n\n## Releasing\n\n`docs/release.md` owns release notes format, the tag and asset flow, and demo\nscreenshot regeneration commands. Read it when cutting or refreshing a release.\n","category":"root","tokens":5611},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Kami\n\nDocument-generation skill and template system. Editorial HTML templates plus a PDF / PPTX / PNG build pipeline.\n\n## Where things live\n\n- **`AGENTS.md` owns every repository maintenance rule**: repo map, working rules, generated mirrors, packaging hard stops, CI gotchas, risk areas, verification, fonts. This file does not restate them. The Claude-specific section below is the only overlap, and it exists because those steps are Claude-side workflow rather than repository policy.\n- Producing a document: `SKILL.md` is the runbook. Template design spec: `references/design.md`. Writing spec: `references/writing.md`. Draft review checklist: `references/anti-patterns.md`. Render troubleshooting: `references/production.md` Part 4. Release flow: `docs/release.md`.\n- `python3 scripts/build.py --help` is the authoritative command list. Do not trust a hand-written copy; the Commands section in `AGENTS.md` covers only the scripts `--help` cannot reach.\n\n## Claude-specific\n\n- This repo ships plugins for both Claude Code and Codex. `plugins/kami/` and `.claude-plugin/marketplace.json` are generated: after editing a root file, run `python3 scripts/build_metadata.py --check`.\n- The Claude Desktop skill package must be the output of `bash scripts/package-skill.sh` (top-level `kami/` directory, 6 MB ceiling). A hand-zipped checkout is rejected on size.\n- To let Claude drive rendering and verification directly: `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`.\n- Plugin install changes need an isolated smoke run: under `HOME=/tmp/...`, `claude plugin marketplace add <path>` then `claude plugin install kami@kami`. Reading metadata is not verification.\n","category":"root","tokens":421},{"name":"llms.txt","path":"llms.txt","title":"llms.txt","content":"# Kami\n\n> A warm parchment design system for AI-assisted professional documents. One accent color, serif-led hierarchy, and editorial whitespace.\n\n## Author\n- Name: Tw93\n- Site: https://tw93.fun\n\n## What is Kami\nKami is a layout design system for the AI era. Give Claude (or any LLM) a brief, and it produces polished documents: one-pagers, resumes, portfolios, slides, long docs, letters, equity reports, and changelogs. The system uses a warm parchment canvas (#f5f4ed), ink-blue accent (#1B365D), and Charter/TsangerJinKai serif fonts. Parchment is the default canvas; an opt-in white-paper variant renders any document on a white background for home or office printers while keeping the warmth in cards and tables.\n\nKami installs into the agent that uses it and runs on that machine. There is no hosted Kami API, no account, and no API key: the integration surface is a local MCP server, JSON content schemas, and CLI checks.\n\n## When to use Kami\nReach for Kami when the user wants a finished document whose appearance matters, and a plain text answer would not be enough:\n- \"Make me a resume / CV\" -> `resume`\n- \"Turn this into a one-pager, product brief, or intro sheet\" -> `one-pager`\n- \"Write a formal letter, offer, or notice\" -> `letter`\n- \"Build a slide deck for this talk\" -> `slides` (PDF, or editable PPTX)\n- \"Write this research, spec, or report up as a document\" -> `long-doc`\n- \"Show my work, case studies, or portfolio\" -> `portfolio`\n- \"Analyze this company or stock and produce a report\" -> `equity-report`\n- \"Write release notes for this version\" -> `changelog`\n- \"Draw an architecture diagram, flowchart, timeline, or chart to embed\" -> one of 18 inline SVG diagram types\n- \"Build a landing page in this style\" -> browser-only `landing-page` template\n\nDo not reach for Kami for chat answers, code files, or content where the user only wants the text. Kami's cost is layout work; it pays off when the artifact is handed to someone else.\n\nHow an agent should call Kami: install the skill, fill the matching content schema, fill the template HTML, then verify with `python3 scripts/build.py --check-content content.json filled.html` and `--check-visual`, or drive the same steps as tools through the local MCP server. Judgment lives in SKILL.md; execution lives in the scripts.\n\n## Key Pages\n- [English showcase](https://kami.tw93.fun): Design system overview with live demos\n- [Developers](https://kami.tw93.fun/developers): Agent and developer integration surface\n- [About](https://kami.tw93.fun/about): What Kami is and who maintains it\n- [Contact](https://kami.tw93.fun/contact): Support and reporting channels\n- [Privacy](https://kami.tw93.fun/privacy): What this site and the skill collect\n- [Chinese showcase](https://kami.tw93.fun/index-zh.html): Chinese version\n- [Japanese showcase](https://kami.tw93.fun/index-ja.html): Japanese version (best-effort CJK path)\n- [Korean showcase](https://kami.tw93.fun/index-ko.html): Korean version (best-effort CJK path)\n- [Traditional Chinese showcase](https://kami.tw93.fun/index-tw.html): Traditional Chinese version\n- [GitHub](https://github.com/tw93/kami): Source code and templates\n\n## Install\n- Claude Code (v2.1.142+): `/plugin marketplace add tw93/kami && /plugin install kami@kami`\n- Codex plugin marketplace: `codex plugin marketplace add tw93/kami && codex plugin add kami@kami`\n- Generic agents (`~/.agents`): `npx skills add tw93/kami/plugins/kami -a universal -g -y`\n- Claude Desktop: download the release asset `kami.zip` from GitHub Releases (not the source-code ZIP) and upload it in Skills settings\n- MCP client: `claude mcp add kami -- python3 <checkout>/scripts/mcp_server.py`\n\n## Templates\n- 8 document template types: One-pager, Letter, Resume, Long document, Portfolio, Slides, Equity report, Changelog\n- 18 diagram types: architecture, architecture board, flowchart, quadrant, bar chart, line chart, donut chart, state machine, timeline, swimlane, tree, layer stack, venn, candlestick, waterfall, sequence, class, ER\n\n## Agent Interfaces\n- Content contracts: `references/schemas/<type>.json` carries the per-type structure and quality bar; new `content.json` files also carry an artifact `brief` with target, preserve boundary, evidence, and acceptance checks; validate before layout and check coverage after filling with `python3 scripts/build.py --check-content content.json [filled.html]`\n- Deterministic checks: placeholders, markdown residue, page density, orphan lines, slide rhythm, and a perceptual pass that exports page images with a fixed review checklist (`--check-visual`)\n- MCP server: `python3 scripts/mcp_server.py` speaks MCP over stdio with tools kami_templates / kami_doctor / kami_render / kami_check / kami_screenshot, so agents can diagnose, render, and verify without loading the skill prompt\n\n## Machine-Readable Files\n- MCP server card: https://kami.tw93.fun/.well-known/mcp/server-card.json\n- Agent Skills index: https://kami.tw93.fun/.well-known/agent-skills/index.json\n- Skill definition: https://kami.tw93.fun/SKILL.md\n- Homepage as Markdown: https://kami.tw93.fun/index.md (a request to `/` carrying `Accept: text/markdown`, or `/?mode=agent`, redirects here)\n- Developer surface: https://kami.tw93.fun/developers.md and https://kami.tw93.fun/developers/llms.txt\n- Template and diagram catalog: https://kami.tw93.fun/feeds/catalog.jsonld (indexed by https://kami.tw93.fun/schemamap.xml)\n\n## Links\n- GitHub: https://github.com/tw93\n- Blog: https://tw93.fun\n- AI Profile: https://tw93.fun/llms-full.txt\n","category":"root","tokens":1381}]}