doctor: install and verify

When to use it

• First contact: a machine or repo that has never run okf. Every other verb assumes the CLI is installed; doctor is the one playbook that does not.
• The toolchain misbehaves: the gem installed but the command is not found, or you want a quick health read on the bundle.
• orient routes here on its own when okf --version fails.

What the agent does

Doctor works through four stations in order, reports what it finds at each, and asks before any install that touches your system.

1. Is the CLI already here? okf --version. If a version prints, the agent skips straight to the bundle check.
2. Install the gem. The agent finds a Ruby first: anything 2.4 or newer works, so whatever the OS or a version manager already ships is enough (ruby --version, then rbenv versions, asdf list ruby, mise ls ruby if absent). In a repo with a Gemfile where okf belongs to the project, it uses bundle add okf and bundle exec okf from then on; otherwise gem install okf. It verifies with okf --version before moving on, and it knows the failure modes in order of likelihood:
   • okf: command not found right after a successful install means the gem bindir is not on PATH. ruby -e 'puts Gem.bindir' shows where the executable landed; a PATH entry or a shim refresh (rbenv rehash, asdf reshim ruby) fixes it.
   • A permission error on the system Ruby never gets sudo. gem install --user-install okf plus $(ruby -e 'puts Gem.user_dir')/bin on PATH does the same job safely.
   • On Windows, a RubyInstaller Ruby works; the executable is okf.bat under the gem bindir, run from the same shell that has ruby on PATH.
3. Doctor the bundle. The agent locates a bundle: the target you named, which can be a directory or a registry reference (@slug for a registered bundle, a bare @ for the registry default), else .okf/, else a root index.md carrying okf_version. It then runs okf validate and okf lint, and summarizes in a few lines: conformant or not (with the errors if not), the warning count, and the top curation findings by category. Nothing in the cwd? The next move is okf registry list, since the bundles you work with are usually registered rather than sitting in a sibling directory. Still nothing, and it offers to bootstrap one through produce, scaffolding nothing without your yes.
4. Say what changes now. A short orientation on the new state. With the Claude Code plugin active, every Write or Edit inside a bundle runs validate and lint automatically and returns the findings as context, and /okf:gem curate runs the full curation cycle on demand. Without the plugin, the skill itself instructs the agent to run the same checks after editing a bundle.

Try it

In Claude Code with the okf plugin, run /okf:gem doctor, or ask the skill in plain words:

Set up the okf CLI on this machine and check the health of the knowledge bundle in this repo.

Pitfalls

• Doctor asks before installing. Anything that touches your system (a gem install, a PATH change) waits for a yes; the read-only checks it just runs.
• Never sudo. A permission error on the system Ruby means --user-install, not elevated privileges.
• "Installed but not found" is a PATH problem, not a broken gem. The fix is Gem.bindir on PATH or a shim refresh, not a reinstall.
• No bundle is not a failure. Doctor reports the absence and offers produce; it never scaffolds a bundle unasked.