supered 0.2.0 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Small, evidence-first workflows for coding agents.",
   "author": {
     "name": "Farouk Hajjej",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A compact agent workflow kit for clarifying, building, verifying, and shipping software changes.",
   "author": {
     "name": "Farouk Hajjej",

package/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "supered",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Small, evidence-first workflows for coding agents.",
   "homepage": "https://fhajjej-ship-it.github.io/Supered/",
   "license": "MIT",

package/README.md

@@ -30,6 +30,12 @@ Install with npx:
 npx supered install --target codex
 ```
 
+Check the install:
+
+```bash
+npx supered doctor --target codex
+```
+
 Or install the default Codex skill set with curl:
 
 ```bash
@@ -50,6 +56,7 @@ cd Supered
 npm test
 npm run validate
 node ./bin/supered.mjs install --target codex
+node ./bin/supered.mjs doctor --target codex
 ```
 
 For Claude or Gemini, replace `codex` with `claude` or `gemini`.
@@ -63,6 +70,25 @@ Host-specific notes:
 
 Marketplace readiness lives in [docs/marketplace-checklist.md](docs/marketplace-checklist.md).
 
+## Which Skill Should I Use?
+
+Use [docs/which-skill.md](docs/which-skill.md) as the quick router:
+
+- unclear task: `shape-the-task`
+- clear but large task: `make-a-map`
+- planned implementation: `build-in-slices`
+- broken or flaky behavior: `trace-the-fault`
+- completion claim: `prove-the-change`
+- commit, publish, or handoff: `ship-the-work`
+
+## Eval Pack
+
+Supered includes a public eval pack so the skills can be judged against realistic work instead of vibes.
+
+- [Scenario catalog](docs/evals/scenarios.json): 10 realistic coding-agent scenarios.
+- [Baseline results](docs/evals/baseline-results.json): scores across clarity, actionability, guardrails, evidence, and outcome.
+- [Eval report](docs/evals/README.md): how to use the scenarios to improve the skills.
+
 ## CLI
 
 ```bash
@@ -72,13 +98,14 @@ npm run smoke-install
 npm run verify-site
 npm run verify-package
 node ./bin/supered.mjs skills --json
+node ./bin/supered.mjs doctor --target codex --json
 ```
 
 The validator checks package metadata, plugin metadata, and skill frontmatter so the public repo does not drift into a half-installable state.
 
 `npm run verify-site` opens the landing page in Chromium at desktop and mobile sizes, checks the logo and workflow text, and writes screenshots to `artifacts/site/`.
 
-`npm run verify-package` builds the npm tarball and verifies `npx`-style installs for every supported host target.
+`npm run verify-package` builds the npm tarball and verifies `npx`-style installs plus Doctor checks for every supported host target.
 
 ## Design Principles
 

package/bin/supered.mjs

@@ -1,19 +1,14 @@
 #!/usr/bin/env node
-import { cp, mkdir } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { listSkills, validateProject } from "../lib/manifest.js";
+import { installSuperedSkills } from "../lib/host-install.js";
+import { inspectSuperedInstall } from "../lib/install-doctor.js";
+import { listSkills } from "../lib/manifest.js";
+import { validateReleaseBundle } from "../lib/release-bundle.js";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const [command, ...args] = process.argv.slice(2);
-const installTargets = {
-  codex: ".codex/skills",
-  claude: ".claude/skills",
-  cursor: ".cursor/skills",
-  gemini: ".gemini/skills",
-  opencode: ".opencode/skills"
-};
 
 function printHelp() {
   console.log(`Supered
@@ -22,10 +17,12 @@ Usage:
   supered skills [--json]
   supered validate
   supered install --target <codex|claude|cursor|gemini|opencode> [--dest <path>]
+  supered doctor --target <codex|claude|cursor|gemini|opencode> [--dest <path>] [--json]
 
 Examples:
   npx supered install --target codex
   npx supered install --target gemini --dest ~/.gemini/skills
+  supered doctor --target codex
 `);
 }
 
@@ -42,7 +39,7 @@ async function skillsCommand() {
 }
 
 async function validateCommand() {
-  const result = await validateProject(root);
+  const result = await validateReleaseBundle(root);
   if (result.errors.length > 0) {
     for (const error of result.errors) {
       console.error(`- ${error}`);
@@ -54,29 +51,52 @@ async function validateCommand() {
   console.log(`Supered bundle is valid: ${result.skills.length} skills, ${result.checked.length} files checked.`);
 }
 
-function defaultInstallDest(target) {
-  const home = process.env.HOME;
-  if (!home) {
-    throw new Error("HOME is not set; pass --dest explicitly.");
+async function installCommand() {
+  const targetIndex = args.indexOf("--target");
+  const destIndex = args.indexOf("--dest");
+  const target = targetIndex === -1 ? "" : args[targetIndex + 1];
+  const dest = destIndex === -1 ? undefined : args[destIndex + 1];
+
+  if (!target || (destIndex !== -1 && !dest)) {
+    throw new Error("Install requires --target <codex|claude|cursor|gemini|opencode>.");
   }
 
-  if (installTargets[target]) return `${home}/${installTargets[target]}`;
-  throw new Error(`Unsupported target: ${target}`);
+  const result = await installSuperedSkills({ root, target, dest });
+  console.log(`Installed Supered skills for ${result.target} at ${result.dest}.`);
 }
 
-async function installCommand() {
+async function doctorCommand() {
   const targetIndex = args.indexOf("--target");
   const destIndex = args.indexOf("--dest");
   const target = targetIndex === -1 ? "" : args[targetIndex + 1];
-  const dest = destIndex === -1 ? defaultInstallDest(target) : args[destIndex + 1];
+  const dest = destIndex === -1 ? undefined : args[destIndex + 1];
+  const json = args.includes("--json");
 
-  if (!target || !dest) {
-    throw new Error("Install requires --target <codex|claude|cursor|gemini|opencode>.");
+  if (!target || (destIndex !== -1 && !dest)) {
+    throw new Error("Doctor requires --target <codex|claude|cursor|gemini|opencode>.");
   }
 
-  await mkdir(dest, { recursive: true });
-  await cp(resolve(root, "skills"), dest, { recursive: true });
-  console.log(`Installed Supered skills for ${target} at ${dest}.`);
+  const result = await inspectSuperedInstall({ root, target, dest });
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    if (result.status !== "ok") {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (result.status === "ok") {
+    console.log(`Supered doctor passed for ${result.target} at ${result.dest}.`);
+    console.log(`${result.installedSkills.length} skills installed and current.`);
+    return;
+  }
+
+  console.log(`Supered doctor found ${result.issues.length} issue${result.issues.length === 1 ? "" : "s"} for ${result.target} at ${result.dest}.`);
+  for (const installIssue of result.issues) {
+    console.log(`- [${installIssue.code}] ${installIssue.message}`);
+  }
+  console.log(`Fix: ${result.fixCommand}`);
+  process.exitCode = 1;
 }
 
 try {
@@ -88,6 +108,8 @@ try {
     await validateCommand();
   } else if (command === "install") {
     await installCommand();
+  } else if (command === "doctor") {
+    await doctorCommand();
   } else {
     throw new Error(`Unknown command: ${command}`);
   }

package/docs/evals/README.md

@@ -0,0 +1,34 @@
+# Supered Eval Pack
+
+This pack gives Supered a visible usefulness standard: 10 realistic coding-agent scenarios, a simple scoring rubric, and baseline results for the current skill set.
+
+The goal is not to claim scientific benchmark status. The goal is to make the product falsifiable: a reader can see what the skills are supposed to help with, how outcomes are judged, and where the current library is strong or still dependent on project context.
+
+## Files
+
+- [scenarios.json](scenarios.json): 10 realistic coding-agent scenarios with prompts, context, primary skills, success criteria, and expected evidence.
+- [baseline-results.json](baseline-results.json): maintainer-scored baseline results for Supered v0.2.0.
+
+## Scoring
+
+Each scenario is scored from 1 to 5 across five dimensions:
+
+- `clarity`: the skill helps the agent understand what kind of work this is.
+- `actionability`: the skill tells the agent what to do next, not just how to think.
+- `guardrails`: the skill prevents common bad moves such as scope creep, guessing, or premature claims.
+- `evidence`: the skill asks for proof before completion or handoff.
+- `outcome`: the skill increases the chance of a useful user-facing result.
+
+## Baseline Summary
+
+The current baseline average is `4.58 / 5` across the catalog. Strongest areas are release handoff, verification, and fault tracing. The scenarios with lower scores are intentionally product-heavy or environment-dependent, where a skill can guide the agent but cannot replace user priorities, browser access, database access, or security review.
+
+## How To Use It
+
+1. Pick a scenario close to your real task.
+2. Ask an agent to use the recommended Supered skill.
+3. Score the result against the five dimensions.
+4. Add notes when the skill was vague, too strict, or missing a useful recovery path.
+5. Propose a skill improvement or a new scenario when the score exposes a real gap.
+
+This gives contributors a practical way to improve Supered without turning the project into a pile of opinions.

package/docs/evals/baseline-results.json

@@ -0,0 +1,132 @@
+{
+  "product": "Supered",
+  "catalogVersion": "0.1",
+  "summary": {
+    "averageScore": 4.58,
+    "scenarioCount": 10,
+    "scoreScale": "1-5",
+    "method": "Maintainer review of the v0.2.0 Supered skill bodies against the scenario catalog. Scores are intentionally conservative until external user studies exist."
+  },
+  "results": [
+    {
+      "scenarioId": "S01",
+      "recommendedSkill": "shape-the-task",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 4,
+        "evidence": 4,
+        "outcome": 5
+      },
+      "notes": "The skill asks for users, constraints, assumptions, and acceptance signals before implementation, which directly prevents dashboard overreach. Evidence is strong but still depends on user confirmation."
+    },
+    {
+      "scenarioId": "S02",
+      "recommendedSkill": "make-a-map",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 4,
+        "outcome": 5
+      },
+      "notes": "The mapping playbook fits multi-file auth work well because it forces affected areas, checkpoints, and verification commands before edits. External security review may still be needed."
+    },
+    {
+      "scenarioId": "S03",
+      "recommendedSkill": "build-in-slices",
+      "scores": {
+        "clarity": 4,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 4,
+        "outcome": 4
+      },
+      "notes": "The slice discipline prevents a settings redesign from swallowing the small save-confirmation task. The score is slightly lower because visual quality still needs domain judgment."
+    },
+    {
+      "scenarioId": "S04",
+      "recommendedSkill": "trace-the-fault",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 4
+      },
+      "notes": "The fault-tracing skill is strongest on this scenario: it demands symptom capture, hypotheses, probes, and proof before patches. The remaining risk is platform access to mobile Safari."
+    },
+    {
+      "scenarioId": "S05",
+      "recommendedSkill": "prove-the-change",
+      "scores": {
+        "clarity": 5,
+        "actionability": 4,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 5
+      },
+      "notes": "The verification skill explicitly blocks premature completion claims and requires fresh proof. Actionability is high, though the exact export check depends on the app's local tooling."
+    },
+    {
+      "scenarioId": "S06",
+      "recommendedSkill": "ship-the-work",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 5
+      },
+      "notes": "The shipping skill aligns directly with public release work: clean status, intended staging, verification, push, release, and public read-back. It is the best fit in the catalog."
+    },
+    {
+      "scenarioId": "S07",
+      "recommendedSkill": "using-supered",
+      "scores": {
+        "clarity": 4,
+        "actionability": 5,
+        "guardrails": 4,
+        "evidence": 4,
+        "outcome": 4
+      },
+      "notes": "The entrypoint helps route a messy request into a first useful workflow instead of trying everything. The score is lower because the request still requires product prioritization."
+    },
+    {
+      "scenarioId": "S08",
+      "recommendedSkill": "trace-the-fault",
+      "scores": {
+        "clarity": 5,
+        "actionability": 5,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 4
+      },
+      "notes": "CI recovery benefits from the same diagnosis discipline: start from logs, reproduce, isolate, then patch. Outcome depends on whether the CI failure can be reproduced locally."
+    },
+    {
+      "scenarioId": "S09",
+      "recommendedSkill": "make-a-map",
+      "scores": {
+        "clarity": 4,
+        "actionability": 5,
+        "guardrails": 4,
+        "evidence": 5,
+        "outcome": 4
+      },
+      "notes": "The map-and-slice combination handles migration risk well by separating schema, data, and route compatibility. Database-specific rollback details remain project dependent."
+    },
+    {
+      "scenarioId": "S10",
+      "recommendedSkill": "ship-the-work",
+      "scores": {
+        "clarity": 5,
+        "actionability": 4,
+        "guardrails": 5,
+        "evidence": 5,
+        "outcome": 4
+      },
+      "notes": "The handoff scenario is well covered because the skill values honest status over false completion. It needs local judgment about whether to commit partial work or leave notes only."
+    }
+  ]
+}

package/docs/evals/scenarios.json

@@ -0,0 +1,212 @@
+{
+  "product": "Supered",
+  "version": "0.1",
+  "description": "A compact public catalog of realistic coding-agent scenarios for checking whether Supered skills are useful in practice.",
+  "scoring": {
+    "maxScore": 5,
+    "dimensions": [
+      "clarity",
+      "actionability",
+      "guardrails",
+      "evidence",
+      "outcome"
+    ],
+    "rubric": {
+      "1": "Absent or actively misleading.",
+      "2": "Present but too vague to guide reliable work.",
+      "3": "Usable with noticeable gaps or extra human correction.",
+      "4": "Strong enough for normal work with minor judgment required.",
+      "5": "Excellent: specific, safe, evidence-driven, and ready to apply."
+    }
+  },
+  "scenarios": [
+    {
+      "id": "S01",
+      "title": "Turn a vague feature request into a buildable slice",
+      "prompt": "Add dashboards for customers so they can understand account health, but keep it simple and do not overbuild it.",
+      "context": "The repo has a React admin app, no product requirements document, three possible user roles, and no obvious owner for metric definitions. The agent must avoid inventing a large analytics system.",
+      "primarySkills": [
+        "using-supered",
+        "shape-the-task"
+      ],
+      "successCriteria": [
+        "Clarifies the target user, first workflow, and non-goals.",
+        "Produces a short brief that can be accepted or corrected.",
+        "Identifies the smallest useful dashboard slice before implementation."
+      ],
+      "expectedEvidence": [
+        "A concise task brief with assumptions called out.",
+        "A list of decisions that need user confirmation before code changes."
+      ]
+    },
+    {
+      "id": "S02",
+      "title": "Map a multi-file authentication change",
+      "prompt": "Add magic-link login to the existing app and make sure the old password login still works.",
+      "context": "The app has API routes, an email sender, session middleware, and browser tests. The request touches security-sensitive paths and must be broken into reviewable changes.",
+      "primarySkills": [
+        "make-a-map",
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Lists affected files and ownership boundaries before editing.",
+        "Sequences backend, email, session, and UI work into small checkpoints.",
+        "Names verification commands for old and new login paths."
+      ],
+      "expectedEvidence": [
+        "A short execution map with ordered slices.",
+        "Verification notes covering both magic-link and password login."
+      ]
+    },
+    {
+      "id": "S03",
+      "title": "Implement a narrow UI improvement without scope creep",
+      "prompt": "Make the settings page easier to scan and add a save confirmation when preferences change.",
+      "context": "The settings page is already used by customers, has mixed form components, and has a brittle screenshot test. The agent should improve the workflow without redesigning the app.",
+      "primarySkills": [
+        "build-in-slices"
+      ],
+      "successCriteria": [
+        "Starts with one visible behavior and one verification path.",
+        "Keeps layout and interaction edits separable.",
+        "Avoids unrelated visual redesign or component churn."
+      ],
+      "expectedEvidence": [
+        "A small diff grouped around the settings workflow.",
+        "Passing component or browser verification for the save confirmation."
+      ]
+    },
+    {
+      "id": "S04",
+      "title": "Diagnose an intermittent checkout failure",
+      "prompt": "Checkout sometimes fails with a generic payment error, mostly on mobile Safari. Fix it.",
+      "context": "Logs show several possible causes: token refresh, double-submit, gateway declines, and a recent UI refactor. The agent must investigate before changing code.",
+      "primarySkills": [
+        "trace-the-fault"
+      ],
+      "successCriteria": [
+        "Separates symptom, reproduction attempts, and hypotheses.",
+        "Finds evidence for one root cause before patching.",
+        "Adds or updates a regression check for the observed failure."
+      ],
+      "expectedEvidence": [
+        "A fault trace showing ruled-out hypotheses.",
+        "A failing-then-passing check or a documented reproduction result."
+      ]
+    },
+    {
+      "id": "S05",
+      "title": "Prove a production bug fix before claiming completion",
+      "prompt": "The export button is fixed now, right? Tell the customer we are done and include the exact proof that the filtered CSV download works.",
+      "context": "A prior agent changed CSV generation but did not run the browser workflow. The customer issue involves filters, permissions, and a downloaded file.",
+      "primarySkills": [
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Refuses to claim completion from code changes alone.",
+        "Runs the relevant automated or manual export verification.",
+        "Reports the actual evidence and any untested risk."
+      ],
+      "expectedEvidence": [
+        "Fresh command output or browser verification notes.",
+        "A final status that distinguishes verified behavior from assumptions."
+      ]
+    },
+    {
+      "id": "S06",
+      "title": "Prepare a small public release",
+      "prompt": "Commit this library update, push it, tag a release, and make sure the public install instructions still work.",
+      "context": "The repo is public, has CI, a package manifest, generated screenshots, and possible uncommitted user files. The agent must not overwrite unrelated work.",
+      "primarySkills": [
+        "ship-the-work",
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Checks the worktree and stages only intended files.",
+        "Runs release-relevant validation before tagging or publishing.",
+        "Reads back the public release or install path after shipping."
+      ],
+      "expectedEvidence": [
+        "Git status, commit, push, and release URLs.",
+        "Public install or package registry verification."
+      ]
+    },
+    {
+      "id": "S07",
+      "title": "Choose the right workflow for a mixed request",
+      "prompt": "The app is slow, the nav is confusing, and we should probably add AI summaries. Can you just improve it?",
+      "context": "The request mixes performance, design, and new AI features. The agent needs to route the session instead of starting a broad refactor.",
+      "primarySkills": [
+        "using-supered",
+        "shape-the-task"
+      ],
+      "successCriteria": [
+        "Identifies separate work types and risks.",
+        "Chooses a first skill based on the highest uncertainty.",
+        "Offers a narrow next action instead of starting all tasks at once."
+      ],
+      "expectedEvidence": [
+        "A routing decision with the chosen Supered skill.",
+        "A short set of questions or assumptions that unblock the first slice."
+      ]
+    },
+    {
+      "id": "S08",
+      "title": "Recover from a failing CI run",
+      "prompt": "CI is red after the last push. Please inspect the failed job, fix the real cause, and keep the intended feature intact.",
+      "context": "The failure could come from tests, packaging, linting, or browser setup. The agent must inspect the failed job and avoid local-only guesses.",
+      "primarySkills": [
+        "trace-the-fault",
+        "build-in-slices"
+      ],
+      "successCriteria": [
+        "Starts from the failing CI evidence.",
+        "Reproduces or narrows the failure locally before editing.",
+        "Makes the smallest fix that preserves the intended feature."
+      ],
+      "expectedEvidence": [
+        "CI log excerpt or command that identifies the failure point.",
+        "A passing local check and, when possible, a green rerun."
+      ]
+    },
+    {
+      "id": "S09",
+      "title": "Add tests around a risky data migration",
+      "prompt": "Add a migration that backfills missing organization slugs without breaking existing URLs.",
+      "context": "The database has legacy rows, duplicate display names, and routing code that assumes slugs are stable. The migration needs a reversible plan and proof.",
+      "primarySkills": [
+        "make-a-map",
+        "build-in-slices",
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Maps schema, data, and route changes before implementation.",
+        "Builds the migration and app compatibility in separate slices.",
+        "Verifies duplicate and legacy-row cases explicitly."
+      ],
+      "expectedEvidence": [
+        "Migration test cases or dry-run output for edge cases.",
+        "Application route checks for old and new organization URLs."
+      ]
+    },
+    {
+      "id": "S10",
+      "title": "Hand off unfinished work honestly",
+      "prompt": "I need to stop here. Leave the branch in a state another engineer can continue from.",
+      "context": "The agent has partial implementation, one failing test, and two unverified assumptions. The handoff must be useful without pretending the work is done.",
+      "primarySkills": [
+        "ship-the-work",
+        "prove-the-change"
+      ],
+      "successCriteria": [
+        "Separates completed, partial, and unstarted work.",
+        "Lists failing or skipped checks clearly.",
+        "Leaves next steps and evidence paths for the next engineer."
+      ],
+      "expectedEvidence": [
+        "A handoff note with known status and blockers.",
+        "Command output showing the current failing or passing checks."
+      ]
+    }
+  ]
+}

package/docs/index.html

@@ -15,6 +15,7 @@
       </a>
       <nav>
         <a href="#skills">Skills</a>
+        <a href="#proof">Proof</a>
         <a href="#install">Install</a>
         <a href="https://github.com/fhajjej-ship-it/Supered">GitHub</a>
       </nav>
@@ -65,6 +66,28 @@
         </div>
       </section>
 
+      <section id="proof" class="proof" aria-labelledby="proof-title">
+        <div class="section-head">
+          <p class="eyebrow">Proof</p>
+          <h2 id="proof-title">Eval pack, not vibes.</h2>
+          <p>Supered ships with 10 realistic coding-agent scenarios and a baseline scoring pass across clarity, actionability, guardrails, evidence, and outcome.</p>
+        </div>
+        <div class="proof-grid">
+          <a href="https://github.com/fhajjej-ship-it/Supered/blob/main/docs/which-skill.md">
+            <span>Guide</span>
+            <strong>Which skill should I use?</strong>
+          </a>
+          <a href="https://github.com/fhajjej-ship-it/Supered/blob/main/docs/evals/scenarios.json">
+            <span>Catalog</span>
+            <strong>10 realistic coding-agent scenarios</strong>
+          </a>
+          <a href="https://github.com/fhajjej-ship-it/Supered/blob/main/docs/evals/README.md">
+            <span>Eval pack</span>
+            <strong>How usefulness is scored</strong>
+          </a>
+        </div>
+      </section>
+
       <section id="install" class="install" aria-labelledby="install-title">
         <div>
           <p class="eyebrow">Install</p>

package/docs/install.md

@@ -6,12 +6,14 @@ Supered ships plain skill folders plus lightweight plugin manifests.
 
 ```bash
 npx supered install --target codex
+npx supered doctor --target codex
 ```
 
 Choose another host:
 
 ```bash
 npx supered install --target opencode
+npx supered doctor --target opencode
 ```
 
 ## One-line install
@@ -30,20 +32,34 @@ curl -fsSL https://raw.githubusercontent.com/fhajjej-ship-it/Supered/main/instal
 
 ```bash
 node ./bin/supered.mjs install --target codex
+node ./bin/supered.mjs doctor --target codex
 ```
 
 ## Claude
 
 ```bash
 node ./bin/supered.mjs install --target claude
+node ./bin/supered.mjs doctor --target claude
 ```
 
 ## Gemini
 
 ```bash
 node ./bin/supered.mjs install --target gemini
+node ./bin/supered.mjs doctor --target gemini
 ```
 
+## Doctor
+
+Doctor checks Install Health without changing files:
+
+```bash
+supered doctor --target codex
+supered doctor --target codex --json
+```
+
+It reports missing skills, changed skill files, missing destinations, and unsafe symlinks. The fix it prints is a reinstall command for the same target and destination.
+
 ## Manual
 
 Copy each folder in `skills/` into the skill directory used by your agent host.