Merge pull request #67 from JRS1986/feature/cli-ux-pass

CLI UX pass: doctor + pilot + grouped help (v0.5.0)

Author: JRS1986

CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to CodingScaffold are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] — 2026-05-18
+
+### Added
+
+- **Top-level help groups commands by user journey.** `coding-scaffold --help` now opens
+  with four labelled sections — **Start here**, **10-minute pilot**, **Daily workflow**,
+  and **Advanced / governance** — so a new user can see the smallest useful path before
+  the full alphabetical command list. The full reference is still printed below as usual;
+  no commands were removed or renamed and every hidden compatibility alias (`init`,
+  `wizard`, `setup-tool`, `setup-addon`, `setup-knowledge`, `knowledge-status`,
+  `context-budget`, `compress-context`, `orchestrate`, `adapt`, `route`, `select-model`)
+  still parses.
+- **`coding-scaffold doctor` becomes the accessibility hub.** New module
+  `src/coding_scaffold/doctor.py`. The command now accepts `--target` and `--json`,
+  surveys 14 scaffold-artifact paths (AGENTS.md, CLAUDE.md, PR template,
+  `.coding-scaffold/` and its sub-directories, eval-config, etc.), recommends 1-3
+  context-aware next commands (e.g. an empty repo gets `pilot` + `setup run`; a partially
+  set-up repo gets `pr-template init` or `session init`), and explicitly names the
+  advanced surfaces (`policy`, `mcp`, `skills`, `memory`, `team`, `permissions write`,
+  `tools route` / `workflow` / `orchestrate`) under "Ignore for now (advanced)". The
+  original hardware/provider snapshot still prints below the new structured output for
+  continuity.
+- **`coding-scaffold pilot --target . --tool opencode`.** New module
+  `src/coding_scaffold/pilot.py`. A safe guided wrapper that runs only read-only local
+  checks (Python version, `git` on PATH, the chosen tool's binary on PATH, credentials
+  in env, local-runtime CLIs) and then prints the exact three-step recipe tailored to
+  your environment. Never installs anything. Never writes files. The printed recipe may
+  include `--install` flags, but the user makes that call. Supports all six tools
+  (`opencode`, `claude-code`, `codex`, `openclaude`, `hermes`, `pi`) and `--json` output.
+
+### Documentation
+
+- README adds a "30-Second Start" block at the top with the three commands a new user
+  needs today (`doctor`, `pilot`, then follow the recipe).
+- `docs/wiki/Getting-Started.md` adds a "Smallest Useful Path" section that names the
+  same three commands and explicitly tells readers what to ignore for now.
+
 ## [0.4.2] — 2026-05-18
 
 ### Added
@@ -270,6 +307,7 @@ for the supported entry points.
   supported. Windows native (outside WSL) works for documentation generation but not for tool
   installation — use WSL for the full flow.
 
+[0.5.0]: https://github.com/JRS1986/CodingScaffold/releases/tag/v0.5.0
 [0.4.2]: https://github.com/JRS1986/CodingScaffold/releases/tag/v0.4.2
 [0.4.1]: https://github.com/JRS1986/CodingScaffold/releases/tag/v0.4.1
 [0.4.0]: https://github.com/JRS1986/CodingScaffold/releases/tag/v0.4.0

README.md

@@ -6,6 +6,27 @@
 Local-first onboarding, configuration, and governance scaffolding for AI-assisted software
 development teams.
 
+## 30-Second Start
+
+You need three commands today. The rest can wait.
+
+```bash
+# 1. See what's set up and what's next.
+coding-scaffold doctor --target .
+
+# 2. Print the safe 10-minute happy path for this repo.
+coding-scaffold pilot --target . --tool opencode
+
+# 3. Follow the printed steps. When done, run `doctor` again.
+```
+
+`doctor` is the accessibility hub: it surveys scaffold artifacts, recommends 1-3 commands
+tailored to what's already present, and explicitly names the advanced features you can
+ignore for now. `pilot` is a safe guided wrapper — it runs only read-only local checks
+(Python version, git availability, tool presence on PATH, credentials in env) and prints
+the exact commands to run next. Neither command installs anything or writes files; the
+recipe they print may include `--install` flags, but you make that call.
+
 > Looking for a specific entry point? See the [persona paths](docs/wiki/Team-Rollout.md#persona-paths)
 > (beginner / control-and-reproducibility / security review / team lead). For the threat model
 > and what the scaffold deliberately does not enforce, read [Security](docs/wiki/Security.md#threat-model).

docs/wiki/Getting-Started.md

@@ -3,6 +3,40 @@
 This page walks through the first useful session. The goal is not to configure every advanced
 backend immediately; the goal is to make one small, inspected, verified change.
 
+## Smallest Useful Path
+
+After installing CodingScaffold in your environment, your first three commands are:
+
+```bash
+coding-scaffold doctor --target .
+coding-scaffold pilot --target . --tool opencode
+# follow the printed steps
+```
+
+That's it for day one. Everything else on this page is reference material you can come back
+to when you actually need it. The other commands (`policy`, `mcp`, `skills`, `memory`,
+`team`, `permissions`, `tools route`) are deliberately out of the first-run mental model —
+`doctor` lists them under "Ignore for now (advanced)" so you don't have to track them
+yourself.
+
+### What `doctor` does
+
+Surveys the scaffold artifacts already present in your project (AGENTS.md, PR template,
+`.coding-scaffold/`, etc.), prints which ones exist, and recommends 1-3 next commands
+tailored to the state. Read-only — never installs or writes files. Use `--json` for
+machine-readable output.
+
+### What `pilot` does
+
+Safe guided wrapper. Runs only read-only local checks (Python version, `git` on PATH, the
+chosen coding tool's binary on PATH, whether `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` /
+`GITHUB_TOKEN` are set, whether Ollama / LM Studio / llama-server are installed) and then
+prints the exact 10-minute path tailored to your environment. The recipe may include
+`--install` flags, but `pilot` itself never installs anything — you make that call.
+
+Both commands accept `--target` (defaults to `cwd`) and `--json`. Run `coding-scaffold
+doctor --help` or `pilot --help` for the full surface.
+
 ## What Needs A Model?
 
 The scaffold bootstrap does not need one. `coding-scaffold setup run`, `probe`, `credentials`,

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coding-scaffold"
-version = "0.4.2"
+version = "0.5.0"
 description = "Local-first coding agent scaffold with hardware probing, provider discovery, and routing config generation."
 readme = "README.md"
 requires-python = ">=3.11"

src/coding_scaffold/cli.py

@@ -40,6 +40,8 @@
     review_memory,
     write_memory_config,
 )
+from .doctor import format_doctor_text, run_doctor
+from .pilot import SUPPORTED_TOOLS as PILOT_SUPPORTED_TOOLS, format_pilot_text, run_pilot
 from .pr_template import write_pr_template
 from .session import (
     SessionStatusResult,
@@ -82,10 +84,38 @@
 KNOWLEDGE_BACKENDS_WITH_NONE = ["none", *KNOWLEDGE_BACKENDS]
 
 
+TOP_LEVEL_DESCRIPTION = """\
+Local-first scaffold for AI-assisted coding teams. Generates reviewable
+project-local guidance for hardware, providers, model selection, tool adapters,
+skills, knowledge, policy, and sessions.
+
+START HERE
+  coding-scaffold doctor                         see what's set up + what's next
+  coding-scaffold pilot --target . --tool opencode   print the 10-minute happy path
+  coding-scaffold setup run --mode beginner      guided full setup
+
+10-MINUTE PILOT (printed by `pilot` above; or run by hand)
+  coding-scaffold setup run --target . --tool opencode --mode beginner
+  coding-scaffold pr-template init --target .
+  opencode      # inside the agent: /first-session, then /agentic-change
+
+DAILY WORKFLOW
+  coding-scaffold session init --task "..."      reversible session trace
+  coding-scaffold context lint --target .        check agent-context files
+  coding-scaffold eval run --target .            readiness benchmark
+
+ADVANCED / GOVERNANCE (safe to ignore until your team needs them)
+  policy, mcp, skills, memory, team, permissions, tools, knowledge distill
+
+The full command list is below. Every command supports --help.
+"""
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="coding-scaffold",
-        description="Prepare a local-first AI coding scaffold for a project.",
+        description=TOP_LEVEL_DESCRIPTION,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     sub = parser.add_subparsers(dest="command", required=True, metavar="command")
 
@@ -634,7 +664,25 @@ def build_parser() -> argparse.ArgumentParser:
     update.add_argument("--target", type=Path, default=Path.cwd(), help="Project directory.")
     update.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
 
-    sub.add_parser("doctor", help="Print setup recommendations.")
+    doctor = sub.add_parser(
+        "doctor",
+        help="Survey scaffold artifacts and recommend the next 1-3 commands.",
+    )
+    doctor.add_argument("--target", type=Path, default=Path.cwd(), help="Project directory.")
+    doctor.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+
+    pilot = sub.add_parser(
+        "pilot",
+        help="Print the safe 10-minute happy path tailored to this project.",
+    )
+    pilot.add_argument("--target", type=Path, default=Path.cwd(), help="Project directory.")
+    pilot.add_argument(
+        "--tool",
+        choices=list(PILOT_SUPPORTED_TOOLS),
+        default="opencode",
+        help="Coding tool to weave into the recipe (default: opencode).",
+    )
+    pilot.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
     _hide_suppressed_subcommands(sub)
     return parser
 
@@ -880,7 +928,26 @@ def main(argv: list[str] | None = None) -> int:
         return 0
 
     if args.command == "doctor":
-        _print_doctor()
+        target = getattr(args, "target", None) or Path.cwd()
+        report = run_doctor(target)
+        if getattr(args, "json", False):
+            print(json.dumps(report.to_dict(), indent=2, sort_keys=True))
+        else:
+            print(format_doctor_text(report))
+            # Keep the original system snapshot at the end for continuity.
+            _print_doctor()
+        return 0
+
+    if args.command == "pilot":
+        try:
+            report = run_pilot(args.target, tool=args.tool)
+        except ValueError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return 1
+        if args.json:
+            print(json.dumps(report.to_dict(), indent=2, sort_keys=True))
+        else:
+            print(format_pilot_text(report))
         return 0
 
     if args.command == "credentials":