# Zhi

Zhi is a document layout design system for the AI era. Give an AI agent a brief, and Zhi turns it into a finished document: a one-pager, resume, portfolio, slide deck, long report, letter, equity report, or changelog. Output is HTML that exports to PDF, PNG, or editable PPTX.

The system is a fixed constraint set rather than a theme picker: a warm parchment canvas (`#f5f4ed`), a single ink-blue accent (`#1B365D`), serif-led hierarchy (Charter for Latin, FangZheng GongWen KaiTi for Chinese), and editorial whitespace. Resume pages default to pure white with warm cream as the alternate; other documents keep the established parchment default.

Zhi runs on the machine that installs it, with no hosted Zhi API or Zhi account. It is currently a private preview with no formal release. Access to the private GitHub repository requires authorization; this public site provides an overview and selected samples.

## When to use Zhi

Reach for Zhi when the user asks for a document whose *appearance* matters and a plain markdown answer would not be enough:

- "Make me a resume / CV" - route to Resume polish, Resume construction, or Source-led reconstruction; ask only the Visual guide for a complete resume, use Layout fitting under Source protection, then deliver HTML, PDF, and validated DOCX.
- "Turn this into a one-pager / product brief / intro sheet" - `one-pager`.
- "Write a formal letter, offer, or notice" - `letter`.
- "Build a slide deck for this talk" - `slides`, exported to PDF or editable PPTX.
- "Write up this research / spec / report as a document" - `long-doc`.
- "Show my work / case studies / portfolio" - `portfolio`.
- "Analyze this stock or company 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 the 18 inline SVG diagram types.
- "Build a landing page in this style" - the 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 delivered to someone else.

How an agent should call Zhi: install the skill (below), fill the template HTML, then verify with `python3 scripts/build.py --check-content` and `--check-visual`, or drive the same steps as tools through the local MCP server. The judgment lives in `SKILL.md`; the execution lives in the scripts.

## Install

Read the [private preview guide](https://zhi.cht.me/developers#private-preview) first. An authorized GitHub account is required; there is no anonymous install or public release download.

- Authenticate with `gh auth login`, then run `gh repo clone okht/zhi ./zhi` into a new directory. Keep the terminal in the directory containing `zhi` for the commands below.
- 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 that read `~/.agents/`: `npx skills add ./zhi/plugins/zhi -a universal -g -y`
- Claude Desktop: upload the checkout's `dist/zhi.zip` under Customize > Skills. This is the Slim bundle below 6 MB.
- Font distribution: authorized testers build `zhi-fonts-full.zip` from the checkout, then pass the local bundle to `bash scripts/ensure-fonts.sh` with `--bundle` and `--approved-only`. Follow the guide for paths and render verification.
- MCP client: `claude mcp add zhi -- python3 <checkout>/scripts/mcp_server.py`

## What ships

Eight document templates: one-pager, letter, long document, portfolio, resume, slides, equity report, changelog. Each exists in Chinese, English, and Korean variants where the typography differs.

Eighteen inline SVG 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.

Nine content schemas under `references/schemas/`: changelog, equity-report, landing-page, letter, long-doc, one-pager, portfolio, resume, slides. Each one states the structure and the quality bar for its document type.

## Agent interfaces

- **Content contracts**: `references/schemas/<type>.json` carries the per-type structure, while `content.json.brief` records the artifact target, preserve boundary, evidence, and acceptance checks. Validate before layout and check coverage after filling: `python3 scripts/build.py --check-content content.json filled.html`.
- **Resume contract**: the Visual guide contains base color and page target only. Pure white and A4 one page are the defaults; warm cream and two pages are optional, and photos are optional. Layout fitting chooses spacing after render, Source protection blocks silent content edits, and the dedicated DOCX adapter validates OOXML plus trusted page count before atomic delivery.
- **Deterministic checks**: placeholders, markdown residue, page density, orphan lines, and slide rhythm, plus 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 `zhi_templates`, `zhi_doctor`, `zhi_render`, `zhi_check`, and `zhi_screenshot`, so an agent can diagnose, render, and verify without loading the skill prompt.
- **Machine-readable site surfaces**: [/llms.txt](https://zhi.cht.me/llms.txt), [/developers.md](https://zhi.cht.me/developers.md), and [/developers/llms.txt](https://zhi.cht.me/developers/llms.txt). Runtime definitions, full source files, and distribution catalogs stay in the authorized checkout during the private preview.

## Pages

- [Homepage](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, 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
- [Source](https://github.com/okht/zhi) - templates, scripts, and skill definition

Localized versions of the homepage: [简体中文](https://zhi.cht.me/index-zh.html), [繁體中文](https://zhi.cht.me/index-tw.html), [日本語](https://zhi.cht.me/index-ja.html), [한국어](https://zhi.cht.me/index-ko.html).

## License

Zhi code and templates are distributed under the MIT license. Font and Matt Pocock skills attribution is preserved in [THIRD_PARTY_NOTICES.md](https://github.com/okht/zhi/blob/main/THIRD_PARTY_NOTICES.md).