openRepoShape --doctor: the installed form keeps the clone of the standard it ran from and names it on the report's last line, so a NEXT line pasted after the command has exited runs instead of dying with can't open file, and it hands --json and --placement-plan <file> on to shape-doctor.py instead of refusing them (#500)

AGENTS.md

@@ -215,9 +215,9 @@ no `--dry-run` to do first. The checks are a REGISTRY with an empty `fix` slot
 in each of them, which is where a repair mode will hang; nothing in it writes
 today. The one exception to "writes nothing" is `--placement-plan <file>`, which
 writes that file and nothing else — see 4. Installed, `openRepoShape --doctor`
-runs from a temporary clone of the standard, deleted on exit, and takes a path
-and nothing else: to ACT on a row (`--json`, `--placement-plan`, its next
-command) run `./shape-doctor.py --root <path>` from a checkout.
+takes `--json` and `--placement-plan <file>` as well, and KEEPS its temporary
+clone of the standard, because the NEXT lines run from it: its last line names
+that directory, which is the human's to delete once those commands have run.
 
 1. **Read the verdict, then read the rows.** `COMPLIANT`, `COMPLIANT, SHAPE
    BEHIND`, `DRIFTED`, `MISPLACED`, `INVALID`, `NOT A SHAPE ROOT` — exits 0, 1,
@@ -263,7 +263,7 @@ command) run `./shape-doctor.py --root <path>` from a checkout.
    never changes the verdict: it says whether THIS workstation can run the fixes
    the other rows named. Relay a missing prerequisite; `openRepoShape
    --preflight` offers only the `gh` set-up, and the human types that yes.
-7. `./shape-doctor.py --json` is the same report as one object, each row
+7. `--json` is the same report as one object, alone on stdout, each row
    carrying its `id`, for when you have to act on a row rather than quote it.
 
 ## Updating a project's shape

README.md

@@ -1109,11 +1109,11 @@ openRepoShape --doctor                 # the repository you are standing in
 ./shape-doctor.py --root ../MedxEHR --json
 ```
 
-It **writes nothing and fetches nothing**, and it reimplements nothing: every
-row is one of the checks this file already documents. The standard a project's
-copies are compared against is the checkout the script is RUN FROM — beside
-one it uses that one, installed it clones the standard into a temporary
-directory first — which is what makes the verdict offline.
+It **writes nothing into the repository and fetches nothing from it**, and it
+reimplements nothing: each row is a check this file documents. It compares
+against the checkout it is RUN FROM, so the verdict is offline. Installed, it
+clones the standard into a temporary directory and KEEPS it, because its NEXT
+lines run from there: its last line names it, safe to delete after they run.
 
 For an assembly root the rows are **naming** (this standard's own
 `contracts/repository-naming.yaml`), **manifest** and **pins** (the project's
@@ -1168,7 +1168,7 @@ next command. `MISPLACED` sits between the two: a path in the wrong leg is a
 fact about the shape no validator, pin or manifest here can see. **An
 unfinished merge outranks all three**, as `INVALID (merge)`: the conflict is
 what turns the other rows red, and no fix commits until it is finished.
-`--json` is the same report as one object, each row carrying its `id`.
+`--json` is the same report as one object on stdout, each row carrying its `id`.
 
 **`placement` is the row that reads what is *inside* the legs.** Brett Heap,
 2026-09-10: *"we have to look for code in spec and spec in code"*. It runs the
@@ -1209,7 +1209,7 @@ is already split. `adopt-project.py` refuses this kind by name, and the refusal
 says which tool consumes one. A later `--fix --plan <file>` will carry a
 **resolved** plan out by paired leg pull requests and a pin bump, printing what
 it will do and asking first; until then the moves are yours. `--placement-plan`
-is the only thing this command writes, and it writes only the file you name.
+is all `shape-doctor.py` ever writes, and it writes only the file you name.
 
 **`machine` is the one row that is not about the repository**, so it is `n/a`
 by status and can never move the verdict: a workstation with no `gh` is not

docs/cli.md

@@ -122,7 +122,7 @@ Anything after `--` is passed straight through to scaffold-project.py.
 ```
 openRepoShape --install            install (or update) this command into ~/.local/bin
 openRepoShape --preflight          check this MACHINE and stop; creates nothing
-openRepoShape --doctor [<path>]    diagnose a REPOSITORY against this standard
+openRepoShape --doctor [<path>] [--json] [--placement-plan <file>]
 openRepoShape <Project> [--org <org>] [setup-project.py options] [-- <scaffold flags>]
 openRepoShape --help | --version
 
@@ -155,12 +155,23 @@ opensoft/openRepoTools', and its own installer places them:
   $OPENREPOSHAPE_BIN_DIR    where --install puts it  (default ~/.local/bin)
   $OPENREPOSHAPE_SETUP_SH   run this setup.sh on disk instead of fetching one
 
-`--doctor [<path>]` runs `shape-doctor.py` over <path> (default `.`) and prints
-one row per check and ONE verdict: COMPLIANT, COMPLIANT SHAPE BEHIND, DRIFTED,
-INVALID or NOT A SHAPE ROOT. It writes nothing, and every finding names the
-command that fixes it. Exit 0 compliant, 1 findings, 2 not a shape root, 3
-usage. Run beside a checkout of the standard it uses that one; run from
-anywhere else it clones the standard into a temporary directory first.
+`--doctor [<path>] [--json] [--placement-plan <file>]` runs `shape-doctor.py`
+over <path> (default `.`) and prints one row per check and ONE verdict:
+`COMPLIANT`, `COMPLIANT, SHAPE BEHIND`, `DRIFTED`, `MISPLACED`, `INVALID`,
+`NOT A SHAPE ROOT` or `CANNOT ANSWER`. Every finding names the command that
+fixes it. Exit 0 compliant, 1 findings, 2 not a shape root, 3 when it cannot
+answer (`CANNOT ANSWER`, no such <path>, a `--placement-plan` it cannot
+write); this command's own refusals exit 2. `--json` is the same report as
+one JSON object. The doctor writes no file but the `--placement-plan <file>`
+you name, at the path you give (a relative <file> lands in the directory you
+ran this from, even inside the repository), and moves nothing.
+
+Run beside a checkout of the standard, it uses that one. Run from anywhere
+else, it clones the standard into a temporary directory first and KEEPS it,
+because its NEXT lines name files in it. The report's last line names
+that directory, which is safe to delete once you are done with those
+commands; under `--json` that line goes to stderr, so stdout stays one JSON
+object.
 
 `--preflight` is the MACHINE check -- it was spelled `--doctor` until
 2026-09-10, and the name moved to the repository diagnosis above, which is

docs/handbook.html

@@ -1464,12 +1464,12 @@ <h2>Is this repository compliant? <code>openRepoShape --doctor</code></h2>
       <div class="code" data-lang="sh"><pre><code>openRepoShape --doctor ../MedxEHR      # or: ./shape-doctor.py --root ../MedxEHR
 openRepoShape --doctor                 # the repository you are standing in
 ./shape-doctor.py --root ../MedxEHR --json</code></pre></div>
-      <p>It <strong>writes nothing into the repository and fetches nothing</strong>, and it
-      reimplements nothing. One flag writes at all, and it writes one file you named:
-      <code>--placement-plan</code>, below. The
-      standard a project&rsquo;s copies are compared against is the checkout the script is RUN FROM
-      &mdash; beside one it uses that one, installed it clones the standard into a temporary
-      directory first &mdash; which is what makes the verdict offline.</p>
+      <p>It <strong>writes nothing into the repository and fetches nothing from it</strong>, and
+      it reimplements nothing. One flag writes at all, and it writes one file you named:
+      <code>--placement-plan</code>, below. It compares against the checkout it is RUN FROM, so
+      the verdict is offline. Installed, it clones the standard into a temporary directory and
+      KEEPS it, because its NEXT lines run from there: its last line names it, safe to delete
+      after they run.</p>
       <p>For an assembly root the rows are <strong>naming</strong>, <strong>manifest</strong> and
       <strong>pins</strong> (the project&rsquo;s OWN validators when it carries them &mdash; they
       are the pinned copies, which is the point &mdash; else the template copies, and the row says
@@ -1526,7 +1526,7 @@ <h2>Is this repository compliant? <code>openRepoShape --doctor</code></h2>
       a red validator names itself in the table whether or not it also names the verdict line.
       <strong>An unfinished merge outranks all three</strong>, as <code>INVALID (merge)</code>: the
       conflict is what turns the other rows red, and no fix commits until it is finished.
-      <code>--json</code> is the same report as one object,
+      <code>--json</code> is the same report as one object on stdout,
       each row carrying its <code>id</code>.</p>
 
       <p><strong><code>placement</code> is the row that reads what is <em>inside</em> the
@@ -1567,8 +1567,8 @@ <h2>Is this repository compliant? <code>openRepoShape --doctor</code></h2>
       tool consumes one. A later <code>--fix --plan &lt;file&gt;</code> will carry a
       <strong>resolved</strong> plan out by paired leg pull requests and a pin bump, printing what
       it will do and asking first; until then the moves are yours.
-      <code>--placement-plan</code> is the only thing this command writes, and it writes only the
-      file you name.</p>
+      <code>--placement-plan</code> is all <code>shape-doctor.py</code> ever writes, and it writes
+      only the file you name.</p>
       <p><strong><code>machine</code> is the one row that is not about the repository</strong>, so
       it is <code>n/a</code> by status and can never move the verdict: a workstation with no
       <code>gh</code> is not this repository being non-compliant. It runs
@@ -1877,9 +1877,10 @@ <h2>For AI assistants</h2>
       <code>--reuse-empty-repo</code> reusing an empty leg and a leg holding the scaffold&rsquo;s
       own seed, and the one ruleset exit that re-run is, added (#462); <code>family.py</code>
       <code>add</code>, <code>bump</code> and <code>remove</code> committing on a branch made first,
-      never the tracking branch, and printing the push of it, added (#487) &mdash; a page cannot
-      name the commit that contains it, and the blob below is the fact a test checks.
-      README.md blob ab6ec9b00c1b7d0d4f1d0be075f2d3afcf8d8a3f. Every command, flag, exit code
+      never the tracking branch, and printing the push of it, added (#487); the installed doctor
+      keeping its clone of the standard, which its NEXT lines run from, added (#500) &mdash; a page
+      cannot name the commit that contains it, and the blob below is the fact a test checks.
+      README.md blob 8527950a3e47a4b6d87dababe6886155432d5c87. Every command, flag, exit code
       and file name on this page is quoted from that README and from AGENTS.md.</p>
     </footer>
   </main>