# Zhi

> A warm parchment design system for AI-assisted professional documents. One accent color, serif-led hierarchy, and editorial whitespace.

## Project
- Name: Zhi（纸）
- Repository: https://github.com/okht/zhi
- Status: private preview; repository access requires authorization; no formal release is available yet.

## What is Zhi
Zhi 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), Charter for Latin, and FangZheng GongWen KaiTi for Chinese. Resume pages default to pure white and A4 one page; warm cream and two pages are optional. Photos are optional. Other documents retain parchment.

Zhi installs into the agent that uses it and runs on that machine. There is no hosted Zhi API, Zhi account, or Zhi API key: the integration surface is a local MCP server, JSON content schemas, and CLI checks. GitHub authentication is required to obtain the private checkout.

## When to use Zhi
Reach for Zhi when the user wants a finished document whose appearance matters, and a plain text answer would not be enough:
- "Make me a resume / CV" -> route Resume polish, Resume construction, or Source-led reconstruction; Visual guide, Layout fitting, Source protection, then HTML + PDF + validated DOCX
- "Turn this into a one-pager, product brief, or intro sheet" -> `one-pager`
- "Write a formal letter, offer, or notice" -> `letter`
- "Build a slide deck for this talk" -> `slides` (PDF, or editable PPTX)
- "Write this research, spec, or report up as a document" -> `long-doc`
- "Show my work, case studies, or portfolio" -> `portfolio`
- "Analyze this company or stock and produce a report" -> `equity-report`
- "Write release notes for this version" -> `changelog`
- "Draw an architecture diagram, flowchart, timeline, or chart to embed" -> one of 18 inline SVG diagram types
- "Build a landing page in this style" -> browser-only `landing-page` template

Do not reach for Zhi for chat answers, code files, or content where the user only wants the text. Zhi's cost is layout work; it pays off when the artifact is handed to someone else.

How an agent should call Zhi: 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.

## Key Pages
- [English showcase](https://zhi.cht.me/): Design system overview with live demos
- [Developers](https://zhi.cht.me/developers.html): Agent and developer integration surface
- [About](https://zhi.cht.me/about.html): What Zhi is and who maintains it
- [Contact](https://zhi.cht.me/contact.html): Support and reporting channels
- [Privacy](https://zhi.cht.me/privacy.html): What this site and the skill collect
- [Chinese showcase](https://zhi.cht.me/index-zh.html): Chinese version
- [Japanese showcase](https://zhi.cht.me/index-ja.html): Japanese version (best-effort CJK path)
- [Korean showcase](https://zhi.cht.me/index-ko.html): Korean version (best-effort CJK path)
- [Traditional Chinese showcase](https://zhi.cht.me/index-tw.html): Traditional Chinese version
- [GitHub](https://github.com/okht/zhi): Source code and templates

## Install
- Private preview guide: https://zhi.cht.me/developers#private-preview. Authorized repository access is required; there is no public release download.
- Authenticate with `gh auth login`, then `gh repo clone okht/zhi ./zhi`. Run the following commands from the parent of the new checkout.
- Claude Code (v2.1.142+): `/plugin marketplace add ./zhi`, then `/plugin install zhi@zhi`
- Codex plugin marketplace: `codex plugin marketplace add ./zhi`, then `codex plugin add zhi@zhi`
- Generic agents (`~/.agents`): `npx skills add ./zhi/plugins/zhi -a universal -g -y`
- Claude Desktop: upload the checkout's Slim `dist/zhi.zip` in Skills settings; it stays below 6 MB.
- Fonts: authorized testers build `zhi-fonts-full.zip` locally and pass it to `bash scripts/ensure-fonts.sh` with `--bundle` and `--approved-only`. See the guide for the exact paths and render verification.
- MCP client: `claude mcp add zhi -- python3 <checkout>/scripts/mcp_server.py`

## Templates
- 8 document template types: One-pager, Letter, Resume, Long document, Portfolio, Slides, Equity report, Changelog
- 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

## Agent Interfaces
- 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]`
- 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`)
- MCP server: `python3 scripts/mcp_server.py` speaks MCP over stdio with tools zhi_templates / zhi_doctor / zhi_render / zhi_check / zhi_screenshot, so agents can diagnose, render, and verify without loading the skill prompt

## Machine-Readable Files
- Homepage as Markdown: https://zhi.cht.me/index.md (direct Markdown endpoint)
- Developer surface: https://zhi.cht.me/developers.md and https://zhi.cht.me/developers/llms.txt
- Runtime definitions, source templates, full font bundles, and distribution catalogs are available only through the authorized checkout during private preview.

## Links
- Private source (authorized users): https://github.com/okht/zhi
- Questions and bug reports (authorized users): https://github.com/okht/zhi/issues