@skill-map/cli 0.45.1 → 0.47.0

package/dist/cli/tutorial/sm-master/references/tour-settings.md

@@ -1,12 +1,18 @@
 # Tour: settings + slots (step library, `settings-*` ids)
 
-Step bodies for two tours: option 2 (`settings-and-consent`,
-runs `settings-1-project` and `settings-2-local`) and the
-single shared step `settings-6-contributions` borrowed by
+Step bodies for two tours: option 1 (`settings`, runs
+`settings-1-layers`, `settings-2-resolve`, and `settings-3-lens`)
+and the single shared step `settings-6-contributions` borrowed by
 option 3 (`build-and-configure`). The SKILL.md orchestrator
 dispatches each `settings-*` id here; `authoring-*` ids it
 dispatches to `tour-authoring.md`.
 
+The `.sm` consent gate (companion files, `allowEditSmFiles`,
+`sm sidecar annotate`) is covered end to end in the basic
+`sm-tutorial`, so this tour does NOT repeat it; it focuses on the
+config layer system and the `sm config` verbs, which the basic
+tutorial does not teach.
+
 ## Precondition check
 
 Same as the authoring step library: `.skill-map/` must exist in
@@ -16,18 +22,34 @@ and appended the master-tutorial's internal entries to
 `.skill-map/` is missing, surface the bootstrap mismatch and
 stop, do not try to re-init mid-tour.
 
-## Step `settings-1-project` — project settings (~2 min)
+## Step `settings-1-layers` — the config layers (~3 min)
+
+**Context**: where settings live and how `sm` resolves a value
+when more than one place sets it.
+
+> `sm` resolves every setting through a stack of **layers**, each
+> one overriding the layer below it:
+>
+> 1. **defaults**, baked into the CLI.
+> 2. **project**, `.skill-map/settings.json`. Committed to git,
+>    shared with the whole team.
+> 3. **project-local**, `.skill-map/settings.local.json`.
+>    Gitignored, per-checkout, never travels through the repo
+>    (this is where the `.sm` consent flag from the basic tutorial
+>    lives).
+> 4. **override**, transient flags for a single command.
+>
+> There is no user or global layer: `sm` never merges anything
+> from your home directory. Everything is project-scoped.
 
-> Every project that runs `sm init` gets a `.skill-map/`
-> directory with two settings files. The first one is
-> `settings.json`, this is the **public** project settings, the
-> file you commit to git.
+> `sm init` already created the two files. The committed one starts
+> minimal:
 
 ```bash
 cat .skill-map/settings.json
 ```
 
-Expected output on a fresh init:
+Expected on a fresh init:
 
 ```json
 {
@@ -35,83 +57,142 @@ Expected output on a fresh init:
 }
 ```
 
-> Minimal on purpose. The CLI keeps the file lean and only adds
-> keys when you change a setting. Schema version is there so the
-> CLI can migrate the shape forward without surprising you.
->
-> The settings UI in the browser (the `Settings` tab when `sm` is
-> running) writes back into this file. Anything you change in
-> there ends up here, commit it to share the choice with the
-> team.
+> `schemaVersion` lets the CLI migrate the shape forward without
+> surprising you; the file only grows keys as you change settings.
+> Now list every setting the project sees, already resolved across
+> the layers:
 
-Mark `settings-1-project: done`.
+```bash
+sm config list
+```
 
-## Step `settings-2-local` — per-user overrides (~3 min)
+Expected: a grouped table (General, Scan, Jobs, Roots & plugins,
+History, Other) with each key's resolved value. A dash means
+"unset, falling back to the default". The browser Settings tab
+writes into `settings.json`, so anything you change there shows up
+in this list too.
 
-> The second file is `settings.local.json`, which is **gitignored
-> by default**. It exists for choices that should NOT travel
-> across the team:
->
-> - Whether you allowed `sm` to create `.sm` companion files in
->   this project (the consent gate from the basic tutorial).
-> - Personal token paths or credentials you do not want to
->   commit.
-> - Local preferences that depend on your dev environment.
+Mark `settings-1-layers: done`.
+
+## Step `settings-2-resolve` — read, resolve, and set a value (~3 min)
+
+**Context**: the four config verbs (`get`, `show`, `set`, `reset`)
+and how `show --source` reveals which layer won.
+
+> Read a single setting. We'll use `scan.maxNodes`, the cap on how
+> many nodes a scan walks:
 
 ```bash
-cat .skill-map/settings.local.json
+sm config get scan.maxNodes
+sm config show scan.maxNodes --source
 ```
 
-Expected on a fresh init:
+Expected: `get` prints the value (`256`); `show --source` adds
+where it came from, `256  (from defaults)`. Nothing is set yet, so
+the default wins.
 
-```json
-{}
+> Now set it in the project layer and watch the source move:
+
+```bash
+sm config set scan.maxNodes 500 --yes
+sm config show scan.maxNodes --source
 ```
 
-> Empty until something writes to it. The first thing that
-> typically lands is `allowEditSmFiles: true` after you accept
-> the `.sm` prompt (the consent gate is a per-user, per-project
-> choice, that's why it goes here).
-
-Before the demo, give the tester one sentence of context about
-what a `.sm` file actually is (the basic tutorial introduces it
-in passing, here we anchor the concept):
-
-> Every `.md` skill-map tracks gets a sibling `.sm` file (e.g.
-> `notes/ideas.sm` next to `notes/ideas.md`) that carries **all
-> of the tool's metadata about that markdown, so your `.md`
-> stays clean and uncluttered**. Version, history, tags,
-> annotations, anything that does not belong in the
-> human-authored body lives in the `.sm`. The `.md` is content
-> you write for Claude or humans, the `.sm` is bookkeeping the
-> tool writes. They are ordinary source files, committed to git,
-> and you'll see them often once you start using `sm bump` /
-> `sm sidecar annotate` day to day.
-
-If the tester wants to see it in action: ask them to run
-`sm sidecar annotate notes/ideas.md`, accept the `[Y/n]` prompt
-with `y`, and re-check the file:
+Expected: the set prints
+`✓  scan.maxNodes = 500  (wrote .skill-map/settings.json)`, and
+`show --source` now reads `500  (from project)`. The value climbed
+a layer, `project` overrides `defaults`. Peek at the file and the
+nested key is there:
+
+```bash
+cat .skill-map/settings.json
+```
+
+> Last, undo it. `sm config reset` removes the key so the default
+> takes over again:
+
+```bash
+sm config reset scan.maxNodes
+sm config show scan.maxNodes --source
+```
+
+Expected: `✓  Removed scan.maxNodes from .skill-map/settings.json`,
+then `256  (from defaults)`, back where we started. (A made-up key
+like `scan.nope` is rejected with `✕ Unknown config key`, the
+catalog is closed.)
+
+Mark `settings-2-resolve: done`.
+
+## Step `settings-3-lens` — the active provider lens (~4 min)
+
+**Context**: the single most consequential setting, the lens that
+decides which provider types the project's files. It is reversible
+and never touches your `.md` files, only the scan cache.
+
+> One setting earns its own step: the **active provider lens**. A
+> skill-map project sees its filesystem through exactly **one**
+> provider at a time, and that lens decides how each file is read.
+> Under the `claude` lens a `.claude/agents/*.md` is an agent and
+> `@`-mentions / `/`-commands become links; point the lens at
+> `openai` and the same tree is read against Codex's layout instead.
+> Same files, different reading.
+
+> The lens auto-detects on the first scan from the markers in your
+> project (`.claude/` → claude, `.codex/` or a root `AGENTS.md` →
+> openai, `.agents/` → agent-skills). Scan once and check where it
+> landed:
+
+```bash
+sm scan
+sm config get activeProvider
+```
+
+Expected: the scan prints a line like `Auto-detected activeProvider
+= claude from filesystem markers; persisted to
+.skill-map/settings.json`, and `get` then reports `claude`. The lens
+is just a key in `settings.json`, persisted like any other setting.
+
+> Now switch it by hand and watch what happens. We'll point it at
+> `openai`:
+
+```bash
+sm config set activeProvider openai
+```
+
+Expected: alongside the usual `✓  activeProvider = openai  (wrote
+.skill-map/settings.json)`, the CLI warns `Lens switched. Cleared 7
+scan table(s) ... Run sm scan to repopulate the graph under the new
+lens`. The important part: it cleared the **scan cache only**, your
+`.md` files are untouched. The graph is derived data; the source is
+always your filesystem.
+
+> Re-scan under the new lens, then put it back the way you found it:
 
 ```bash
-sm sidecar annotate notes/ideas.md
-cat .skill-map/settings.local.json
+sm scan
+sm config reset activeProvider
+sm scan
 ```
 
-Expected: now contains `{"allowEditSmFiles": true}` (plus a
-`notes/ideas.sm` file landed next to the markdown).
+Expected: the first scan repopulates under `openai`; `reset` removes
+the key (`Removed activeProvider from .skill-map/settings.json`); the
+last scan auto-detects `claude` again from your `.claude/` marker.
+Back where you started, nothing lost.
 
-> The choice stuck. Next time `sm` wants to write a `.sm` in this
-> project, it skips the prompt because your consent is on
-> record. If you delete the file or move to a different project,
-> the prompt comes back.
+> That's the whole idea of the lens: one project, one active
+> provider at a time, chosen by `activeProvider` and backed by the
+> built-in provider plugins (`claude`, `openai`, `agent-skills`,
+> `antigravity`). Switching it is cheap and reversible because the
+> graph is always rebuilt from your files, never the other way
+> around.
 
-Mark `settings-2-local: done`.
+Mark `settings-3-lens: done`.
 
 ## Step `settings-6-contributions` — watch contributions land (~2 min)
 
-> Last step. Let's see a contribution land in the inspector
-> live. The fixture's `master-agent` declares `tools: [Read,
-> Bash, Edit]`, which the `core/tools-counter` extractor picks up.
+> Last step. Let's watch a contribution land on a node card live.
+> The fixture's `master-agent` declares `tools: [Read, Bash,
+> Edit]`, which the `core/tools-counter` extractor picks up.
 
 If the tester does not have `sm` running, ask them to launch it
 in their second terminal (same drill as the basic tutorial:
@@ -124,14 +205,14 @@ sm
 
 Once the UI is open, ask the tester to:
 
-> Click the `master-agent` node. The inspector opens on the
-> right side. Look at the **header badge cluster** (just under
-> the title): you should see a small chip from `tools-counter`
-> showing the value `3`.
+> Find the `master-agent` card in the graph. Look at its **left
+> footer** (the bottom-left corner of the card): you should see a
+> small wrench chip from `tools-counter` labelled `tools` showing
+> the value `3`. Hover it to see the tool names.
 >
 > That chip is a plugin contribution. It landed in the slot
-> `inspector.header.badge.counter`, the renderer is `NodeCounter`
-> (same one your scaffold uses), the payload was `{ value: 3 }`.
+> `card.footer.left`, the renderer is `NodeCounter` (same one your
+> scaffold uses), the payload was `{ value: 3 }`.
 
 If the `demo-highlight` plugin from the earlier authoring steps
 of this tour is still installed, point the tester at the
@@ -147,8 +228,8 @@ remove one tool), save, and watch the chip refresh.
 > Same flow as the basic tutorial's live UI: edit the markdown,
 > watch the UI refresh. The difference is that the value flowed
 > through a plugin (`core/tools-counter`) and landed in a specific
-> slot (`inspector.header.badge.counter`). You now know the full
-> path from `.md` to UI chip.
+> slot (`card.footer.left`). You now know the full path from `.md`
+> to UI chip.
 
 Have them Ctrl+C the server when done.
 

package/dist/cli/tutorial/sm-tutorial/SKILL.md

@@ -1603,11 +1603,11 @@ tester pulls on the thread.
 
 The verb is informational, passing `core/external-url-counter`
 validates the extension exists and then renders the **parent
-bundle's** detail (i.e. the full `core` listing). The extension
+plugin's** detail (i.e. the full `core` listing). The extension
 you named lives in that list. This is deliberate: forcing the user
-to type the bundle id just to read a single extension's manifest
+to type the plugin id just to read a single extension's manifest
 would be hostile, so `show` accepts the qualified shape and
-resolves up. Use `sm plugins doctor` or scroll the bundle's
+resolves up. Use `sm plugins doctor` or scroll the plugin's
 extension table to spot the one you queried.
 
 ### IDs for `plugins disable` / `plugins enable`