doctor: check your Paqad setup

paqad-ai doctor checks whether Paqad is set up correctly in a project. It reads the files Paqad keeps in the project, runs a list of checks, and prints a report. Every check comes back as pass, warning or fail, and anything that is not a pass comes with a suggested fix.

Doctor only reads. It does not repair anything, and it does not call an AI model: each result is decided by a script, so the same project state always gives the same report.

When to run doctor

• Right after paqad-ai onboard or paqad-ai join, to confirm the setup is complete.
• After upgrading Paqad or running paqad-ai update.
• When an AI tool seems to ignore Paqad, for example when rules or gates never appear.
• In a CI job, as a quick health check on the committed setup.

Synopsis

paqad-ai doctor [--project-root <path>]

--project-root points doctor at another folder. It defaults to the current folder. There is no --json flag, because the output is always JSON.

Reading the report

The report has three parts: an overall_status, the list of checks, and an efficiency block with usage rates. A shortened example:

{
  "overall_status": "warning",
  "checks": [
    {
      "name": "Framework artifacts exist",
      "status": "pass",
      "detail": "Framework artifacts are present"
    },
    {
      "name": "Indexes are current",
      "status": "warning",
      "detail": "Registry scaffold has not been generated yet",
      "remediation": "Run the documentation workflow to generate registries."
    }
  ],
  "efficiency": { ... }
}

• overall_status is fail if any check failed, warning if none failed but at least one warned, and pass otherwise.
• detail says what doctor found. remediation says what to do about it.
• Exit code: doctor exits with 1 when the overall status is fail, and 0 otherwise. Warnings alone do not change the exit code.

What doctor checks

The exact list depends on your setup (for example, extra checks appear when RAG is on), so treat this as a map rather than a fixed count. Check names appear in the report exactly as shown.

Area	Examples of checks
Core files	Framework artifacts exist (the profile and .paqad/framework-path.txt), Profile is valid, Detection report is valid, Onboarding manifest is valid, No broken scaffold state, Stable framework paths only (flags an install that points at a temporary npx location)
Stack	Stack snapshot present, Stack drift report present, Stack commands configured, Test runner parallel mode, Structured test output ready
AI tool setup	Adapter config is present, Entry files point to the framework bootstrap, Codex hooks wired, MCP servers configured
Rules and records	Instruction copies exist, Compiled rules are current, Lean rule footprint acceptable, Decision workspace ready, Module health ledger valid, Classification override rate acceptable
Documentation	Indexes are current (registries refreshed within the last seven days), UI docs present, API docs present, Integration docs present, Error catalog present
Retrieval (RAG)	RAG index present, RAG provider matches profile, RAG secrets gitignore present, RAG secret permissions acceptable, RAG retrieval ready, Context hit rate acceptable
Other features	Spec pipeline is healthy, Expert roster config is coherent, Visual evidence is ready, Skill cache healthy

Limits of what doctor can see

• Doctor checks files on disk. It cannot see settings held inside an AI tool. For Codex, it can confirm that .codex/hooks.json wires Paqad's hooks, but not whether you approved them with /hooks in Codex.
• When Paqad is switched off for a project with paqad-ai disable, the path check passes with a note saying gates and hooks are inactive.
• Doctor checks the Paqad setup, not your code. Auditing the code itself (dead code, risky packages, secrets, stale docs) is a separate command, paqad-ai health.

Using doctor in CI

Because doctor exits with 1 only on a failure, you can use it as a CI step. One thing to know first: some of the records doctor reads are machine-local and git-ignored, including .paqad/detection-report.json, .paqad/stack-snapshot.json and .paqad/stack-drift.json. On a fresh clone those files are missing, so doctor reports failures until the machine has been set up, which is what paqad-ai join does. Run paqad-ai join --no-rag before doctor in the job (--no-rag skips building the optional search index).

To list only the checks that need attention, filter the JSON, for example with jq:

paqad-ai doctor | jq '.checks[] | select(.status != "pass")'