Fix Paqad setup problems with paqad-ai doctor

This page is about using paqad-ai doctor to find and fix problems. For the command's options, see the doctor command reference.

When to run doctor

Right after onboarding, and after a teammate runs paqad-ai join on a new machine.
After upgrading Paqad, or after editing the profile or settings files by hand.
When hooks seem not to fire, the AI seems not to load Paqad, or a check fails for no obvious reason.
In CI, to catch a broken setup before it reaches the team.

doctor is a script. It reads files in your project and gives the same answer every time; it does not ask an AI anything and changes nothing.

Run it and read the report

paqad-ai doctor

The output is always JSON. An abridged example from a newly onboarded project:

{
  "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": {
    "context_hit_rate": 0,
    "skill_cache_hit_rate": 0,
    "mcp_usage_rate": 0
  }
}

overall_status is fail if any check failed, warning if any check warned, otherwise pass.
Each entry in checks has a name, a status, a detail saying what was found, and, for warnings and failures, a remediation with the suggested fix.
The exit code is 1 only when overall_status is fail. Warnings exit with 0.
efficiency reports rates read from Paqad's own log files. In 1.91.1 mcp_usage_rate is always 0.

There are around forty named checks. The exact number depends on what is switched on; for example, the search-index checks all pass with "RAG is disabled" until you enable RAG. To see only the checks that need attention, you can filter the output with a JSON tool such as jq:

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

Common findings and how to fix them

Check name	What it usually means	What to do
Framework artifacts exist (fail)	`.paqad/project-profile.yaml` or `.paqad/framework-path.txt` is missing	Run `paqad-ai onboard`
Detection report is valid, Stack snapshot present, Stack drift report present (fail)	These per-machine files are not in git, so a fresh clone lacks them	Run `paqad-ai join`, or `paqad-ai refresh --stack`
Profile is valid (fail)	A hand edit put an invalid field or value in the profile	Fix the field named in `detail`
Stack commands configured (fail)	A command in the profile's `commands` block is empty	Fill it in; see Project profile
Instruction copies exist (fail)	`docs/instructions/rules/` or your stack's tool guides are missing	Run `paqad-ai onboard` again; it rewrites only missing files
Entry files point to the framework bootstrap (fail or warning)	An entry file such as `CLAUDE.md` no longer mentions `.paqad/framework-path.txt`, or still carries an old, long format	Run `paqad-ai refresh --providers` (the suggested fix in the report says `paqad refresh --providers`; the command is `paqad-ai`)
Codex hooks wired (warning)	`.codex/hooks.json` is missing or incomplete	Run onboarding with the `codex-cli` tool, then open Codex, run `/hooks` and approve Paqad's hooks
Stable framework paths only (fail)	The pointer file names a temporary install location	Install globally with `npm install -g paqad-ai` and onboard again
Compiled rules are current (fail)	Rules in `docs/instructions/rules/` changed after Paqad last compiled them, so the AI could be given outdated rule text	Run `paqad-ai rag refresh-context`
Indexes are current (warning)	The documentation registries have not been generated, or are more than seven days old	Prompt your AI tool with `create documentation`
MCP servers configured (warning)	No MCP file was found, or servers recommended for your stack are missing from it	Re-run onboarding, or add the servers named in `detail`
No broken scaffold state (fail)	A file ending in `.partial` or `.tmp` exists somewhere in the project folder, including folders such as `node_modules`	Delete the files listed in `detail`
RAG index present, RAG chunk index current and other RAG checks (warning)	RAG is on but the index is missing or out of date	Run `paqad-ai rag init` or `paqad-ai rag rebuild`, as the check suggests

Warnings that are normal on a new project

Indexes are current warns until the create documentation workflow has run.
Skill cache healthy warns when .paqad/cache/skill-results does not exist. It does not block anything. Its suggested fix names a script, skill-cache-manager.sh, that is not included in paqad-ai 1.91.1, so you can treat this warning as information only.
Structured test output ready warns when your stack pack declares no test runner. In 1.91.1 that is the case for the dotnet, flask, kotlin-android, nestjs and nextjs packs. Test results are then read as plain text; see Structured test output.
Test runner parallel mode warns when your tests can only run one after another, and names the package that would allow parallel runs where one exists.

What doctor does not check

It does not compare your documentation with your code. It checks that the right files exist and are readable.
"Stack drift report present" only confirms the drift file exists and can be read. To see whether your stack actually changed, read .paqad/stack-drift.json (see Drift detection).
It cannot see inside your AI tool. For example, it can confirm .codex/hooks.json is complete, but not whether you approved the hooks in Codex.

Using doctor in CI

Because doctor exits with 1 only on a failure, you can add it as a CI step to stop on a broken setup while letting warnings through. On a CI machine, run paqad-ai join --no-rag first so the per-machine files exist without building a search index; otherwise the detection and snapshot checks fail. join asks no questions unless you pass --interactive.

Diagnosing problems with doctor