@skill-map/cli 0.45.0 → 0.46.0

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

@@ -98,13 +98,13 @@ must internalise before talking to the tester:
   first-mention gloss in addition. The list itself is the gloss.
 
   **Emoji preservation**: when the source line is `> <emoji>
-  **Name**` (e.g. `> 📦 **Built-in bundles**`, `> 🗂️
+  **Name**` (e.g. `> 📦 **Built-in plugins**`, `> 🗂️
   **provider**`), the emoji stands alone as plain text, the name
   is bold. NEVER wrap the emoji in single asterisks (`*📦*`) or
   underscores (`_📦_`), NEVER wrap the entire line in italics
   (`*📦 Name*`), NEVER convert the bold to italic. The emoji
   must render as a plain emoji glyph, not italicised. Same for
-  the bundle list (`📦`, `📥`) and the six-kinds list (`🗂️`,
+  the plugin list (`📦`, `📥`) and the six-kinds list (`🗂️`,
   `🔍`, `🩺`, `⚡`, `🎨`, `🎣`).
 - **The `> ` blockquote prefix on tester messages is
   host-dependent**, applied only when the host renders blockquotes
@@ -299,9 +299,10 @@ we move on."
 > before we move on.
 >
 > By the way: this advanced tutorial assumes you already went
-> through `sm-tutorial` (the onboarding one). If you have not, it
-> is the same flow with the `tutorial` keyword from an empty dir.
-> Want to keep going here, or pause and run that one first?
+> through `sm-tutorial` (the onboarding one). If you have not, run
+> `sm tutorial` in an empty dir to install its skill, then open
+> your agent there and ask for it, the same way you reached this
+> one. Want to keep going here, or pause and run that one first?
 
 ### 2. Verify `sm`
 
@@ -399,18 +400,15 @@ tester already completed.
 All set up! Pick your tour, you can come back for the others
 later.
 
-**1. Built-in plugins** (~13 min)
-> The six extension kinds, what comes pre-installed, how to inspect and toggle them.
+**1. Settings** (~10 min)
+> Config layers, the `sm config` verbs, and the active provider lens that decides how the project is read.
 
-**2. Settings and consent** (~5 min)
-> Where settings live (`settings.json` vs `settings.local.json`), and the per-user consent gate that controls when `sm` may write `.sm` companion files in this project.
+**2. Built-in plugins** (~13 min)
+> The six extension kinds, what comes pre-installed, how to inspect and toggle them.
 
 **3. Build and configure plugins** (~17 min)
 > Scaffold a plugin with `sm plugins create`, tour what landed, edit a setting and a view-slot, see the contribution appear in the UI, validate with `doctor` and `upgrade`.
 
-**4. I'm done for today**
-> Wrap up.
-
 Which one?
 
 **Rendering rules** (apply on every render of the menu, first
@@ -435,16 +433,15 @@ time and on subsequent loops):
   the description visually with two spaces so it stays
   subordinate to its title.
 - The trailing "Which one?" stays on its own line, separated
-  from option 4's description by a blank line.
+  from option 3's description by a blank line.
 
 Mapping:
-- **1** → the tour `plugins-tour`. Its step order is defined in
+- **1** → the tour `settings`. Its step order is defined in
+  `master-state.yml.tours.settings.steps`. All step ids are
+  `settings-*`, the bodies live in `references/tour-settings.md`.
+- **2** → the tour `plugins-tour`. Its step order is defined in
   `master-state.yml.tours.plugins-tour.steps`. All step ids are
   `tour-*`, the bodies live in `references/tour-plugins.md`.
-- **2** → the tour `settings-and-consent`. Its step order is
-  defined in `master-state.yml.tours.settings-and-consent.steps`.
-  All step ids are `settings-*`, the bodies live in
-  `references/tour-settings.md`.
 - **3** → the **merged tour** `build-and-configure`. Its step
   order is defined in `master-state.yml.tours.build-and-configure.steps`.
   Walk those step ids in sequence; for each id, find its body in
@@ -455,13 +452,16 @@ Mapping:
   1..N where N is the length of `steps`, not restarting between
   the settings-* and authoring-* runs. The two reference files
   are the step library; the YAML is authoritative for order.
-- **4** → jump to §Final wrap-up.
+
+There is no "finish" option in the menu: the tester ends the
+session by saying they are done (or by completing every tour),
+which routes to §Final wrap-up.
 
 > **Adding a new tour**: append an entry to `master-state.yml.tours`
 > with its `steps` array, create (or extend) a `references/tour-<id>.md`
 > step library with the matching step ids, add a new option to the
-> menu above (and bump the "I'm done" option number), and add a
-> mapping row here. Keep step id prefixes consistent with the file
+> menu above, and add a mapping row here. Keep step id prefixes
+> consistent with the file
 > name so the dispatch stays mechanical.
 
 After a tour finishes, mark it `done` in `master-state.yml`,
@@ -470,12 +470,12 @@ the menu**. Re-render every option using the same layout from
 §Rendering rules above (plain bold title line + single-level `> `
 description line, back-to-back, one blank line between options,
 no outer blockquote), prefixing the title of any completed tour
-with `✓ ` (e.g. `**1. ✓ Built-in plugins** (~13 min)`). Skip the
+with `✓ ` (e.g. `**2. ✓ Built-in plugins** (~13 min)`). Skip the
 intro sentence ("All set up...") and close with:
 
 What next?
 
-If they say "I'm done" or pick option 4, jump to §Final wrap-up.
+If they say "I'm done" (or have completed every tour), jump to §Final wrap-up.
 
 ## Per-step cycle (inside a tour)
 
@@ -498,8 +498,8 @@ For every step in the tour:
    **Numbering rule**: `N` is the 1-based index of the current
    step inside the picked tour's `steps` array in
    `master-state.yml`. The count **resets to 1 when the tester
-   picks a new tour**, so the first step of `plugins-tour` is
-   "Step 1", the first step of `settings-and-consent` (after
+   picks a new tour**, so the first step of `settings` is
+   "Step 1", the first step of `plugins-tour` (after
    returning to the menu and picking option 2) is again "Step 1",
    and the first step of `build-and-configure` (option 3) is
    again "Step 1" and runs straight through to "Step 7" without
@@ -578,8 +578,8 @@ orchestrator, the tour file is the lesson.
 
 | Menu option | Tour id                 | Reference file(s)                                                                          |
 |-------------|-------------------------|--------------------------------------------------------------------------------------------|
-| 1           | `plugins-tour`          | `references/tour-plugins.md`                                                               |
-| 2           | `settings-and-consent`  | `references/tour-settings.md` (settings-* steps only)                                      |
+| 1           | `settings`              | `references/tour-settings.md` (settings-* steps only)                                      |
+| 2           | `plugins-tour`          | `references/tour-plugins.md`                                                               |
 | 3           | `build-and-configure`   | both `references/tour-settings.md` (settings-* steps) AND `references/tour-authoring.md` (authoring-* steps), dispatched by step id |
 
 Each tour file contains: a short overview, a precondition check
@@ -596,8 +596,8 @@ and re-render the menu.
 
 ## Final wrap-up
 
-When the tester picks option 4 or signals they are done, show the
-closing block:
+When the tester signals they are done (or has completed every
+tour), show the closing block:
 
 > Thanks! That's a wrap.
 >

package/dist/cli/tutorial/sm-master/references/fixture-templates.md

@@ -147,8 +147,25 @@ tours:
   # (e.g. tour-foo.md → steps prefixed `foo-*`). The orchestrator
   # in SKILL.md walks this list and dispatches each step id to its
   # reference file.
-  plugins-tour:
+  settings:
     status: "not_started"   # not_started | in_progress | done | declined
+    estimated_min: 10
+    # Config layers + the `sm config` verbs + the active provider
+    # lens. The `.sm` consent gate is covered in the basic
+    # sm-tutorial, not repeated here. Step bodies live in
+    # tour-settings.md (settings-* ids).
+    steps:
+      - id: "settings-1-layers"
+        title: "The config layers and `sm config list`"
+        status: "pending"
+      - id: "settings-2-resolve"
+        title: "Read, resolve, and set a value with `sm config`"
+        status: "pending"
+      - id: "settings-3-lens"
+        title: "The active provider lens (`activeProvider`)"
+        status: "pending"
+  plugins-tour:
+    status: "not_started"
     estimated_min: 13
     # All step bodies live in tour-plugins.md (tour-* ids).
     steps:
@@ -161,18 +178,6 @@ tours:
       - id: "tour-3-explore"
         title: "Explore one extension up close"
         status: "pending"
-  settings-and-consent:
-    status: "not_started"
-    estimated_min: 5
-    # Settings + the `.sm` consent gate. Step bodies live in
-    # tour-settings.md (settings-* ids).
-    steps:
-      - id: "settings-1-project"
-        title: "Project settings: `.skill-map/settings.json`"
-        status: "pending"
-      - id: "settings-2-local"
-        title: "Per-user overrides: `settings.local.json`"
-        status: "pending"
   build-and-configure:
     status: "not_started"
     estimated_min: 17

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

@@ -66,14 +66,10 @@ with you. They DO NOT edit anything yet.
 
 Then narrate, one file at a time:
 
-> **`plugin.json`**: the manifest
+> **`plugin.json`**: the plugin manifest
 >
-> The contract the CLI validates at load.
->
-> **Key fields:**
->
-> - `id`: the kebab-case id you typed. Must match the bundle folder
->   name.
+> The contract the CLI validates at load. It is deliberately lean,
+> four keys:
 >
 > - `version`: starts at `0.1.0`; you bump it yourself, the CLI
 >   does not touch it.
@@ -81,34 +77,37 @@ Then narrate, one file at a time:
 > - `specCompat` / `catalogCompat`: which `sm` and plugin catalog
 >   version your plugin targets.
 >
-> - `settings`: user-configurable knobs. The scaffold ships
->   `keywords`, a `string-list` defaulting to `["TODO", "FIXME"]`.
->   Browse other input types with `sm plugins slots list`.
+> - `description`: the one-liner shown in `sm plugins list`.
 >
-> There is no `extensions` field. The kernel discovers each
-> extension by walking `<plugin-dir>/<kind>s/<name>/index.js`;
-> the folder layout IS the contract.
+> Notice what is NOT here. There is no `id`: the plugin id is the
+> folder name (`demo-highlight`). There is no `extensions` list: the
+> kernel discovers each extension by walking
+> `<plugin-dir>/<kind>s/<name>/index.js`. And there is no `settings`
+> block: settings live per-extension, inside the extractor's
+> `index.js` (you'll see them next). The folder layout IS the
+> contract, that's the "structure-as-truth" idea.
 
 > **`extractors/demo-highlight-extractor/index.js`**: the code
 >
 > Plain JavaScript with a default export. **Structure-as-truth**:
-> the loader derives `id`, `kind`, and `pluginId` from the folder
-> path; the manifest itself never declares them.
+> the loader derives the extension `id` and its `pluginId` from the
+> folder path, so the export never repeats them. It does declare its
+> `kind` (`extractor`), which the loader cross-checks against the
+> parent folder (`extractors/`); a mismatch is rejected at load.
 >
 > **What the loader reads:**
 >
 > - The folder layout tells the loader this is an extractor named
 >   `demo-highlight-extractor` (`extractors/<id>/index.js`).
 >
-> - `ui`: which slots the extension emits to (renamed from
->   `viewContributions` with the structure-as-truth refactor). The
->   scaffold declares `count`, targeting `card.footer.left` (the
->   chip in the bottom-left of every node card). The slot pins
->   both the renderer (`NodeCounter`) and the payload shape.
+> - `ui`: which slots the extension emits to. The scaffold declares
+>   `count`, targeting `card.footer.left` (the chip in the
+>   bottom-left of every node card). The slot pins both the renderer
+>   (`NodeCounter`) and the payload shape.
 >
-> - `settings`: per-extension user-configurable knobs (moved here
->   from `plugin.json` with the same refactor). Exposed at runtime
->   via `ctx.settings.<settingId>`.
+> - `settings`: the per-extension user-configurable knobs, this is
+>   where the `keywords` list lives. Exposed at runtime via
+>   `ctx.settings.<settingId>`.
 >
 > - `extract(ctx)`: the function the kernel runs per node.
 >   `ctx.body` is the markdown body, `ctx.settings` carries what
@@ -158,28 +157,24 @@ content, not configuration). Append at the end:
 - [ ] XXX revisit naming.
 ```
 
-Now re-scan and confirm the extractor picks them up:
+Now re-scan so the extractor re-reads its settings and re-counts:
 
 ```bash
 sm scan
-sm show notes/ideas.md
 ```
 
-`sm show` prints the node's persisted contributions. Look for a
-`count` contribution with `value: 3` (one match per keyword). The
-exact JSON shape is in the body of the `show` output under a
-`contributions` key.
-
-> Three matches. The setting flowed from `plugin.json` through
-> `ctx.settings.keywords` into the extractor, the extractor
-> counted them, the kernel persisted the contribution, `sm show`
-> reads it back. That's the whole loop.
-
-If the tester wants to see it in the UI: ask them to run `sm` in
-the second terminal, open the browser, click `notes/ideas`, and
-spot the new chip in the **left footer** of the card (or the
-bottom-left badge in the inspector). The chip says `🔍 kw 3` (icon
-and label from the manifest's `ui.count`).
+The scan re-emits the contribution with the new count. To actually
+see it we open the UI: `sm show` covers a node's frontmatter, links,
+and issues, but not plugin contributions. Ask the tester to run `sm`
+in the second terminal, open the browser, click `notes/ideas`, and
+spot the chip in the **left footer** of the card (or the bottom-left
+badge in the inspector). It reads `🔍 kw 3`, one match per keyword,
+the icon and label come from the manifest's `ui.count`.
+
+> Three matches. The setting flowed from the extension's `settings`
+> through `ctx.settings.keywords` into the extractor, the extractor
+> counted them, the kernel persisted the contribution, and the UI
+> rendered it. That's the whole loop.
 
 Mark `authoring-3-edit-setting: done`.
 

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

@@ -1,9 +1,9 @@
 # Tour: plugins-tour
 
 Guided tour of the **built-in plugins** that ship with `sm`. Three
-steps: a quick mental model of what bundles are plus a peek at
+steps: a quick mental model of what plugins are plus a peek at
 the catalogue, then the six extension kinds rounded off by opening
-one bundle to see them in the wild, and finally a deeper drill
+one plugin to see them in the wild, and finally a deeper drill
 into a single extension (detail view, diagnostic, disable/enable
 toggle). By the end the tester has the mental model and knows
 which verbs reach which surface.
@@ -22,41 +22,40 @@ restore the files.") and stop.
 
 ## Step `tour-1-intro` — how plugins work (~4 min)
 
-**Context**: A short tour of what a plugin is, how they're
-packaged into bundles, and a peek at the five bundles that ship
+**Context**: A short tour of what a plugin is, how it groups
+extensions, and a peek at the five plugins that ship
 pre-installed.
 
-> Plugins are how skill-map gets extended. A **plugin** groups one
-> or more **extensions**, the actual code units that run inside
-> the kernel. So when we say "skill-map has a plugin for Claude",
-> what we really mean is "there is a plugin called `claude` that
-> contains one extension (a provider) which knows how to walk
-> `.claude/`".
+> Plugins are how skill-map gets extended. A **plugin** is the
+> deployable unit: one directory with a `plugin.json` manifest and
+> the extension code. It groups one or more **extensions**, the
+> actual code units that run inside the kernel. So when we say
+> "skill-map has a plugin for Claude", what we really mean is
+> "there is a plugin called `claude` that contains one extension
+> (a provider) which knows how to walk `.claude/`".
 >
-> Plugins ship as **bundles**. A bundle is the deployable unit,
-> one directory with a `plugin.json` manifest and the extension
-> code. Two ways they reach your project:
+> Two ways plugins reach your project:
 >
-> 📦 **Built-in bundles**
+> 📦 **Built-in plugins**
 >    Travel inside the CLI itself. Available the moment you
 >    `npm install -g @skill-map/cli`.
 >
-> 📥 **Drop-in bundles**
+> 📥 **Drop-in plugins**
 >    You (your company, or someone else) drop them by hand under
 >    `<cwd>/.skill-map/plugins/`. The directory lives inside the
->    project, so a bundle committed here travels with the repo
+>    project, so a plugin committed here travels with the repo
 >    and the rest of the team picks it up on the next pull.
 
 > Now let's look at what's actually installed. `sm plugins list`
-> shows every bundle the CLI shipped with. Run it in your second
+> shows every plugin the CLI shipped with. Run it in your second
 > terminal:
 
 ```bash
 sm plugins list
 ```
 
-> There are the five bundles. The next step zooms into the six
-> kinds of extension that bundles can carry, you'll see at least
+> There are the five plugins. The next step zooms into the six
+> kinds of extension that a plugin can carry, you'll see at least
 > one of each living inside `core`.
 
 Mark `tour-1-intro: done`.
@@ -101,7 +100,7 @@ Mark `tour-1-intro: done`.
 >    newer skill-map is available on npm.
 >    Example: `update-check`.
 >
-> Putting it together: a **bundle** packages one or more
+> Putting it together: a **plugin** packages one or more
 > **extensions**, each extension has a **kind**, the kind decides
 > where it plugs into the kernel.
 >
@@ -111,7 +110,7 @@ Mark `tour-1-intro: done`.
 > from there. CLI and UI use the same store, so a change in one
 > is reflected in the other.
 
-> Now let's see those six kinds inside a real bundle. Open `core`
+> Now let's see those six kinds inside a real plugin. Open `core`
 > in your second terminal:
 
 ```bash
@@ -121,7 +120,7 @@ sm plugins show core
 Expected: the 28 extensions grouped by kind, each row showing its
 kind and qualified id (e.g. `extractor  core/markdown-link`). You
 can spot at least one of each of the six kinds you just read about,
-all packed into a single bundle.
+all packed into a single plugin.
 
 Mark `tour-2-kinds: done`.
 
@@ -139,8 +138,9 @@ the change persists.
 sm plugins show core/external-url-counter
 ```
 
-Expected: a focused detail block for that one extension (header,
-Kind, Version, Stability, Description, Preconditions, Entry).
+Expected: a focused detail block for that one extension, the header
+line (`✓ core/external-url-counter built-in`) plus its Kind
+(`extractor`) and Description.
 
 > Now run the diagnostic. The `doctor` verb reports every plugin
 > and extension status in one go: enabled, disabled, load errors,
@@ -160,15 +160,15 @@ spec-compatibility mismatch, `doctor` is the verb that flags it.
 
 ```bash
 sm plugins disable core/external-url-counter
-sm plugins doctor
+sm plugins show core
 sm plugins enable core/external-url-counter
-sm plugins doctor
+sm plugins show core
 ```
 
-Expected: between the two `doctor` calls, the
-`core/external-url-counter` row flips from `enabled` to
-`disabled` and back. The change persists in the project DB; if
-you restarted `sm`, the disabled state would still be there.
+Expected: between the two `show core` calls, the
+`core/external-url-counter` row flips its marker from `✓` (enabled)
+to `✕` (disabled) and back. The change persists in the project DB;
+if you restarted `sm`, the disabled state would still be there.
 
 Mark `tour-3-explore: done`.
 
@@ -176,8 +176,8 @@ Mark `tour-3-explore: done`.
 
 > All set. You now know:
 >
-> - What plugins, extensions, bundles, and the six kinds are.
-> - Five bundles ship pre-installed (`claude`, `antigravity`,
+> - What plugins, extensions, and the six kinds are.
+> - Five plugins ship pre-installed (`claude`, `antigravity`,
 >   `openai`, `agent-skills`, `core`).
 > - How to list, inspect, diagnose, and toggle extensions from
 >   the CLI (and the same lives in the UI).