@skill-map/cli 0.15.0 → 0.16.1

package/README.md

@@ -25,6 +25,22 @@ npx @skill-map/cli --version
 
 Both `sm` (short, daily use) and `skill-map` (full name, scripts) are registered as binaries after install. The package name is scoped (`@skill-map/cli`) to sit alongside `@skill-map/spec` under the same npm org; the binaries keep the unprefixed names for ergonomics.
 
+## Interactive tutorial (recommended starting point)
+
+If you use [Claude Code](https://claude.ai/code), `sm tutorial` is the fastest way to learn the CLI and the live UI without committing your real project to anything:
+
+```bash
+mkdir try-skill-map && cd try-skill-map
+sm tutorial                  # writes sm-tutorial.md into the empty dir
+claude                       # open Claude Code in the same dir
+# Inside Claude:
+ejecutá @sm-tutorial.md
+```
+
+Claude loads the SKILL.md and runs the demo (~7 min): fixture, `sm init`, live UI, four "reveals" that show the watcher in action, plus the `.skillmapignore` hide-a-file flow. An optional deep-dive (~30-40 min) covers the rest of the CLI surface (`list`, `graph`, `export`, `orphans`, `plugins`, `db ops`).
+
+The verb `sm tutorial` writes a single self-contained file; the SKILL.md ships inside this package, so no extra install needed.
+
 ## Usage
 
 ```bash

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

@@ -53,16 +53,43 @@ optional second phase (~30-40 min) covering the rest of the CLI.
   the Tone bullets above, voseo and all); if in English, run it in
   plain English. Internal narration in this SKILL.md stays in
   English regardless.
+- **Never emit bilingual user-facing copy**. The samples in the
+  blockquotes throughout this SKILL are written in English as the
+  base; translate the entire block to Spanish when the tester
+  speaks Spanish. Do NOT show "Spanish / English" pairs inline,
+  do NOT keep one sentence in English while another is in Spanish,
+  do NOT sprinkle isolated Spanish words inside English paragraphs
+  (or vice versa). Pick one language and commit.
+- **Fixture content also follows the tester's language**. When you
+  `Write` the demo `.md` files (frontmatter `description`, body
+  prose, link anchor text, list items), translate the human text
+  to the tester's language. **Keep these English regardless**:
+  file paths and filenames (`.claude/agents/demo-agent.md`),
+  frontmatter keys (`name`, `description`, `metadata`, `tools`,
+  `event`, etc.), node identifiers (`demo-agent`, `demo-skill`),
+  link target paths inside `[...]( ... )`, code snippets, fenced
+  blocks, and anything the kernel parses structurally. Only the
+  natural-language portions get translated — schema and identifiers
+  stay stable so the watcher and link extractors keep working.
 
 ## Inviolable rules
 
 1. **You DO NOT run `sm` verbs for the tester** except `sm version`
    ONCE during pre-flight to verify the install. Your responsibilities:
    - Write fixture files and `tutorial-state.yml` directly in the cwd.
-   - Edit `.md` files when a step calls for it (the live-UI demo
-     needs this so the watcher has something to react to).
+   - Edit `.md` fixture files when a step calls for it (the live-UI
+     demo needs this so the watcher has something to react to).
    - Read files to verify what the tester modified.
    - Everything else is run by the tester.
+   - **Configuration files are off-limits to your editing tools**:
+     `.skillmapignore`, `.skill-map/settings.json`,
+     `.skill-map/settings.local.json`, and `.gitignore` are
+     ALWAYS edited by the tester, never by you. When a step calls
+     for a change to one of those, you describe the edit in a
+     blockquote and the tester applies it in their own editor.
+     The pedagogical point is that those files belong to the user
+     — they need to internalise where they live and how to change
+     them. Doing it for them defeats the lesson.
 2. **After every command block, stop and wait.** The tester pastes
    the output or replies "OK" / "done". Only then do you advance.
 3. **Persist progress after every step / stage.** Update
@@ -349,7 +376,7 @@ Mark `1-version: done`.
 
 **Context**: `sm init` creates a hidden `.skill-map/` folder in the
 cwd holding the database where skill-map stores what it learns about
-the project. It also drops a `.skill-mapignore` in the cwd with
+the project. It also drops a `.skillmapignore` in the cwd with
 default exclusions. Mandatory first step.
 
 ```bash
@@ -358,10 +385,10 @@ ls -la .skill-map/
 ```
 
 Expected: `.skill-map/skill-map.db` appears (plus config files), and
-a `.skill-mapignore` shows up at the root.
+a `.skillmapignore` shows up at the root.
 
 **After init**, you append the tutorial's entries to the
-`.skill-mapignore` that `sm init` just created (do not create a new
+`.skillmapignore` that `sm init` just created (do not create a new
 file — append to the existing one with `Edit`). This prevents
 `sm scan` from picking up the tutorial's internal files as graph nodes:
 
@@ -385,18 +412,25 @@ starts the UI server with the watcher built in. One process, one
 terminal: it boots the server, scans the `.md` files, detects
 changes, and pushes events over WebSocket to the live UI.
 
-This step has **three reveals**, each one driven by you editing
-files while the server stays up:
+This step has **five reveals**, each one driven by you editing
+files while the server stays up — except Reveal 3, where the
+tester takes the keyboard for the first time.
 
 1. **Reveal 1 (boot)** — one node alone (the agent).
 2. **Reveal 2 (kinds)** — the four other kinds appear as new nodes,
    still unconnected.
-3. **Reveal 3 (connectors)** — the connectors light up between all
+3. **Reveal 3 (your first edit)** — the **tester** edits the
+   `description` of the agent's `.md` and watches the card
+   refresh in the graph.
+4. **Reveal 4 (connectors)** — the connectors light up between all
    five nodes.
+5. **Reveal 5 (ignore)** — a private file appears, then disappears
+   the moment a pattern is added to `.skillmapignore`.
 
-The pedagogical arc: a single dot → a constellation of dots → a
-graph. Each reveal stops at a confirm prompt before you do the
-next.
+The pedagogical arc: a single dot → a constellation of dots →
+your own edit lands → graph → a graph that respects the user's
+ignore list. Each reveal stops at a confirm prompt before you do
+the next.
 
 **Command** (one terminal):
 
@@ -404,6 +438,28 @@ next.
 sm
 ```
 
+Before Reveal 1, ask the tester to set up a **side-by-side view** so
+they can watch the magic happen without alt-tabbing every reveal.
+Tell the tester:
+
+> Arrange your screen so two windows are visible at the same time:
+>
+> 1. **The browser** at `http://127.0.0.1:4242` — where the graph
+>    will update in real time.
+> 2. **This terminal** — the one where you're talking to me. You'll
+>    see me announce each reveal here, then confirm what you see
+>    in the browser.
+>
+> The third window — the terminal running `sm` — you can leave
+> minimized or off to the side; it will just print scan progress
+> lines and you don't need to read them.
+>
+> A typical layout: browser on the left half, this chat on the
+> right half. Or any split that lets you see both at once. Tell
+> me when you're set up and we start.
+
+Wait for confirmation before moving on.
+
 #### Reveal 1 — the lone agent
 
 Tell the tester:
@@ -507,42 +563,62 @@ Create these four files (with `Write`), exactly in this order:
    wired into the rest of the fixture next.
    ```
 
-4. `notes/todo.md` (kind: note — has a **deliberately broken link**
-   that we exploit later in stage L4):
+4. `notes/todo.md` (kind: note):
    ```markdown
    ---
    name: Demo TODO list
    description: |
      Live list of things to review in the demo. Will become the
      hub between skill / agent / command / hook in the next
-     reveal. Contains a broken link on purpose for the broken-ref
-     stage later on.
+     reveal.
    tags: [notes, demo]
    metadata:
      version: "1.0.0"
    ---
 
    # Pending
-
-   - [ ] Document the [flow diagram](./missing-page.md) — broken
-         link on purpose, leave it.
    ```
 
 Tell the tester:
 
-> Mirá el navegador / Look at the browser. Four new nodes should
-> have popped in: `demo-skill`, `demo-command`, `demo-hook`, and
+> Look at the browser. Four new nodes should have popped in:
+> `demo-skill`, `demo-command`, `demo-hook`, and
 > `notes/todo`. Five total now, **still unconnected** — they're
-> floating dots.
->
-> If you don't see them, zoom out with the mouse wheel or the UI
-> zoom control — new nodes sometimes land off-screen.
+> floating dots. The viewport auto-fits whenever a node is added or
+> removed, so all five should be visible without panning.
 >
 > Did the four appear? Confirm so we can wire them up.
 
 Wait for confirmation.
 
-#### Reveal 3 — the connectors light up
+#### Reveal 3 — your first edit
+
+Up to here you've been watching the agent write files. Now hand
+the keyboard over: the lesson is that the watcher reacts to
+**any** `.md` edit under the cwd, not just to files the agent
+authors. After this beat, the tester has the muscle memory for
+"save → graph updates", which Reveal 5 (`.skillmapignore`) reuses
+verbatim.
+
+Tell the tester:
+
+> Tu turno. Open `.claude/agents/demo-agent.md` in your editor of
+> choice. In the frontmatter, change the `description:` field to
+> any text you want — the actual content does not matter, just
+> make it different from what's there now. Save the file.
+>
+> Watch the browser. The `demo-agent` card should refresh its
+> description in real time, no reload, no Ctrl+C — same watcher
+> that picked up the four new nodes a moment ago, this time
+> reacting to YOUR edit.
+>
+> Confirm so we wire the five up.
+
+Wait for confirmation. You MAY use `Read` on the file afterwards
+to verify the change landed (read-only, allowed under Inviolable
+rule #1) before moving on.
+
+#### Reveal 4 — the connectors light up
 
 Now you edit the existing files to add the cross-fixture links —
 each one becomes a connector in the graph. Apply with `Edit` (do
@@ -571,11 +647,9 @@ not rewrite the files):
    See [pending items](../../notes/todo.md) for operational
    context.
    ```
-5. **Edit `notes/todo.md`** — replace the existing single bullet
-   with these three (keep the broken-link bullet intact):
+5. **Edit `notes/todo.md`** — append these two bullets after the
+   `# Pending` heading:
    ```markdown
-   - [ ] Document the [flow diagram](./missing-page.md) — broken
-         link on purpose, leave it.
    - [ ] Polish the
          [demo-skill](../.claude/skills/demo-skill/SKILL.md)
          prompt.
@@ -585,8 +659,8 @@ not rewrite the files):
 
 Tell the tester:
 
-> Mirá la magia de nuevo / Look at the magic again. The five
-> floating nodes should now be wired together — connectors light
+> Look at the magic again. The five floating nodes should now be
+> wired together — connectors light
 > up between them as the watcher picks up each edit:
 >
 > - `demo-skill → demo-agent`
@@ -595,18 +669,117 @@ Tell the tester:
 > - `demo-hook → notes/todo`
 > - `notes/todo → demo-skill`, `notes/todo → demo-hook`
 >
-> The intentional broken link inside `notes/todo` (pointing at the
-> non-existent `missing-page.md`) does **not** show up as a
-> connector in the graph — it surfaces as a `broken-ref` **issue**
-> on the `notes/todo` node (look for a warning marker on the node
-> or open it in the inspector). We'll explore that issue properly
-> in stage L4 if you continue with the deeper part.
+> Confirm. If a connector is missing, refresh the browser and tell
+> me.
+
+Wait for confirmation. **Do NOT move on to Reveal 5** until the
+connectors are confirmed visible — Reveal 5 reuses the same live UI
+session.
+
+#### Reveal 5 — silence a private file via `.skillmapignore`
+
+The first four reveals showed the watcher picking up new files and
+edits (yours and theirs). Reveal 5 flips the direction: a file the
+tester DOES NOT want
+in the graph (a draft, a scratch file, a secret) gets hidden by a
+single line in `.skillmapignore`. Same live mechanism — no restart.
+
+`sm init` already wrote a starter `.skillmapignore` at the scope
+root. The flow has three beats:
+
+**Beat A — you create one new fixture file (the agent does this).**
+
+`Write` `notes/private-credentials.md` — kind `note`, simulates a
+file the tester would never want surfacing publicly:
+
+```markdown
+---
+name: private-credentials
+description: |
+  Personal API tokens — exists in the repo but should not show
+  up in the skill-map graph. Demonstrates the .skillmapignore
+  flow.
+metadata:
+  version: "0.0.1"
+---
+
+# Private
+
+API_TOKEN: example-not-real
+```
+
+Confirm the file appears in the graph as a sixth node
+(`notes/private-credentials`). The watcher sees it like any
+other `.md` — that's the point of the demo.
+
+**Beat B — you show the project structure (the agent does this).**
+
+Before asking the tester to touch `.skillmapignore`, give them a
+mental map of the folder so they know where the file lives and
+what's around it. Use `Bash` (`ls -la` and `ls -la notes/` if a
+deeper view helps) and present the listing inside a blockquote so
+the tester sees what their cwd holds:
+
+> Antes del último paso, esto es lo que tenés en el directorio
+> ahora mismo:
+>
+> ```
+> .                            ← your cwd
+> ├── .claude/
+> │   ├── agents/demo-agent.md
+> │   ├── commands/demo-command.md
+> │   ├── hooks/demo-hook.md
+> │   └── skills/demo-skill/SKILL.md
+> ├── .skill-map/              ← project DB + settings (managed)
+> │   ├── settings.json
+> │   ├── settings.local.json
+> │   └── skill-map.db
+> ├── .skillmapignore          ← the file we're about to edit
+> ├── notes/
+> │   ├── todo.md
+> │   └── private-credentials.md   ← what we want to hide
+> └── sm-tutorial.md           ← the tutorial file you loaded
+> ```
 >
-> Confirmá / confirm. If a connector is missing, refresh the
-> browser and tell me.
+> The `.skillmapignore` at the root is the file we'll touch
+> next. Same syntax as `.gitignore`. Anything matching a pattern
+> there is invisible to skill-map's scan.
+
+Adjust the actual tree shown to whatever `ls -la` returns — the
+goal is "tester recognises their own filesystem", not a copy of
+the snippet above.
+
+**Beat C — the tester edits `.skillmapignore` (NOT the agent).**
 
-Once they confirm, ask them to stop the server with **Ctrl+C** in
-the terminal before continuing.
+Per Inviolable rule #1, you DO NOT touch `.skillmapignore` with
+your `Edit` tool. Tell the tester to do it from their editor:
+
+> Last step. Open `.skillmapignore` (it's at the cwd root) in
+> your editor of choice. At the end of the file, on a new line,
+> append:
+>
+> ```
+> notes/private-*.md
+> ```
+>
+> Save the file. The pattern uses a glob (same as `.gitignore`):
+> `notes/private-*.md` matches `private-credentials.md` and any
+> future sibling `private-*.md`. A literal path
+> (`notes/private-credentials.md`) would also work — the glob
+> teaches the broader habit.
+>
+> Watch the browser when you save. The
+> `notes/private-credentials` node should disappear from the
+> graph in real time, without restarting anything. Six nodes
+> back to five.
+>
+> Did the node vanish?
+
+After they confirm, you MAY use `Read` on `.skillmapignore` to
+verify the appended pattern landed correctly (in case
+`sm check` later reports something odd) — that is read-only and
+allowed. Once confirmed, ask them to stop the server with
+**Ctrl+C** in the terminal before continuing.
 
 Mark `3-ui-live: done`.
 
@@ -678,7 +851,8 @@ process trying to bind the same port and confusing the tester.
 >
 > Expected: the `demo-skill → demo-agent` connector disappears. If
 > `demo-agent.md` ends up with no one linking to it, it shows up as
-> an orphan (we'll exploit this in stage L4).
+> an orphan (we'll create a similar dangling situation in stage L4
+> to see how `sm check` flags it).
 
 You verify by reading `.claude/skills/demo-skill/SKILL.md` to confirm
 the change was applied. Once they confirm, ask them to **Ctrl+C**
@@ -695,8 +869,9 @@ sm check
 ```
 
 Expected: you see the 5 fixture nodes listed with their kind;
-`check` reports the broken-link issue in `notes/todo.md` pointing
-at `missing-page.md`.
+`check` runs the deterministic rules and reports a clean fixture
+(no issues at this point — we will plant one in stage L4 and watch
+the rule catch it).
 
 ### Stage L3 — ASCII: graph + export (~3 min)
 
@@ -713,10 +888,18 @@ or json.
 
 ### Stage L4 — Issues: broken refs (~3 min)
 
-The fixture has a deliberate broken link in `notes/todo.md`
-pointing at `notes/missing-page.md`. skill-map flags it as a
-**`broken-ref` issue** (not a graph connector, not an "orphan" —
-those are different concepts).
+`broken-ref` is one of the deterministic rules `sm check` runs.
+We'll plant one and watch it surface — that's the easiest way to
+internalise that it is an **issue** on a node, NOT a graph
+connector and NOT the same thing as an "orphan".
+
+Ask the tester to **append one bullet** to `notes/todo.md`:
+
+```markdown
+- [ ] Document the [flow diagram](./missing-page.md).
+```
+
+`./missing-page.md` deliberately doesn't exist. Save the file.
 
 ```bash
 sm check
@@ -727,7 +910,9 @@ sm check --json
 Expected: the warning surfaces the dangling link from
 `notes/todo.md` to the non-existent `missing-page.md`. The
 `--rules` filter lets you focus on a single issue type; `--json`
-emits the structured payload (useful for CI / scripting).
+emits the structured payload (useful for CI / scripting). When
+done, the tester can leave the bullet in place or delete it — the
+rest of the deep-dive doesn't depend on it.
 
 > **Heads up about scope** (mention only if the tester asks):
 >
@@ -845,7 +1030,7 @@ the cwd, start like this (do NOT repeat pre-flight from scratch):
 
 If they pick "start over", confirm explicitly. Only after
 confirmation, delete the tutorial files in the cwd
-(`tutorial-state.yml`, `findings.md`, `.skill-mapignore`, `.claude/`,
+(`tutorial-state.yml`, `findings.md`, `.skillmapignore`, `.claude/`,
 `notes/`, `.skill-map/`, and any `export.*`, `dump.sql`, or
 `sm-tutorial-report.md` that may have been left behind) and start
 everything from pre-flight.