docent-doctor

name

docent-doctor

description

First-run bootstrap and ongoing health check for docent. On first invocation, clones the docent engine into ~/.local/share/docent/engine, installs every cascade dependency (uv, ffmpeg, Kokoro voice weights, Remotion), and puts the `docent` CLI on PATH. On subsequent invocations, just runs `docent doctor --install --yes` to verify and repair. Use when the user says "/docent-doctor", asks to set up docent, hits a missing-dependency error from another docent skill, or wants to confirm the cascade can render end-to-end.

docent-doctor — bootstrap or verify the docent environment

You are responsible for getting docent ready to render a film, or for confirming it still is. Two paths to walk depending on whether docent is already on PATH:

Path A — first run (docent not on PATH)

The user just installed the skills via apm install and has never used docent before. You need to clone the engine, bootstrap the cascade, and put the docent CLI on PATH.

Detect this case by running command -v docent. If it returns nothing, take Path A.

Execute these steps in order. Walk through each with the user so they see what's happening; do not paste the whole block silently.

1. Pick the engine location. Default:

   DOCENT_HOME="${XDG_DATA_HOME:-$HOME/.local/share}/docent/engine"
   

   Tell the user this is where the engine will live — about 1 GB after bun install + uv sync + Kokoro weights. They can override by exporting DOCENT_HOME before re-running.

2. Verify bun is on PATH. If command -v bun returns nothing, stop and tell the user:

   docent requires bun. Install it first:
     curl -fsSL https://bun.sh/install | bash
     exec $SHELL -l
   Then re-invoke /docent-doctor.
   

   Bun is the only prerequisite docent itself can't bootstrap (it is the runtime that runs the bootstrap).

3. Clone the engine (or fast-forward an existing clone):

   mkdir -p "$(dirname "$DOCENT_HOME")"
   if [ -d "$DOCENT_HOME/.git" ]; then
     git -C "$DOCENT_HOME" pull --ff-only
   else
     git clone https://github.com/benelser/docent "$DOCENT_HOME"
   fi
   

4. Bootstrap the cascade. This is the long step — uv sync pulls torch + transformers + kokoro, Kokoro downloads ~300 MB of voice weights, and bun install materializes Remotion. Allow 3-8 minutes on a warm machine, longer on a cold one.

   cd "$DOCENT_HOME" && bun packages/agent/scripts/doctor.ts --install --yes
   

   That command installs uv, ffmpeg, gh, apm if missing; writes ~/.local/bin/docent (the shim that lets you call docent <cmd> from any cwd); and records DOCENT_HOME at ~/.config/docent/home. Show the user the live output — every step is labeled.

5. Verify the shim is callable. From the user's original cwd:

   command -v docent && docent env | head -5
   

   If command -v docent returns nothing, the shim is installed but ~/.local/bin is not on PATH. Print:

   Add ~/.local/bin to PATH:
     echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
     exec $SHELL -l
   

   and stop.

6. Hand back. Print:

   • the engine location ($DOCENT_HOME)
   • "Ready" if every required check is green; otherwise list the failing check ids
   • "Next: /docent-explain <subject>" as the next step

Path B — re-verify (docent already on PATH)

The user has docent installed and wants a health check or a repair.

docent doctor --install --yes

This re-runs every check and installs anything missing — Kokoro weights got evicted, node_modules got blown away by a clean-slate, ffmpeg got upgraded oddly, etc. Show the user the raw output (it is already formatted with per-stage grouping and remediation hints on every failure).

If docent doctor exits 0, print Ready and suggest /docent-explain <subject>.

If it exits non-zero, list the failing check ids by stage so the user can resume mid-setup, and explain what each one means in one line.

What "ready" means

Required by cascade stage:

• system: bun, git
• survey: at least one of claude or codex on PATH (the agent that authors the spec); apm (the install channel)
• tts: uv, the .venv materialized, the Kokoro voice weights cached
• render: ffmpeg, ffprobe, Remotion (from bun install), and the docent shim on PATH

Optional (warnings, not failures): gh-auth (interactive — docent ar and the PR poster need it eventually), manim (only films with a manim/<id> directory use it).

Codex-specific install behaviors (worth flagging to the user)

These are not docent bugs — they are how the codex plugin CLI behaves today. Knowing them up front saves debugging time when something is silently wrong:

• marketplace.json source.path must be relative, not absolute. An absolute path is silently accepted by codex plugin marketplace add but codex plugin list -m <name> then shows "no plugins found in marketplace <name>" — no error, no warning. The docent repo's .agents/plugins/marketplace.json uses ./packages/agent (relative) for this reason.
• The marketplace's name: field is the collision key, not the directory path. If the user already has a marketplace named docent (e.g. from a prior install), codex plugin marketplace add <newpath> refuses to add a second one with the same name. They can either codex plugin marketplace remove docent first, or accept that the existing one will be re-resolved.
• codex plugin remove docent-agent leaves the cache dir on disk. Cached files live at ~/.codex/plugins/cache/<marketplace>/. If a re-install gets stuck reading stale skills, the fix is rm -rf ~/.codex/plugins/cache/docent/ and re-running codex plugin add docent-agent@docent.

If the user reports "I installed but /docent-doctor doesn't show up in Codex", check these three before anything else.