@skill-map/cli 0.61.5 → 0.62.1

package/dist/cli/tutorial/sm-tutorial/references/_core.md

@@ -415,7 +415,14 @@ inside the content, mirroring the `✓` confirmations used elsewhere,
 never as a title prefix.
 NO blank line between a title and its description; ONE blank line
 between parts; NO outer blockquote around the whole menu. Close with a
-short "¿Cuál?" / "Which one?" on its own line. Sample (Claude variant,
+short "¿Cuál?" / "Which one?" on its own line.
+
+**Developer aside for section 5 (Extend)**: append to its one-line
+description a short note that this section is mostly for developers
+who want to get more out of skill-map (writing plugins, tuning
+settings, moving view-slots). Mirror the tester's language.
+
+Sample (Claude variant,
 fill the parts and durations from `_manifest.yml`):
 
 ```

package/dist/cli/tutorial/sm-tutorial/references/_manifest.json

@@ -205,7 +205,7 @@
         },
         {
           "id": "authoring-1-scaffold",
-          "title": "`sm plugins create demo-highlight`",
+          "title": "`sm plugins create extractor demo-highlight`",
           "est_min": 2
         },
         {
@@ -223,20 +223,10 @@
           "title": "Change the view-slot the contribution targets",
           "est_min": 2
         },
-        {
-          "id": "settings-6-contributions",
-          "title": "Watch contributions land in the inspector",
-          "est_min": 2
-        },
         {
           "id": "authoring-5-doctor-author",
           "title": "Catch a manifest mistake with `sm plugins doctor`",
           "est_min": 2
-        },
-        {
-          "id": "authoring-6-upgrade",
-          "title": "Try `sm plugins upgrade`",
-          "est_min": 2
         }
       ]
     },

package/dist/cli/tutorial/sm-tutorial/references/_manifest.yml

@@ -72,13 +72,11 @@ parts:
       - id: tour-1-intro             ; title: "How plugins work" ; est_min: 4
       - id: tour-2-kinds             ; title: "The six extension kinds" ; est_min: 5
       - id: tour-3-explore           ; title: "Explore one extension up close" ; est_min: 4
-      - id: authoring-1-scaffold     ; title: "`sm plugins create demo-highlight`" ; est_min: 2
+      - id: authoring-1-scaffold     ; title: "`sm plugins create extractor demo-highlight`" ; est_min: 2
       - id: authoring-2-anatomy      ; title: "Tour the scaffold (plugin.json + stubs + README)" ; est_min: 3
       - id: authoring-3-edit-setting ; title: "Edit a setting (string-list) and observe it in the UI" ; est_min: 3
       - id: authoring-4-edit-slot    ; title: "Change the view-slot the contribution targets" ; est_min: 2
-      - id: settings-6-contributions ; title: "Watch contributions land in the inspector" ; est_min: 2
       - id: authoring-5-doctor-author ; title: "Catch a manifest mistake with `sm plugins doctor`" ; est_min: 2
-      - id: authoring-6-upgrade      ; title: "Try `sm plugins upgrade`" ; est_min: 2
 
   - id: cli
     order: 5

package/dist/cli/tutorial/sm-tutorial/references/part-authoring.md

@@ -19,7 +19,7 @@ of whether the tester ran the plugins chapters first). If `.skill-map/` is missi
 is corrupted: surface the mismatch ("the project bootstrap is
 gone, re-invoke the tutorial from an empty dir") and stop.
 
-## Step `authoring-1-scaffold` - `sm plugins create demo-highlight` (~2 min)
+## Step `authoring-1-scaffold` - `sm plugins create extractor demo-highlight` (~2 min)
 
 **Context**: We're building `demo-highlight`: a tiny extractor
 that scans each node's body for the keywords `TODO` and `FIXME`
@@ -31,7 +31,7 @@ manifest on purpose to see the diagnostic catch it.
 > Let's scaffold it with `sm plugins create`:
 
 ```bash
-sm plugins create demo-highlight
+sm plugins create extractor demo-highlight
 ```
 
 Expected output:
@@ -39,9 +39,9 @@ Expected output:
 ```
 Created /<cwd>/.skill-map/plugins/demo-highlight
 Next:
-  - Edit demo-highlight/extractors/demo-highlight-extractor/index.js (the extract() body)
-  - Run sm scan to see the contribution surface
-  - sm plugins slots list: browse other slots
+  - Edit extractors/demo-highlight-extractor/index.js
+  - Run sm plugins doctor to confirm it loads
+  - sm plugins slots list: browse slots and input-types
 ```
 
 **Heads up on the id**: it must be **kebab-case lowercase**, no
@@ -89,35 +89,25 @@ Then narrate, one file at a time:
 > **`extractors/demo-highlight-extractor/index.js`**: the code
 >
 > Plain JavaScript with a default export. **Structure-as-truth**:
-> 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.
+> the loader derives the extension `kind` (`extractor`), its `id`,
+> and its `pluginId` from the folder path, so the export never
+> repeats them. Re-declaring `kind` or `id` is rejected at load as
+> `invalid-manifest`.
 >
 > **What the loader reads:**
 >
-> - The folder layout tells the loader this is an extractor named
->   `demo-highlight-extractor` (`extractors/<id>/index.js`).
+> - **folder layout**: marks this as the extractor
+>   `demo-highlight-extractor`.
+> - **`ui`**: where the chip shows. The scaffold sends `count` to
+>   the `card.footer.left` slot; the slot picks the renderer and
+>   payload shape for you.
+> - **`settings`**: the user knobs (here, the `keywords` list),
+>   read at runtime via `ctx.settings`.
+> - **`extract(ctx)`**: runs once per node. It reads the body from
+>   `ctx.body` and emits the count via `ctx.emitContribution`.
 >
-> - `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`: 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
->   the user set on this extension, and `ctx.emitContribution(id,
->   payload)` sends data to the slot.
->
->   Heads up: the body has `|| ['TODO', 'FIXME']` as a defensive
->   fallback in case `ctx.settings` is missing. In normal
->   operation the kernel always passes the manifest's default (or
->   the user's override), so the hardcoded list is never used,
->   the manifest is the real source of truth.
+> The `|| ['TODO', 'FIXME']` you see in the code is just a safety
+> fallback; the real keyword list comes from the manifest.
 
 > **`README.md`**: the docs
 >
@@ -162,13 +152,10 @@ Now re-scan so the extractor re-reads its settings and re-counts:
 sm scan
 ```
 
-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`.
+The scan re-emits the contribution with the new count. To see it,
+run `sm`, open the browser, click `notes/ideas`, and find the chip
+in the card's **left footer** (it also shows in the inspector). It
+reads `🔍 kw 3`, one match per keyword.
 
 > Three matches. The setting flowed from the extension's `settings`
 > through `ctx.settings.keywords` into the extractor, the extractor
@@ -179,14 +166,14 @@ Mark `authoring-3-edit-setting: done`.
 
 ## Step `authoring-4-edit-slot` - change the view-slot (~2 min)
 
-> Same contribution, different home. We'll move it from the
-> footer to the top-right corner of the card.
+> Same contribution, different home. We'll move it from the left
+> footer to the right footer of the card.
 
 The tester edits the extractor source:
 
 > Open `.skill-map/plugins/demo-highlight/extractors/demo-highlight-extractor/index.js`.
-> Find the `ui.count.slot` line. Change
-> `'card.footer.left'` to `'card.title.right'`. Save.
+> Find the `slot` line in the `count` contribution. Change
+> `'card.footer.left'` to `'card.footer.right'`. Save.
 
 Re-scan:
 
@@ -197,17 +184,22 @@ sm scan
 If `sm` is still running, the watcher picks up the file change
 and re-emits contributions live. If not, run the scan manually.
 
-Refresh the UI, the chip should now appear next to the **title**
-on the node card instead of the footer.
+Refresh the UI, the chip should now appear in the **right footer**
+of the node card instead of the left.
 
 > Notice we did not write any UI code. The slot decides the
-> renderer (`NodeCounter` here, same widget reused across four
-> slots) and the position. You picked a position, the UI did the
-> rest.
+> renderer and the position. You picked a position, the UI did
+> the rest.
 
-**Side trip if the tester asks**: `sm plugins slots list` shows
-all 14 slots with one-line descriptions. They are the closed
-catalogue, picking an unknown slot id is rejected at load.
+> **Two ways to see the whole slot catalogue:**
+>
+> - **In the UI**, add `?debug=1` to the URL. Every view-contribution
+>   slot lights up with a coloured ring and its id, so you can see
+>   exactly where `card.footer.left` and `card.footer.right` sit.
+>   Turn it back off with `?debug=0`.
+> - **In the CLI**, run `sm plugins slots list`: all 14 slots with a
+>   one-line description each. The catalogue is closed, an unknown
+>   slot id is rejected at load.
 
 Mark `authoring-4-edit-slot: done`.
 
@@ -218,7 +210,7 @@ Mark `authoring-4-edit-slot: done`.
 
 Have the tester change the slot to a value that does not exist:
 
-> In the same file, change `'card.title.right'` to
+> In the same file, change `'card.footer.right'` to
 > `'card.footer.bottom'` (made up). Save.
 
 ```bash
@@ -233,7 +225,7 @@ on `demo-highlight`, pointing at the unknown slot name.
 > the loader catches the typo before any scan happens.
 
 Restore the slot to a real value (back to `'card.footer.left'` or
-`'card.title.right'`, the tester's choice) and re-run doctor:
+`'card.footer.right'`, the tester's choice) and re-run doctor:
 
 ```bash
 sm plugins doctor
@@ -243,29 +235,6 @@ Back to clean.
 
 Mark `authoring-5-doctor-author: done`.
 
-## Step `authoring-6-upgrade` - `sm plugins upgrade` (~2 min)
-
-> One last verb. `sm plugins upgrade` applies catalog migrations
-> to plugin manifests. Today the catalog is at `1.0.0` with zero
-> migrations registered, so the verb is a **no-op**. The point of
-> the step is to know the verb exists and what it does.
-
-```bash
-sm plugins upgrade
-sm plugins upgrade demo-highlight
-```
-
-Expected: both report no migrations to apply.
-
-> When the catalog evolves (slot renames, deprecations, setting
-> shape changes), `sm plugins upgrade` is the verb that walks
-> your manifests and rewrites them to the new shape. Without
-> that, every catalog change would force every plugin author to
-> re-author by hand. The structure is in place so future bumps
-> land smoothly.
-
-Mark `authoring-6-upgrade: done`.
-
 ## Wrap-up (fires at the end of the authoring chapters)
 
 > You wrote a plugin. From here:
@@ -277,8 +246,6 @@ Mark `authoring-6-upgrade: done`.
 >   misalign them.
 > - `sm plugins doctor` is the diagnostic verb, run it after any
 >   manifest edit.
-> - `sm plugins upgrade` is the migration verb (no-op today, the
->   structure is ready for future catalog changes).
 >
 > Anything weird worth logging? If not, back to the menu.
 

package/dist/cli/tutorial/sm-tutorial/references/part-plugins.md

@@ -97,8 +97,8 @@ Mark `tour-1-intro: done`.
 > 🎣 **hook**
 >    Fires on one of 10 lifecycle events (`boot`, `scan.started`,
 >    `shutdown`, etc.). `update-check`, for instance, listens on
->    `boot` (throttled to once a day) and prints a banner if a
->    newer skill-map is available on npm.
+>    `boot` and prints a banner if a newer skill-map is available
+>    on npm.
 >    Example: `update-check`.
 >
 > Putting it together: a **plugin** packages one or more
@@ -106,10 +106,11 @@ Mark `tour-1-intro: done`.
 > where it plugs into the kernel.
 >
 > Heads up: every `sm plugins` verb you'll run in this part is
-> also available from the UI. From any `sm serve` session, open
-> the **gear icon → Plugins** tab to browse and toggle plugins
-> from there. CLI and UI use the same store, so a change in one
-> is reflected in the other.
+> also available from the UI. From any `sm` session, open the
+> **Settings** panel (the sliders icon, top-right) and its
+> **Plugins** tab to browse and toggle plugins 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 plugin. Open `core`
 > in your second terminal:
@@ -121,7 +122,9 @@ sm plugins list core
 Expected: the 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 plugin.
+all packed into a single plugin. A few rows are marked `✕` with an
+`(experimental)` tag, those extensions ship disabled by default;
+you'll toggle one yourself in the next step.
 
 Mark `tour-2-kinds: done`.
 
@@ -151,8 +154,10 @@ line (`✓ core/external-url-counter built-in`) plus its Kind
 sm plugins doctor
 ```
 
-Expected on a clean machine: `35 enabled extensions · 0 issues · 0 warnings`.
-If any plugin reports a load error, manifest validity issue, or
+Expected on a clean machine: `30 enabled extensions · 0 issues · 0 warnings`.
+That counts the enabled extensions only, the experimental ones you
+saw marked `✕` ship disabled, so they sit outside this total. If any
+plugin reports a load error, manifest validity issue, or
 spec-compatibility mismatch, `doctor` is the verb that flags it.
 
 > Last, toggle one extension off and back on so you see the state

package/dist/cli/tutorial/sm-tutorial/references/part-settings.md

@@ -1,10 +1,9 @@
 # Part 4 (a): Extend skill-map - settings (step library, `settings-*` ids)
 
 Step bodies for the settings chapters of Part 4 (config layers, the
-`sm config` verbs, the active provider lens), plus the shared step
-`settings-6-contributions` that the plugin-authoring chapters reuse.
-The SKILL.md orchestrator dispatches each `settings-*` chapter id
-here; `authoring-*` ids it dispatches to `part-authoring.md`.
+`sm config` verbs, the active provider lens). The SKILL.md
+orchestrator dispatches each `settings-*` chapter id here;
+`authoring-*` ids it dispatches to `part-authoring.md`.
 
 The `.sm` consent gate (companion files, `allowEditSmFiles`,
 `sm sidecar annotate`) is covered elsewhere in this tutorial, so
@@ -126,16 +125,16 @@ Mark `settings-2-resolve: done`.
 
 **Context**: the single most consequential setting, the lens that
 decides which provider types the project's files. It auto-detects and
-never touches your `.md` files, only the scan cache.
+never touches your `.md` files.
 
 > 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. Same files, one reading.
+> skill-map project reads its files through exactly **one** provider
+> at a time, and that lens decides how each file is interpreted, so
+> the same files can read differently depending on which lens is active.
 
-> The lens auto-detects on the first scan from the markers in your
-> project (`.claude/` → claude). Scan once and check where it landed:
+> The lens auto-detects on the first scan from your project's layout
+> (a `.claude/` folder selects the `claude` lens). Scan once and check
+> where it landed:
 
 ```bash
 sm scan
@@ -157,53 +156,6 @@ is just a key in `settings.json`, persisted like any other setting.
 
 Mark `settings-3-lens: done`.
 
-## Step `settings-6-contributions` - watch contributions land (~2 min)
-
-> 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 fundamentals part:
-`sm`, copy the link from the output, open the browser, arrange
-the screen). If `sm` is still running, leave it.
-
-```bash
-sm
-```
-
-Once the UI is open, ask the tester to:
-
-> 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
-> `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 chapters
-of this part is still installed, point the tester at the
-contribution it emits too:
-
-> The `demo-highlight` you scaffolded earlier in this part also
-> shows up: its chip lands on every node that has a TODO / FIXME
-> / XXX in its body. Click `notes/ideas` to find it.
-
-Have the tester change `master-agent`'s `tools` array (add or
-remove one tool), save, and watch the chip refresh.
-
-> Same flow as the fundamentals part'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 (`card.footer.left`). You now know the full path from `.md`
-> to UI chip.
-
-Have them Ctrl+C the server when done.
-
-Mark `settings-6-contributions: done`.
-
 ## Reference: where each catalogue lives in the repo
 
 Not for the tester unless they ask. Cheat sheet for the agent: