Guides

Six guides

Read them in this order the first time. The first one lists what ghola does badly, and that is where I would want to start if somebody handed me this.

Why the limitations come first

Every tool's documentation says what the tool does. That page says what this one does badly, what it refuses to do on purpose, and what has already gone wrong. So it goes first. Deciding against ghola in ten minutes costs you less than finding these out in week two. One item may settle it for you: no configuration removes the pull request.

How much of this you need

Two guides get you working. Read the limitations, run the quickstart, and stop there until something surprises you. The walkthrough is for when it does, because it explains the parts rather than the steps.

The last three are reference, so reach for one when it answers the question in front of you:

  • the ladder, when you are deciding where a rule belongs
  • the customization contract, when you want to change something and cannot find its home
  • evals, before you touch a prompt

That last one matters more than its length suggests, since a prompt is the easiest file here to change and the hardest to check.

Elsewhere

  • PLAN.md is the phased plan: what is built, what each milestone had to prove, and what it taught.
  • examples/ holds two working configurations at opposite ends of the range.
  • settings/ is the reference for the configuration files themselves.
  • iii.dev/docs documents the framework underneath.

The pictures

Every screenshot in these guides is real output, and nobody drew any of it by hand. The console frames come from .tooling/shoot-console.mjs, which holds one page open and shoots it each time a job changes stage. The terminal frames come from .tooling/shoot-terminal.mjs, which runs the make target named in each title bar and photographs its stdout.

cd .tooling && npm install                          # puppeteer, once
node shoot-terminal.mjs ../docs/img/terminal        # needs a running engine
node shoot-console.mjs <job-id> ../docs/img/console # run it beside a live job

Git tracks both scripts, because pictures go stale and the way to retake them should not. Neither one spends money, since shoot-terminal.mjs lists read-only targets only.