GEZHI

# gezhi

Set up this project so future coding-agent work is judged by a rebuilt,
inspectable artifact, not by a summary of source edits.

THE THING is the finished result the user will inspect: a PDF, website, slide
deck, report, chart pack, workbook, benchmark, app demo, or another concrete
output.

Your job is to leave the user with a working `gezhi.toml`, a reliable rebuild
command, and a clear next command. The user should not need to understand
`gezhi` internals to get a first safe setup.

## Division of Labor

This file is the public one-prompt entrypoint. Use it to bootstrap the task,
choose the correct skill, and preserve the non-expert setup contract.

`skills/gezhi-project-setup/SKILL.md` is the detailed execution runbook for
connecting a real project to `gezhi`. If that skill is available, read it
completely and follow it for inspection, artifact choice, producer synthesis,
`gezhi.toml`, validation, and recovery.

`skills/gezhi-template-author/SKILL.md` is only for maintaining reusable
gezhi templates, examples, docs, or skills in the `gezhi` repository. Do
not use it for an ordinary user's project setup.

The sections below are the minimum contract and fallback path when the project
setup skill is unavailable. When the skill is available, use these sections as
scope guardrails, not as a competing checklist.

## Non-Negotiables

- Use live project evidence over README claims.
- If the user already named THE THING, use that artifact.
- If THE THING is not clear, infer it from the project.
- Ask exactly one short question only if you cannot infer the artifact safely.
- Do not edit raw data, generated outputs, build products, `.git/`, or `.gezhi/`.
- Do not edit unrelated docs, READMEs, tests, or source files unless required
  for the setup and clearly within scope.
- Keep future repair write access narrow; generated outputs are not source
  write scopes.
- Do not run a real heartbeat until validation and dry-run checks pass.

## Install Or Verify gezhi

First check:

```bash
gezhi -h
```

If the command is missing, verify Python 3.11+ and install from GitHub:

```bash
python3 --version
python3 -m pip install --upgrade pip
python3 -m pip install "gezhi @ git+https://github.com/SiyaoZheng/GEZHI.git"
```

If `tik.provider = "api"` will be used, install with the OpenAI extra:

```bash
python3 -m pip install "gezhi[openai] @ git+https://github.com/SiyaoZheng/GEZHI.git"
```

API tik defaults to PackyAPI `claude-fable-5`. Credentials may come from
`PACKYAPI_API_KEY`, `PACKYCODE_CODEX_KEY`, `OPENAI_API_KEY`, or
`~/.config/gezhi/api.env`.

If you are already inside a `gezhi` checkout, use the local checkout instead:

```bash
python3 -m pip install -e '.[openai]'
```

Verify again:

```bash
gezhi -h
```

## Fallback Setup Flow

1. Inspect the project root and current Git state.
2. Identify one canonical artifact path for THE THING.
3. Find an existing command that rebuilds it, or create a small producer
   wrapper such as `scripts/goal_producer.sh`.
4. Make the producer fail non-zero when the artifact is missing or empty.
5. Create or update `gezhi.toml`.
6. Choose the smallest useful tik:
   - deterministic `oracle` when a script can reject bad output;
   - command-backed `checklist` when a checklist runner should appear as its
     own tik provider;
   - `codex_file` when Codex can review a local artifact file;
   - `claude_code_file` when Claude Code can review a local artifact file;
   - `api` only when OpenAI-compatible file upload is intended and credentials exist.
7. Configure `tok` with narrow source `write_dirs` as the audited source-change
   scope, `run_cwd = "."` when useful, and generated `runtime_write_dirs` only
   for command side effects. Pick `codex_goal` (Codex exec),
   `codex_app_server` (Codex app-server stdio), or `claude_code_goal`
   (Claude Code) as the provider.
8. Put generated output folders in `[safety].generated_dirs`.
9. If the user asks for unattended long-horizon work, add explicit
   `[perpetual]` and `[lease]` sections so future runs have one fixed
   substantive goal and a narrow file-operation boundary.

## Required Checks

Run these before any real heartbeat:

```bash
gezhi validate
gezhi doctor
```

If using Codex tok:

```bash
gezhi doctor --smoke-codex-goal
```

If using `tok.provider = "codex_app_server"`:

```bash
gezhi doctor --smoke-codex-app-server
```

If using `tok.provider = "claude_code_goal"`:

```bash
gezhi doctor --smoke-claude-code-goal
```

If using `tik.provider = "codex_file"`:

```bash
gezhi doctor --smoke-codex-goal --smoke-codex-file-tik
# or, with tok.provider = "codex_app_server":
gezhi doctor --smoke-codex-app-server --smoke-codex-file-tik
```

If using `tik.provider = "claude_code_file"`:

```bash
gezhi doctor --smoke-claude-code-file-tik
```

If using `tik.provider = "oracle"` or `tik.provider = "checklist"`, the default
doctor run checks the configured command.

Combine the tok and tik smoke flags that match the configured providers; the
all-Claude stack is `--smoke-claude-code-goal --smoke-claude-code-file-tik`.

Run the producer directly and prove the artifact exists:

```bash
scripts/goal_producer.sh
test -s path/to/artifact
```

Then render prompts without changing source:

```bash
gezhi run --dry-run
```

Only after those checks pass, recommend one manual heartbeat:

```bash
gezhi run --max-minutes 600
```

For unattended progress, recommend a timed heartbeat instead. Let gezhi pick
the default wake-up interval unless the project needs a fixed timer: perpetual
goals wake every 5 minutes and legacy goals every 30 minutes.

```bash
gezhi heartbeat install --max-minutes 600
gezhi heartbeat status
```

## Final Report

End by reporting:

- artifact path;
- producer command;
- tik provider and any remaining blocker;
- tok editable folders;
- protected generated folders;
- validation commands run and their result;
- the exact next command for the user.

If setup cannot be completed, do not pretend it is ready. Report the exact
blocking command and output, then give the smallest next action.

## Agent Entry Points

- [Project setup skill](skills/gezhi-project-setup/SKILL.md): Use this to
  connect an existing project to `gezhi`.
- [Template author skill](skills/gezhi-template-author/SKILL.md): Use this
  only when improving reusable examples, checks, or docs in this repository.

## Core Documentation

- [README](README.md): Product overview and one-prompt quick start.
- [Installation](docs/installation.md): Install details and local setup checks.
- [gezhi.toml schema](docs/config-schema.md): Full configuration reference.
- [CLI reference](docs/cli-reference.md): Current command help.
- [Skills guide](docs/skills.md): Agent-facing setup instructions.
- [Architecture](docs/architecture.md): Runtime design
  rationale and module boundaries.

## Examples

- [PDF-first example](examples/scientificity/gezhi.toml): Research-paper setup
  where THE THING is the rebuilt PDF.
- [PDF-first example, Claude Code](examples/scientificity-claude/gezhi.toml):
  The same setup with both tik and tok run by Claude Code; tik reviews via
  the `/apsr-review` slash skill.

## Optional

- [Architecture](docs/architecture.md): Why the final
  output is the control point.
- [Codex goal implementation report](docs/codex-goal-openai-implementation-report.md):
  Codex `/goal` integration details.