# Zhi: developer and agent surface

> Scoped context for integrating Zhi. For the product overview, read https://zhi.cht.me/llms.txt instead.

## Integration model
Zhi is a locally installed skill and template system in private preview, with no formal release yet. There is no hosted Zhi API, Zhi account, or Zhi API key. An authorized GitHub account is required to obtain the private checkout. This domain publishes selected static documentation and samples only.

## When to use
Reach for Zhi when a user wants a finished document whose appearance matters: resume, one-pager, letter, portfolio, long document, slide deck, equity report, changelog, or a product landing page. Skip it when the user only wants the text.

## MCP server
- Start: `python3 scripts/mcp_server.py` (stdio, newline-delimited JSON-RPC 2.0)
- Register: `claude mcp add zhi -- python3 <checkout>/scripts/mcp_server.py`
- Card and runtime definitions: available inside the authorized checkout only.
- Tools: `zhi_templates` (templates, diagrams, schema types), `zhi_doctor` (installed capabilities), `zhi_render` (HTML to PDF), `zhi_check` (stable findings + coverage), `zhi_screenshot` (page PNGs + CJK font verdict + `review_pending` checklist)

## Content contracts
- Schemas: `references/schemas/<type>.json` for changelog, equity-report, landing-page, letter, long-doc, one-pager, portfolio, resume, slides
- Artifact brief: new `content.json` files carry audience, job, output contract, target, preserve boundary, evidence, and acceptance checks under `brief`; older files without it remain valid
- Validate: `python3 scripts/build.py --check-content content.json`
- Coverage into the filled document: `python3 scripts/build.py --check-content content.json filled.html`

## Verification
- Deterministic: `--check-placeholders`, `--check-markdown`, `--check-orphans`, `--check-density`, `--check-rhythm`, `--check-resume-balance`
- Perceptual: `--check-visual` exports page images with a fixed review checklist
- Repository-wide: `python3 scripts/build.py --check` (template lint, token sync, public-fact drift)
- Authoritative command list: `python3 scripts/build.py --help`

## Machine-readable files
- https://zhi.cht.me/developers.md (this surface as prose Markdown)
- https://zhi.cht.me/index.md (homepage as Markdown)
- https://zhi.cht.me/llms.txt (8 document templates, 18 diagram types)
- Full runtime source and distribution catalogs are not public website files during private preview.

## Install
- Guide: https://zhi.cht.me/developers#private-preview. Repository access is required; no public release is available.
- 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: `codex plugin marketplace add ./zhi` then `codex plugin add zhi@zhi`
- Generic agents: `npx skills add ./zhi/plugins/zhi -a universal -g -y`
- Claude Desktop: upload the checkout's Slim `dist/zhi.zip`; it stays below 6 MB and excludes the six approved FangZheng and Charter programs.
- Approved fonts: authorized testers build `zhi-fonts-full.zip` locally, then pass it to `bash scripts/ensure-fonts.sh` with `--bundle` and `--approved-only`. Verify document font paths and rendered glyphs separately.

## Source
https://github.com/okht/zhi (private preview; authorized users only; code and templates retain MIT terms, fonts retain separate notices)