# Zhi for developers and agents

Everything an agent needs to drive Zhi: one local MCP server, nine content schemas, and a set of deterministic checks that decide whether a document is finished.

HTML version: <https://zhi.cht.me/developers.html>

## There is no hosted Zhi API

Zhi is a locally installed skill and template system. Document rendering needs no Zhi account or hosted Zhi API. During private preview, an authorized GitHub account is required to obtain the source. Dependency installation and optional font downloads use their own external sources.

The integration surface is local: an MCP server for tool calls, JSON content schemas for structure, and CLI checks for verification. This website provides selected samples and machine-readable overviews. Runtime definitions, templates, and complete distribution files remain in the private checkout.

## Private preview

Zhi is in private testing, with no formal release or anonymous download. Read this [setup guide](https://zhi.cht.me/developers#private-preview) and ask the repository owner for access before continuing. Use your authorized GitHub account and clone into a new directory. Keep the terminal in the directory containing `zhi` for the commands below. Choose your client; Claude Code slash commands run inside Claude Code.

```
# Authenticate and clone the private repository
gh auth login
gh repo clone okht/zhi ./zhi

# Claude Code (v2.1.142+)
/plugin marketplace add ./zhi
/plugin install zhi@zhi

# Codex plugin marketplace
codex plugin marketplace add ./zhi
codex plugin add zhi@zhi

# Generic agents that read ~/.agents/
npx skills add ./zhi/plugins/zhi -a universal -g -y

# MCP client, from a checkout
claude mcp add zhi -- python3 <checkout>/scripts/mcp_server.py
```

Claude Desktop: upload `zhi/dist/zhi.zip` from the authorized checkout under Customize > Skills. This Slim archive stays below 6 MB and excludes the six approved FangZheng and Charter font programs. It is not a public download.

For Chinese and English font testing, authorized users can build `zhi-fonts-full.zip` locally with Python 3 and Bash. Then run the installed skill's `scripts/ensure-fonts.sh` with the local bundle path. Replace `<installed-skill>` with the actual installation directory:

```bash
bash ./zhi/scripts/package-skill.sh --full-fonts
bash <installed-skill>/scripts/ensure-fonts.sh --bundle ./zhi/dist/zhi-fonts-full.zip --approved-only
```

The installer verifies all six separate font programs against the manifest. `--approved-only` covers Chinese and Latin fonts; Korean and other fallback fonts need their documented setup. Before rendering, make each document's local `@font-face` paths resolve and verify the PDF's actual fonts and glyphs. Installing fonts alone does not complete visual verification.

Keep your authenticated checkout for updates. Pull changes there and refresh the local marketplace or replace the Desktop ZIP. Automatic public release downloads are unavailable during private preview.

## MCP tools

The server speaks newline-delimited JSON-RPC 2.0 over stdio and has no third-party dependency for the protocol itself. Tools that need WeasyPrint, pypdf, or PyMuPDF surface the install hint as a tool error instead of crashing.

| Tool | What it does |
| --- | --- |
| `zhi_templates` | List document templates, browser-only templates, the diagram library, and content schema types, with the reference docs to read before filling. |
| `zhi_doctor` | Report installed PDF, visual-check, editable-PPTX, and font capabilities. Unavailable engines are reported explicitly. |
| `zhi_render` | Render trusted local HTML to PDF with WeasyPrint and syntax highlighting. Return the PDF path and page count. |
| `zhi_check` | Run the deterministic checks for a file. Returns the readable report plus stable rule IDs, findings, engine coverage, and explicit degraded checks. |
| `zhi_screenshot` | Rasterize every PDF page to PNG and return the paths, deterministic CJK font verdict, and a `review_pending` checklist contract for the perceptual pass. |

The server card, including protocol version and tool list, is available in the authorized checkout.

## Content schemas

Nine schemas live under `references/schemas/`: changelog, equity-report, landing-page, letter, long-doc, one-pager, portfolio, resume, slides. Each states the structure and the quality bar for its type. A new `content.json` also carries a `brief` with audience, job, output contract, target, preserve boundary, evidence, and acceptance checks; older IR files remain valid. Fill the schema first, lay out second.

```
python3 scripts/build.py --check-content content.json
python3 scripts/build.py --check-content content.json filled.html
```

The second form reports coverage: fields that exist in the content object but never reached the document. That is the most common failure in agent-generated layouts and it is invisible to a human skim.

## Checks

- `--check-placeholders` - unfilled template text still in the document.
- `--check-markdown` - markdown syntax that leaked into the rendered output.
- `--check-orphans` - single lines stranded at a page break.
- `--check-density` - pages ending with more than a quarter of the page empty.
- `--check-rhythm` - slide sequences that repeat one layout too many times.
- `--check-resume-balance` - column and section balance in a resume.
- `--check-visual` - exports page images and returns a fixed review checklist for a perceptual pass.

`python3 scripts/build.py --help` is the authoritative list. Repository-wide checks, `python3 scripts/build.py --check`, cover template lint, design-token sync, and public-site fact drift.

## Machine-readable files

- [/llms.txt](https://zhi.cht.me/llms.txt) - product summary, install commands, and when an agent should reach for Zhi.
- [/index.md](https://zhi.cht.me/index.md) - the homepage as Markdown. Read this directly linked Markdown file.
- [/developers.md](https://zhi.cht.me/developers.md) - this page as Markdown.
- [/developers/llms.txt](https://zhi.cht.me/developers/llms.txt) - the developer surface on its own.
- [/sitemap.xml](https://zhi.cht.me/sitemap.xml) and [/robots.txt](https://zhi.cht.me/robots.txt) - crawl surface and AI crawler policy.

## Elsewhere

[Home](https://zhi.cht.me/) · [About](https://zhi.cht.me/about.html) · [Contact](https://zhi.cht.me/contact.html) · [Privacy](https://zhi.cht.me/privacy.html) · [Source](https://github.com/okht/zhi)