@skill-map/cli 0.29.0 → 0.31.0

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

@@ -0,0 +1,209 @@
+# 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
+the catalogue, then the six extension kinds rounded off by opening
+one bundle 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.
+
+## Precondition check
+
+Before announcing the first step, verify the fixture is initialised
+(the cwd has `.claude/agents/master-agent.md`,
+`.claude/skills/master-skill/SKILL.md`, AND `.skill-map/` with
+`settings.json` and `skill-map.db`). Pre-flight already ran
+`sm init --no-scan` and appended the master entries to
+`.skillmapignore`. If any of that is missing, surface the
+bootstrap mismatch ("master-state.yml says we are running, but
+the bootstrap is missing. Run `sm-master` from an empty dir or
+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 four bundles 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 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:
+>
+> 📦 **Built-in bundles**
+>    Travel inside the CLI itself. Available the moment you
+>    `npm install -g @skill-map/cli`.
+>
+> 📥 **Drop-in bundles**
+>    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
+>    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
+> terminal:
+
+```bash
+sm plugins list
+```
+
+> There are the four bundles. The next step zooms into the six
+> kinds of extension that bundles can carry, you'll see at least
+> one of each living inside `core`.
+
+Mark `tour-1-intro: done`.
+
+## Step `tour-2-kinds` — the six extension kinds (~5 min)
+
+> An extension has a **kind**. The kind tells the kernel where it
+> plugs into the pipeline. There are exactly six kinds:
+>
+> 🗂️ **provider**
+>    Decides what kind each `.md` file is. The `claude` provider,
+>    for instance, walks `.claude/` and types each file it finds
+>    (agent, command, or skill).
+>    Examples: `claude`, `gemini`, `agent-skills`.
+>
+> 🔍 **extractor**
+>    Reads a node's body and emits structured findings (links,
+>    counts, annotations).
+>    Example: `markdown-link`, `external-url-counter`, `tools-count`.
+>
+> 🩺 **analyzer**
+>    Cross-checks the scan and emits issues plus various
+>    detections (errors, warnings, informational signals: broken
+>    refs, stale annotations, schema drift, and more).
+>    Example: `broken-ref`, `stability`, `unknown-field`.
+>
+> ⚡ **action**
+>    Performs a write operation on a node, the graph, or the
+>    filesystem. May modify your `.md` files (frontmatter, body)
+>    ONLY with your explicit permission.
+>    Examples: `bump`, `mark-superseded`.
+>
+> 🎨 **formatter**
+>    Renders a result in a specific shape (`sm export --format md`
+>    and `--format json`).
+>    Example: `ascii`, `json`.
+>
+> 🎣 **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.
+>    Example: `update-check`.
+>
+> Putting it together: a **bundle** packages one or more
+> **extensions**, each extension has a **kind**, the kind decides
+> where it plugs into the kernel.
+>
+> Heads up: every `sm plugins` verb you'll run in this tour 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.
+
+> Now let's see those six kinds inside a real bundle. Open `core`
+> in your second terminal:
+
+```bash
+sm plugins show core
+```
+
+Expected: a table with 24 rows, each carrying `kind/id@version`.
+You can spot at least one of each of the six kinds you just read
+about, all packed into a single bundle.
+
+Mark `tour-2-kinds: done`.
+
+## Step `tour-3-explore` — explore one extension up close (~4 min)
+
+**Context**: Drill into a single extension to see its detail,
+run the diagnostic, then toggle one off and back on so you see
+the change persists.
+
+> Pick one extension and look at its details. We'll use
+> `core/external-url-counter`, an extractor that counts how many
+> external URLs each node body contains:
+
+```bash
+sm plugins show core/external-url-counter
+```
+
+Expected: a focused detail block for that one extension (header,
+Kind, Version, Stability, Description, Preconditions, Entry).
+
+> Now run the diagnostic. The `doctor` verb reports every plugin
+> and extension status in one go: enabled, disabled, load errors,
+> spec compatibility, manifest validity.
+
+```bash
+sm plugins doctor
+```
+
+Expected on a clean machine: `27 enabled · 0 issues · 0 warnings`.
+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
+> persists across CLI invocations. We'll use the same one you
+> inspected above:
+
+```bash
+sm plugins disable core/external-url-counter
+sm plugins doctor
+sm plugins enable core/external-url-counter
+sm plugins doctor
+```
+
+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.
+
+Mark `tour-3-explore: done`.
+
+## Tour wrap-up
+
+> All set. You now know:
+>
+> - What plugins, extensions, bundles, and the six kinds are.
+> - Four bundles ship pre-installed (`claude`, `gemini`,
+>   `agent-skills`, `core`).
+> - How to list, inspect, diagnose, and toggle extensions from
+>   the CLI (and the same lives in the UI).
+>
+> If you want to dig deeper, the next menu option takes you into
+> authoring your own plugin and into settings + view-slots. Or
+> if you've seen enough, "I'm done for today" closes us out.
+>
+> Anything weird worth logging? If not, back to the menu.
+
+Mark tour `plugins-tour: done` in `master-state.yml`, update the
+matching harness task, return to the menu in `SKILL.md`.
+
+## Reference: how `sm` decides what to load
+
+Not for the tester unless they ask. Cheat sheet for the agent:
+
+- Built-in plugins live inside the CLI bundle and are always
+  discovered first.
+- Project plugins live under `<cwd>/.skill-map/plugins/`; the
+  authoring tour uses this path. There is no user / global
+  scope, `-g/--global` and `~/.skill-map/plugins/` were removed
+  in v0.27.x.
+- Load order: built-in → project (project ids that collide with
+  built-in are surfaced by `doctor`).
+- `disable`/`enable` writes the state into the project DB; it
+  survives restarts.
+- Escape hatch for one-off probing without committing a plugin to
+  the project: pass `--plugin-dir <path>` on the `sm plugins …`
+  verb family.

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

@@ -0,0 +1,170 @@
+# 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
+option 3 (`build-and-configure`). The SKILL.md orchestrator
+dispatches each `settings-*` id here; `authoring-*` ids it
+dispatches to `tour-authoring.md`.
+
+## Precondition check
+
+Same as the authoring step library: `.skill-map/` must exist in
+the cwd (pre-flight step 4 of `SKILL.md` ran `sm init --no-scan`
+and appended the master-tutorial's internal entries to
+`.skillmapignore`, so this is the expected state). If
+`.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)
+
+> 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.
+
+```bash
+cat .skill-map/settings.json
+```
+
+Expected output on a fresh init:
+
+```json
+{
+  "schemaVersion": 1
+}
+```
+
+> 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.
+
+Mark `settings-1-project: done`.
+
+## Step `settings-2-local` — per-user overrides (~3 min)
+
+> 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.
+
+```bash
+cat .skill-map/settings.local.json
+```
+
+Expected on a fresh init:
+
+```json
+{}
+```
+
+> 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:
+
+```bash
+sm sidecar annotate notes/ideas.md
+cat .skill-map/settings.local.json
+```
+
+Expected: now contains `{"allowEditSmFiles": true}` (plus a
+`notes/ideas.sm` file landed next to the markdown).
+
+> 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.
+
+Mark `settings-2-local: 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-count` 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:
+`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:
+
+> 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-count`
+> showing the value `3`.
+>
+> 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 }`.
+
+If the `demo-highlight` plugin from the earlier authoring steps
+of this tour is still installed, point the tester at the
+contribution it emits too:
+
+> The `demo-highlight` you scaffolded earlier in this tour 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 basic tutorial's live UI: edit the markdown,
+> watch the UI refresh. The difference is that the value flowed
+> through a plugin (`core/tools-count`) and landed in a specific
+> slot (`inspector.header.badge.counter`). 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:
+
+- **Slot catalogue (normative)**:
+  `spec/schemas/view-slots.schema.json` (enum + payload schemas).
+- **Slot catalogue (UI mirror)**: `ui/src/app/slots/slot-config.ts`
+  (layout) and `ui/src/app/slots/slot-renderer-map.ts` (renderer
+  binding).
+- **Input-types catalogue (normative)**: `spec/input-types.md`.
+- **Plugin manifest schema**:
+  `spec/schemas/plugin-manifest.schema.json`.
+- **Author tutorial**: `spec/plugin-author-guide.md`.
+- **Slot annex for agents**: `context/view-slots.md`.