Persona flag for doctor/pilot + tour command (#90, #91)

README.md

@@ -32,8 +32,12 @@ inside a real repo and when the useful lessons from each session should become r
 You need three commands today. The rest can wait.
 
 ```bash
+# 0. (optional) Five-screen tour explaining the tool — read-only.
+coding-scaffold tour
+
 # 1. See what's set up and what's next.
 coding-scaffold doctor --target .
+# Or pick a persona path: --persona {beginner,control,security,team-lead}
 
 # 2. Print the safe 10-minute happy path for this repo.
 coding-scaffold pilot --target . --tool opencode

docs/docs/wiki/Glossary.md

@@ -0,0 +1,153 @@
+# Glossary
+
+One paragraph per term. Read this first if any CodingScaffold output uses a word you
+have not seen before. Each entry links to the wiki page that goes deeper.
+
+## adapter
+
+A small, native-format integration that teaches a specific coding tool how to behave
+inside this project. `tools adapt --tool opencode` writes OpenCode-shaped files;
+`--tool claude-code` writes the Claude-Code shape; and so on. Adapters are generated,
+reviewable, and have no runtime. See [Tool-Adapters](./Tool-Adapters.md).
+
+## agentic change
+
+A code change planned or written with help from an AI coding agent (OpenCode, Claude
+Code, Codex, …). CodingScaffold's `session` command + `agentic-change.md` PR template
+exist so these changes ship with the same shape as any other PR. See
+[Getting-Started](./Getting-Started.md).
+
+## artifact
+
+A file or directory CodingScaffold knows about: `AGENTS.md`, `.coding-scaffold/policy/`,
+`PR template`, eval config, sessions directory, knowledge base. `doctor` surveys
+artifacts; the canonical list with rationale lives in
+[`src/coding_scaffold/artifacts.py`](https://github.com/JRS1986/CodingScaffold/blob/main/src/coding_scaffold/artifacts.py).
+
+## context
+
+The bytes that go into the agent's input window for a single turn: the prompt, project
+rules, file excerpts, knowledge notes, prior messages. `context budget` estimates the
+size; `context lint` checks the files; `context compress` writes safer sidecars. See
+[Context-Hygiene](./Context-Hygiene.md).
+
+## doctor
+
+`coding-scaffold doctor` — the accessibility hub. Surveys what is set up, recommends
+1–3 next commands, and explicitly says which advanced surfaces a beginner can ignore.
+Never installs or writes; always safe to run.
+
+## eval
+
+A small readiness benchmark: `eval init` creates the config, `eval run` exercises it,
+`eval report` summarizes. It validates that the scaffold is set up — not that the model
+is good. See [Getting-Started](./Getting-Started.md).
+
+## knowledge base
+
+A team-shared, reviewable corpus of notes under `.coding-scaffold/knowledge/`. Multiple
+backends are supported (markdown, obsidian, foam, mempalace, html). Layered by scope
+(team/department/unit/company) and maturity (raw → curated wiki). See
+[Knowledge-Base](./Knowledge-Base.md).
+
+## maturity
+
+The lifecycle stage of a knowledge note: `raw` (captured but unreviewed), `wiki`
+(curated for the team), and the layered scopes (team/department/unit/company).
+`knowledge promote` moves notes between maturity levels with an audit trail.
+
+## MCP
+
+Model Context Protocol — a way for an agent to talk to external integrations (Slack,
+Notion, your bug tracker). `mcp policy`, `mcp scan`, `mcp snapshot`, `mcp diff`
+govern which integrations the project allows. See [Security](./Security.md).
+
+## memory
+
+Reviewable memory entries the agent can recall: `memory capture` proposes one,
+`memory review` accepts/rejects, `memory promote` moves it between maturity classes,
+`memory audit` lists what is in effect. Distinct from knowledge: memory is short
+runtime hints; knowledge is shared documentation.
+
+## orchestration
+
+A multi-step recipe a tool can drive (`tools orchestrate`). Distinct from a single
+prompt: orchestration plans the steps, picks a model per step, and tracks results.
+
+## persona
+
+A target user shape: `beginner`, `control-and-reproducibility`, `security-review`,
+`team-lead`. Used by `doctor --persona` / `pilot --persona` to surface a focused
+recipe instead of the full firehose. Personas are documented in
+[Team-Rollout](./Team-Rollout.md).
+
+## pilot
+
+`coding-scaffold pilot --target . --tool <name>` — read-only guided wrapper. Probes
+the local environment and prints the exact 10-minute happy-path commands. Never
+installs and never writes files. The printed recipe is what the user actually runs.
+
+## policy pack
+
+Files under `.coding-scaffold/policy/` that encode the team's non-negotiables:
+allowed providers, network rules, model selection floors, MCP allowlist. See
+[Policy-Packs](./Policy-Packs.md).
+
+## provider
+
+A source of model inference: a local runtime (Ollama, LM Studio) or a cloud API
+(Anthropic, OpenAI, …). `probe` lists what is available; `routing.json` describes
+how the project routes between them.
+
+## routing
+
+The plan for which model handles which class of request: `weak_model` (fast/cheap),
+`strong_model` (high-quality), plus the endpoint and policy. Stored in
+`.coding-scaffold/routing.json`.
+
+## scaffold artifact
+
+See [artifact](#artifact).
+
+## scaffold version
+
+A SHA256 snapshot of every generated file written by setup, stored in
+`.coding-scaffold/scaffold-version.json`. `setup update` uses it to tell unchanged
+files (safe to rewrite) from user-edited files (write a `.new` sidecar instead).
+
+## session trace
+
+A reviewable Markdown file under `.coding-scaffold/sessions/` recording a single
+agentic change: task, commands run, diff, follow-ups. Powers reversibility:
+`session checkpoint`, `session diff`, `session rollback`.
+
+## skill
+
+A reusable scoped instruction the agent loads on demand: a Markdown file under
+`.coding-scaffold/skills/<name>/` with a `SKILL.md`, optional helpers, and an
+approved checksum. `skills new`, `skills lint`, `skills approve`, `skills export`.
+See [Skills-and-Agents](./Skills-and-Agents.md).
+
+## stability marker
+
+A label rendered in `--help` next to each command name: `[stable]`, `[preview]`,
+`[experimental]`. Tells experienced teams what they can build infrastructure around.
+The contract per marker lives in [Stability](./Stability.md).
+
+## strong model
+
+The model class used for high-quality output (planning, review, hard reasoning).
+Set in `routing.json`. The pilot recipe avoids picking one for the user — that is
+the team's call.
+
+## team manifest
+
+A JSON file (`team-onboarding.json`) shipped from a team repo that defines shared
+policy, skills, knowledge sources, and version requirements. `team connect` /
+`team sync` apply it; `team push` nominates local artifacts upward; `team doctor`
+shows the effective merged view. See [Team-Sync](./Team-Sync.md).
+
+## weak model
+
+The model class used for fast/cheap calls (extraction, classification, format
+conversion). Set in `routing.json`.

docs/docs/wiki/Stability.md

@@ -0,0 +1,67 @@
+# Stability
+
+Every top-level `coding-scaffold` command carries one of three stability markers,
+rendered in `--help` next to the command name:
+
+```
+COMMANDS (DAILY WORKFLOW):
+  session init             [stable]    create a reviewable session trace
+  memory capture           [preview]   capture a memory candidate for review
+  team push                [preview]   nominate local artifacts upward
+```
+
+The marker is a contract about how aggressively the command may change.
+
+## What each marker promises
+
+### `[stable]`
+
+- The flag set, output shape, and exit codes will not change in a backward-incompatible
+  way without a major version bump (`0.x → 1.0`) and a deprecation cycle.
+- A removed flag is preserved as a hidden alias for at least one minor release with
+  a deprecation message.
+- The CHANGELOG names every change under a `Deprecated` heading.
+
+Build automation, CI checks, and team docs against `stable` commands without
+hesitation.
+
+### `[preview]`
+
+- Feature-complete and tested. May still grow new flags or refine output in a minor
+  release.
+- Breaking shape changes are possible but called out in the CHANGELOG with a migration
+  note.
+- Used in production with caution: a `preview` command is on the path to `stable`,
+  and the wiki page for that area should note the target release.
+
+Treat `preview` commands like a beta API: depend on them, pin your scaffold version,
+and watch the CHANGELOG.
+
+### `[experimental]`
+
+- Fast-moving. May change shape, flag names, or behavior without warning.
+- Output formats are not part of the contract; do not parse them in CI.
+- Useful for exploration and feedback; not yet suitable as a build dependency.
+
+If you find an `experimental` command load-bearing for your team, open an issue —
+graduating to `preview` is a signal we look for.
+
+## Lifecycle
+
+- A new command lands as `experimental` by default.
+- It graduates to `preview` once the flag set is settled and at least one team is
+  using it.
+- It graduates to `stable` once the maintainers commit to the deprecation policy
+  above. The graduation lands in a minor release; the CHANGELOG notes it.
+
+## How to read the marker registry
+
+`src/coding_scaffold/cli_stability.py` is the single source of truth. The marker for
+a command is whatever appears there; the `--help` text is generated from it.
+
+A test (`tests/test_cli_stability.py`) asserts:
+- Every command surfaced in `--help` has a registry entry.
+- Every registry entry uses one of `stable | preview | experimental`.
+
+When you move a command between markers, update the registry and add a CHANGELOG
+entry under `Stability`.

docs/docs/wiki/Team-Rollout.md

@@ -142,6 +142,13 @@ The rollout is working when:
 Pick the path that matches the developer you're onboarding. Each path lists who it's for, what
 "done" looks like for them, and the smallest command set that gets them there.
 
+The CLI also surfaces these paths directly: `coding-scaffold doctor --persona <name>` and
+`coding-scaffold pilot --persona <name>` (where `<name>` is one of `beginner`, `control`,
+`security`, `team-lead`) tailor the recommendations and the ignore-for-now list to the
+persona's focus area. The persona registry lives at
+[`src/coding_scaffold/personas.py`](https://github.com/JRS1986/CodingScaffold/blob/main/src/coding_scaffold/personas.py)
+so the wiki and CLI cannot drift apart.
+
 ### Beginner path — for a junior developer new to agentic coding
 
 **Who:** writes Python or web code, hasn't worked with an autonomous coding agent before. Wants

docs/docs/wiki/_meta.json

@@ -1,5 +1,6 @@
 [
   "Getting-Started",
+  "Glossary",
   "Core-Concepts",
   "Model-Selection-and-Providers",
   "Skills-and-Agents",
@@ -12,5 +13,6 @@
   "Advanced-Workflows",
   "Team-Rollout",
   "Review-Backlog",
+  "Stability",
   "FAQ"
 ]

docs/docs/wiki/index.md

@@ -4,6 +4,9 @@ CodingScaffold is a local-first onboarding, configuration, and governance scaffo
 AI-assisted software development teams. The README is the quick front door; this wiki explains the
 project in more depth and gives teams a shared rollout playbook.
 
+**New here?** Read the [Glossary](./Glossary.md) first — every term `doctor` prints
+(artifact, persona, MCP, skill, manifest, scope, maturity) is defined in one place.
+
 ## What CodingScaffold Does
 
 CodingScaffold creates project-local guidance and lightweight configuration for:

src/coding_scaffold/artifacts.py

@@ -0,0 +1,123 @@
+"""Single source of truth for scaffold artifacts and the rationale behind each one.
+
+`doctor`, `pilot`, and any future onboarding command consume this registry instead of
+duplicating their own artifact tables. The `why` line answers \"what does this unlock?\"
+in <100 chars so a first-time reader can interpret `doctor` output without leaving the CLI.
+
+Add a new artifact here, not in `doctor.py`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Artifact:
+    """A scaffold artifact `doctor`/`pilot` can recommend, with a short rationale."""
+
+    key: str
+    relative_path: str
+    why: str
+
+    def __post_init__(self) -> None:
+        if len(self.why) > 100:
+            raise ValueError(
+                f"Artifact rationale for {self.key!r} is {len(self.why)} chars; keep under 100."
+            )
+
+
+ARTIFACTS: tuple[Artifact, ...] = (
+    Artifact(
+        key="AGENTS.md",
+        relative_path="AGENTS.md",
+        why="Codex reads this first; without it the agent has no project rules.",
+    ),
+    Artifact(
+        key="CLAUDE.md",
+        relative_path="CLAUDE.md",
+        why="Claude Code reads this first; project rules and links to local context.",
+    ),
+    Artifact(
+        key="pr_template",
+        relative_path=".github/PULL_REQUEST_TEMPLATE/agentic-change.md",
+        why="Makes every agentic change reviewable in the same shape across the team.",
+    ),
+    Artifact(
+        key=".coding-scaffold/",
+        relative_path=".coding-scaffold",
+        why="Holds project-local scaffold config: routing, providers, sessions, knowledge.",
+    ),
+    Artifact(
+        key="knowledge_base",
+        relative_path=".coding-scaffold/knowledge",
+        why="Shared, reviewable team notes; replaces tribal knowledge in chat history.",
+    ),
+    Artifact(
+        key="sessions_dir",
+        relative_path=".coding-scaffold/sessions",
+        why="Per-change traces; enables rollback and reviewable agentic edits.",
+    ),
+    Artifact(
+        key="policy_pack",
+        relative_path=".coding-scaffold/policy",
+        why="Provider/MCP/runtime rules; lets you enforce 'no internet at runtime'.",
+    ),
+    Artifact(
+        key="permissions_json",
+        relative_path=".coding-scaffold/agent-permissions.json",
+        why="Tool allowlist for agents; defaults to read-only until you opt in.",
+    ),
+    Artifact(
+        key="mcp_policy",
+        relative_path=".coding-scaffold/mcp-policy.json",
+        why="MCP server allow/deny rules; governs which integrations the agent may use.",
+    ),
+    Artifact(
+        key="skills_dir",
+        relative_path=".coding-scaffold/skills",
+        why="Reusable skill packs the agent can load on demand; reviewable in git.",
+    ),
+    Artifact(
+        key="memory_dir",
+        relative_path=".coding-scaffold/memory",
+        why="Captured agent memory entries; reviewed and promoted before they take effect.",
+    ),
+    Artifact(
+        key="eval_config",
+        relative_path=".coding-scaffold/eval-config.json",
+        why="Readiness benchmark config; `eval run` validates the project is set up.",
+    ),
+    Artifact(
+        key="pyproject.toml",
+        relative_path="pyproject.toml",
+        why="Python project marker; doctor uses this to tailor language-specific guidance.",
+    ),
+    Artifact(
+        key="package.json",
+        relative_path="package.json",
+        why="Node project marker; doctor uses this to tailor language-specific guidance.",
+    ),
+)
+
+
+_INDEX: dict[str, Artifact] = {a.key: a for a in ARTIFACTS}
+
+
+def artifact_keys() -> tuple[str, ...]:
+    """Stable, ordered list of artifact keys — matches the order shown by `doctor`."""
+
+    return tuple(a.key for a in ARTIFACTS)
+
+
+def get_artifact(key: str) -> Artifact:
+    """Look up an artifact by key. Raises KeyError if missing — callers should pass a
+    key from ``artifact_keys()``."""
+
+    return _INDEX[key]
+
+
+def rationale_for(key: str) -> str:
+    """Convenience for `get_artifact(key).why`."""
+
+    return _INDEX[key].why