Hide init/metrics behind the existing gate pattern, withdraw them from the user guide, correct doctor's checks

[simonkrol]

Description

CLI:

• Hid konductor init and konductor metrics from --help and gated them at dispatch behind KONDUCTOR_ALLOW_INIT=1/KONDUCTOR_ALLOW_METRICS=1 — matches the existing konductor config pattern exactly. All three stay functionally present (not deleted): init/config are complete, tested commands withheld from the v1 customer-visible surface; metrics is additionally a genuine stub with no logic behind its gate. Keeping them present rather than removing them avoids a breaking change for anything that already calls them directly.
• Consolidated the three near-identical *_dispatch_allowed_for gate helpers (config, init, metrics) into one generic command_dispatch_allowed_for(value, allow_value), with each command's own thin wrapper calling it. One parameterized test replaces three near-duplicate test bodies.
• Removed doctor's config check from the live checks vector (run_checks) — matches the existing check_gitignore dormant-check precedent. Traced every consumer of the resolved config values and confirmed none acts on them for a real decision; the check was validating decorative output. Function and its unit tests stay intact, just not wired into live dispatch. doctor now runs 8 checks instead of 9.
• Fixed doctor's dormant config-load-failure remediation string (in check_config_with_home, unit-tested but never called from live dispatch): it described a backup/hand-edit/delete-to-fallback recovery workflow for config.yml. Since nothing reads or writes this file through any live command today, there's nothing to remediate against; the string now says so plainly.
• Corrected cli.rs's --from doc comment on both install and update, which claimed installing from a published release was unavailable and that update --force doesn't exist — both false since v1.0.0 shipped. Now describes the real GitHub-release/main-dist fallback chain and --force's actual effect.
• Corrected cli/README.md's --all section, which still said "all six checks above" after the live check count had already moved to 8 — predates this branch, never updated.
• Added the three update flags (--cli, --version <v>, --force) to reference.md's flag table — present since the v1.0.0 release but never documented there.
• cli/README.md brought in line with all of the above, and trimmed to the minimum needed to state init/config/metrics exist but are hidden — most of the detailed status callout and repeated "(hidden; see the status note above)" cross-references were removed as redundant, since the one bare command-name line is all the guide's own drift checker actually requires.

Docs:

• Deleted docs/user-guide/tasks/initialize-a-project.md and removed every teaching reference to init/metrics from reference.md, concepts.md, glossary.md, faq.md — consistent with both being withdrawn from the documented command surface. Reworded every remediation step that used to recommend running init so it gives a manual alternative instead of a command that will now fail.
• Minimized init/config/metrics's overall documentation footprint rather than just correcting it: collapsed notes.md's three separately-repeated withdrawal explanations into one short shared section, trimmed skills/about-konductor/SKILL.md's rows to bare facts without escape-hatch mechanics, and dropped init/config entirely from the root README.md's command table — these three commands aren't meant to be used right now, so the documentation about them is deliberately minimal rather than thorough.
• Shrank reference.md's .konductor/config.yml section from a full schema/precedence/error-message writeup down to one short paragraph: the file isn't read by any live command today, so documenting its load errors and merge precedence in detail was describing a path that can't currently be exercised. Removed the matching misleading rows from uninstall.md's and reference.md's own artifact tables (both said "you, by hand" for a file nothing creates), and fixed uninstall.md's backup example to back up the whole .konductor/ directory instead of a file nothing writes.
• Corrected tasks/update.md and tasks/diagnose-problems.md's doctor check-count claims (still said six checks, including the removed config check) and update.md's unqualified "no version awareness" claim, which contradicted the file's own correct description of the no---from version-skip behavior a few lines earlier.
• Fixed all navigation left dangling by the initialize-a-project.md deletion (prev/next links, ToC entries, a mermaid diagram), and a stale "no release has been published yet" claim in prerequisites.md.
• Resynced both docs/index.html and docs/site/user-guide.html to match every markdown change above, via the deterministic htmlbundle.py edit mechanism — confirmed byte-identical to each other throughout, independently verified by decoding both and diffing against current markdown rather than only trusting the automated checker's narrower fact-based checks.

Build tooling:

• Added init/metrics to check-guide-facts.py's WITHDRAWN_COMMANDS, so the checker enforces their absence from the guide the same way it already did for config.

Fixes # (issue)

Type of Change

• CLI (cli/) change — Rust or Python
• Documentation

Testing

• If cli/ changed: cd cli && make test passes (Rust + Python + conformance suites) — full suite green, including the consolidated dispatch-allowed gate tests
• Smoke tested affected agent(s): live-verified konductor --help, konductor init/metrics/config (gated, exit 64, "not currently available"), and each with its escape hatch set (real behavior confirmed — init wrote real files to a scratch target, metrics reached its stub)
• Ran the benchmark harness for the affected agent(s) — not applicable, no agent behavior changed (CLI/docs only)
• New or changed code files carry the required SPDX header

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own changes — comment volume specifically re-reviewed and trimmed after an initial pass left several doc comments and test comments over-explaining implementation trivia and rejected alternative designs rather than stating the one load-bearing reason
• I have commented my code where necessary
• I have made corresponding changes to the documentation
• My changes generate no new warnings — cargo fmt --check and cargo build --release both clean; the one cargo clippy -D warnings finding in this tree (a handful of pre-existing lints in telemetry code) predates this branch and belongs to the PR that introduced it, not this one
• I have added or updated tests that prove my change works — added gate/escape-hatch tests for init/metrics mirroring the existing config test pattern, then consolidated the three into one parameterized test; updated one test whose assertion no longer held once config's doctor check was removed

Notes for Reviewers

• Split out of a larger original PR. This PR originally also included an install-summary SOP/skill-count rework and a quick-start/update page restructuring. Both were split into their own PRs (dev/simonkrol/install_summary_sop_counts, dev/simonkrol/quickstart_update_restructure) since they're orthogonal to hiding init/metrics — the SOP/skill-count work in particular was also directly conflicting with feat: publish Konductor as a Claude Code plugin marketplace #28's own install-summary changes on the same JSON fields, so splitting it out resolves that conflict at the root instead of requiring cross-PR coordination.
• metrics stays, deliberately. It's a stub with no consumer today, which is a real argument for deleting it outright — but keeping it hidden-and-gated (the same treatment as init/config) rather than removed keeps this PR's behavior change softer: nothing that already calls metrics directly loses the ability to, it just needs the same escape hatch init/config already use.
• Judgment call worth a second look: doctor's config check was removed because no code currently acts on .konductor/config.yml's resolved values — they're parsed and echoed but never drive a real decision. If that's intentional groundwork for a near-term feature rather than genuinely dead, this removal should be revisited before it ships.
• No version bump in this PR. The release-bump mechanics were deliberately pulled out at the reviewer's request; this PR's own CHANGELOG content lives under ## [Unreleased] with no version number assigned, since withdrawing a previously-documented, scriptable command (init) is a real behavior change that should get its own minor-version decision at release-cut time, not one bundled into this diff.

[ihmaws]

This removes sops_skipped from install --json output and adds a new sops key, in a patch release (1.0.4). The doc comment on format_install_summary_json says the break is intentional ("so a machine consumer … sees a clear break"). That is a breaking change to a published machine contract, and the CHANGELOG doesn't mention it.

Do not drop the existing key in a patch. Keep sops_skipped (it can be 0 on every path now, which is accurate) and add sops alongside it. If the key really needs to go, it belongs in a release that calls out the removal under ### Removed in the CHANGELOG.

Also note that #28 changes this same JSON block in the opposite direction: it keeps sops_skipped and adds sops_converted_to_skills. Please align with that PR on one contract before either merges (see the top-level comment).

[ihmaws]

Technically konductor init was a documented, public command through 1.0.3. It had its own guide page (tasks/initialize-a-project.md) and appeared in the quick-start. After this change, anyone following those docs or calling it from a script gets exit 64.

QQs:

1. Should this be a minor bump (1.1.0) instead of 1.0.4?
2. Additionally/Alternatively, should it at least be listed under ### Removed rather than ### Changed?

Let me know your thoughts.

[ihmaws]

clap uses /// doc comments as the subcommand's long help, so this maintainer note is printed to users verbatim:

$ konductor init --help
Initialize a new Konductor project: ...

Temporarily hidden from normal --help and from normal dispatch (see dispatch.rs's `Commands::Init` arm, which returns `EXIT_USAGE_ERROR` ... Re-enable by removing `#[command(hide = true)]` here and the gating check at the top of dispatch.rs's `Commands::Init` arm.

Please move the maintainer part to a plain // comment above #[command(hide = true)], so only the first paragraph stays in ///. Config already has the same leak on main (konductor config --help), and so does Metrics ("Hidden from normal --help since…"). Would be good to fix all three here, since this PR is establishing the pattern for them.

[ihmaws]

This skill ships to every install and is what the agent reads when a user asks "how do I use Konductor". The rest of the PR withdraws init/config/metrics from the documented surface, but this table now lists all three and tells the agent there is an escape hatch. That works against the withdrawal: an agent reading this will offer init to users or go looking for the env var. Can these three rows be removed, matching reference.md?

Two more things in this file:

1. The update row (line 173) still says "No diffing, no --force flag". Both are no longer true after the no---from version check and --force.
2. The install row still describes --from <repo-root> as the source, but the quick install path is now the default.

Also, this file isn't mentioned in the PR description, and most of its diff is em-dash → colon/comma rewrites. Was that intended for this PR? It makes the substantive changes harder to find. check-guide-facts.py's withdrawn-command scan doesn't cover skills/, which is why this passes the checker.

[ihmaws]

nit: A cargo update ran alongside the version bump? If not intended, please limit the lockfile change to the konductor entry.

If the dependency refresh is wanted, ideally those would go in its own change with clear intention to do so.

[ihmaws]

Why keep metrics at all? It's a stub with no logic, and it's now hidden, gated, and has an escape hatch that (per its own doc comment) "has no current consumer". We're carrying a command, a gate, an env var, five tests and a notes.md section for something that does nothing. Deleting Commands::Metrics would be simpler, and when the real implementation exists it can arrive as a new command. Is there something I'm missing that needs the stub to exist now? Let me know your thoughts.

[ihmaws]

nit:config_dispatch_allowed_for, init_dispatch_allowed_for and metrics_dispatch_allowed_for are identical, and so are their wrappers and their three exact-value tests. Consolodate?.

[ihmaws]

This comment no longer holds after this PR: init is withdrawn and doctor no longer validates the file. That's why these verbose comment blocks are not helpful. Really stale-ing up the repo with misinformation quickly

[ihmaws]

The config, init and metrics sections each repeat the same two-paragraph WITHDRAWN_COMMANDS explanation word for word, and the config and init sections also repeat the config.yml paragraph. Could the shared text live once, under a single "Withdrawn commands" heading, with one short line per command saying why it's withdrawn? That way the next withdrawal is a one-line edit.

Also on this page: line 26 ("Documented version") still says Cargo.toml is 0.1.1 and to "bump the source before launch". That's no longer true at 1.0.4, and the page's own header says to remove entries once they're fixed. Was pinning the guide at 1.0.0 meant to outlive launch? Right now the quick-start --version checkpoint shows konductor 1.0.0 while users see 1.0.3. Dropping the version from the sample output would avoid this. Not blocking.

[ihmaws]

nit: the piped script is the bootstrap script. What it downloads and verifies is scripts/konductor-install.sh. Suggest: "The bootstrap script downloads konductor-install.sh, verifies it against the checksum GitHub's Contents API reports for that file, and runs it. It needs curl, jq and git on your PATH." It does check for all three up front, and the "What you need" line above no longer mentions git.

[ihmaws]

Thanks for the changes! Some top-level feedback:

1. Size and scope. I'd recommend splitting this one, at +1,780/−934 across 34 files. It mixes CLI gating, an install-summary rework, a doctor change, a quick-start/update-page rewrite, guide tooling fixes, an agent-skill rewrite and a release bump. Probably could have gone in as individual changes or leveraging GitHubs new stacked PRs feature

2. Overlap with #28. #28 also rewrites the install summary's SOP clause and the sops_skipped JSON field, but goes the other way: it counts SOP conversions inside skills and adds sops_converted_to_skills. Whichever merges second will conflict and also has to make the contract decision. Can you two agree on one model first?

3. Comment volume. Many doc comments are much longer than the code they describe. format_install_summary has ~45 lines over one format!, and a lot of the text narrates the fix ("pre-fix bug", "now-removed", "the fix this test guards"), which goes stale as soon as this merges. Would recommend trimming comments to what the code does and why, and leaving the history to the commit messages.

4. Top-level README.md. Its command table (around line 272) still lists konductor init and konductor config. Not in this diff, but it should go with the withdrawal.

5. In my mind, I'd like to see these release bumps on their own once everything lands into main. I don't love the idea of this PR being what controls when we cut the new release.

cli/konductor-rs/src/cli.rs:215 — Same kind of stale --help text as the --from fix in this PR: konductor update --help prints "There is no --force flag" and then lists --force a few lines below. Since you're already correcting cli.rs doc comments, could this one be updated too? Not blocking.