# 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.
