@skill-map/cli 0.52.0 → 0.53.0

package/dist/cli/tutorial/sm-tutorial/references/part-connect-harness.md

@@ -0,0 +1,180 @@
+# Part 2: Connect the harness (step library, `connect-harness`)
+
+This is the wiring part. Part 1 grew a small set of standalone nodes around the handbook (the portfolio harness); here the tester turns that scatter of dots into a connected graph: a link checker, a publish command that pulls three pieces together, the handbook becoming a real hub, and a close-up on how sure skill-map is of each connection. `pace: auto-advance` (walk straight into the next chapter once one is marked done), `preflight: reuse` (it builds on the portfolio harness from Part 1, no fresh fixture of its own). Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
+
+## Chapter `check-links` - The link checker (~3 min)
+
+**Context**: the harness needs a guard that runs before publishing: a skill that walks every page and checks the internal links resolve. We only create it here (its first standalone `skill` node); the `publish` command in the next chapter is what invokes it.
+
+`Write` `.claude/skills/check-links/SKILL.md` (substitute `<provider_dir>` per `_core.md`; this kind exists on every provider, so no skip):
+
+```markdown
+---
+name: check-links
+description: |
+  Validates the portfolio's internal links before publishing. Walks
+  every generated page and reports any link whose target is missing.
+inputs:
+  - name: root
+    type: path
+    description: Folder of generated pages to check.
+    required: true
+outputs:
+  - name: report
+    type: string
+    description: List of broken links, empty when all resolve.
+---
+
+# check-links
+
+Runs as the last gate before the site goes out. Reads each page under
+the given root, follows every internal link, and reports the ones that
+point at a file that does not exist.
+
+## Steps
+1. Read every page under `root`.
+2. Collect the internal links from each page.
+3. Report any link whose target is missing.
+```
+
+Tell the tester:
+
+> I added a new helper to your harness: a skill called `check-links`
+> (its job is to make sure every internal link on the site actually
+> works before you publish). A new `skill` node appeared on the
+> **Map**. It stands alone for now, in the next step we give it a
+> caller.
+>
+> See the new skill node?
+
+Wait for confirmation. Mark `check-links`: done.
+
+## Chapter `publish` - The publish command (~4 min)
+
+**Context**: this is the chapter where the graph comes alive. The `/publish` command ties three pieces together in one body: it invokes the link checker, mentions the content editor, and references the deploy runbook. Three connectors light up from a single new node, one per link syntax.
+
+`Write` `.claude/commands/publish.md` (substitute `<provider_dir>` per `_core.md`; on `agent-skills` / Antigravity there is no `command` kind, so skip this whole chapter and fold its purpose into the prose of the next one):
+
+```markdown
+---
+name: publish
+description: |
+  Publishes the portfolio: runs the link check, hands off to the
+  content editor for any last fixes, then follows the deploy runbook.
+shortcut: "ctrl+alt+p"
+args:
+  - name: root
+    type: path
+    description: Folder of generated pages to publish.
+    required: true
+---
+
+# /publish
+
+The one command you run when the site is ready to go out.
+
+## Steps
+1. Run /check-links on the generated pages first.
+2. If anything needs a fix, brief @content-editor on it.
+3. Follow the [deploy runbook](../../docs/DEPLOY.md) to ship.
+```
+
+Tell the tester:
+
+> I added the `/publish` command, the single entry point you run when
+> the site is ready to go live. Watch the **Map**: **three** new
+> arrows light up at once from the new `publish` node, and each one is
+> a different colour because each one is a different kind of link:
+>
+> - `publish -> check-links` (kind: `invokes`), from the `/check-links`
+>   token in the body.
+> - `publish -> content-editor` (kind: `mentions`), from the
+>   `@content-editor` token.
+> - `publish -> docs/DEPLOY.md` (kind: `references`), from the
+>   `[deploy runbook](../../docs/DEPLOY.md)` markdown link.
+>
+> One node, three connectors, three link kinds. The harness is
+> starting to look like a real graph.
+>
+> Did the three arrows appear?
+
+Wait for confirmation. Mark `publish`: done.
+
+## Chapter `links` - The handbook becomes the hub (~4 min)
+
+**Context**: the handbook (`AGENTS.md`) has been a lonely node since Part 1. Here it becomes the hub: we add two bullets so it mentions the content editor and invokes the publish command. We also give the content editor a reference to the style guide it follows. Several connectors land, and we recap the three link kinds and which syntax produced each.
+
+Apply both edits with `Edit` (do not rewrite the files).
+
+**Edit `AGENTS.md`**: append these two bullets at the end of the body (substitute `<provider_dir>` only in prose, the link tokens below stay as written):
+
+```markdown
+- When a page needs writing or fixing, brief @content-editor.
+- When the site is ready to go out, run /publish.
+```
+
+**Edit `.claude/agents/content-editor.md`**: add this line to the body, right after the "Turns a short brief..." paragraph (substitute `<provider_dir>` per `_core.md`):
+
+```markdown
+Every page follows the [style guide](../../docs/STYLE.md).
+```
+
+Tell the tester:
+
+> Two edits, and the **Map** fills in. Your handbook (`AGENTS.md`) is
+> now the hub: it points at the content editor and at the publish
+> command. And the content editor now reaches the style guide it
+> follows. New arrows:
+>
+> - `AGENTS.md -> content-editor` (kind: `mentions`), from `@content-editor`.
+> - `AGENTS.md -> /publish` (kind: `invokes`), from `/publish`.
+> - `content-editor -> docs/STYLE.md` (kind: `references`), from the
+>   `[style guide](../../docs/STYLE.md)` markdown link.
+>
+> Here is the whole recap of the three link kinds, one per syntax:
+>
+> - an `@handle` token is always a **mention**.
+> - a `/slash` token is always an **invoke**.
+> - a `[text](path.md)` markdown link is always a **reference**.
+>
+> The kind comes purely from how you wrote it. Your harness is wired
+> end to end now: the handbook reaches the work, the work reaches the
+> docs, and `/publish` pulls the whole publish flow together.
+>
+> Did the new arrows light up?
+
+Wait for confirmation. You MAY use `Read` on the two files afterwards to verify the edits landed before moving on. Mark `links`: done.
+
+## Chapter `confidence` - How sure is each link (~3 min)
+
+**Context**: the connectors do not all look equally solid, and that is on purpose. Skill-map estimates how sure it is of every connection and shows that as opacity. Here we open the Inspector on a real harness node and read the per-link confidence numbers, mirroring the prologue's connectors beat but on the portfolio.
+
+No file edits in this chapter, pure observation on the graph the tester just built.
+
+Tell the tester:
+
+> Last beat of this part: how sure is skill-map about each connection?
+> Look closely at the **Map** and you'll notice the arrows are not all
+> equally solid. The more confident skill-map is that a link is real,
+> the more solid the arrow; the less sure, the more translucent.
+>
+> Open the Inspector for the `publish` node (click it on the **Map**).
+> Scroll down to the **Linked nodes** panel and read the **Outgoing**
+> rows. Each row shows the link kind and a confidence badge:
+>
+> - `publish -> docs/DEPLOY.md` (`references`) reads **1.00** and looks
+>   solid: it is a markdown link to a file that really exists on disk,
+>   so skill-map is certain.
+> - `publish -> content-editor` (`mentions`) and `publish ->
+>   check-links` (`invokes`) read high too, because each `@handle` and
+>   `/slash` token resolves cleanly to a node that exists in your
+>   harness.
+>
+> The number is the certainty, and the opacity on the canvas is just
+> that number drawn as transparency: a glance at the **Map** tells you
+> which connections are rock solid and which are skill-map's best
+> guess.
+>
+> Do you see the confidence badges in the Inspector?
+
+Wait for confirmation. Mark `confidence`: done. This closes Part 2; the orchestrator returns to the ToC menu (Part 3, "Maintain the site", is next on the spine).

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

@@ -0,0 +1,424 @@
+# Part 0: The live map (prologue) - step library
+
+The live-UI prologue: the tester runs `sm init`, opens the browser, and watches the map update in real time as files are written and edited. `pace: per-step` (ask "¿seguimos?" between steps), `preflight: taught-init` (the tester runs `sm init` as the first taught step, not pre-flight), and the chapters lay the basics fixture progressively, one node at a time. Shared conventions (tone, provider detection / substitution, the `> ` rendering rule, the per-step cycle) live in `_core.md`; do not restate them here.
+
+## Chapter `init` - Your first node (~2 min)
+
+**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 runs an initial scan. Mandatory first step. Then typing `sm` alone (no arguments) in an initialised dir starts the UI server with the watcher built in (it is just an alias of `sm serve` with all defaults; the moment you need any flag you write `sm serve --flag ...` explicitly). One process, one terminal: it boots the server, scans the `.md` files, detects changes, and pushes events over WebSocket to the live UI. The next chapters all run against the same `sm` session, you boot it here and keep it alive through the `ignore` chapter.
+
+```bash
+sm init
+ls -la .skill-map/
+```
+
+Expected: `.skill-map/skill-map.db` appears (plus config files). The initial scan reports a small node / link / issue count from the demo-agent fixture, NOT 14+ phantom issues from the tutorial's own prose: pre-flight already wrote `.skillmapignore` with the right exclusions in place, so `sm init` leaves that file alone (it only writes when absent) and the scan never sees `sm-tutorial.md` / `findings.md` / `tutorial-state.yml`.
+
+Before launching the server, ask the tester to set up a **side-by-side view** so they can watch the magic happen without alt-tabbing every step. Tell the tester:
+
+> Now arrange your screen so the **browser** (where the **Map**
+> updates in real time) and **this chat** are both visible at once
+>, typical layout is browser on the left half, chat on the right
+> (or any split that lets you see both). The terminal running
+> `sm` can stay off to the side; it just prints scan progress
+> lines and you don't need to read them.
+>
+> Tell me when you're set up and we start.
+
+Wait for confirmation before moving on. Once they're ready, prompt them to launch the server and open the link it prints, without hardcoding the URL here, since the verb itself is the source of truth (it logs the bound `http://host:port` after listen):
+
+> Run `sm`. After a couple of seconds it will print a line with the
+> URL where the UI is listening, copy that link and open it in the
+> browser you just arranged. Tell me when you see the page load.
+
+Wait for confirmation that the page loaded. Then tell the tester:
+
+> You'll see exactly **one node** in the **Map**: `demo-agent`
+> (kind `agent`). That's our starting point.
+>
+> The workspace opens **map-first**: the canvas fills the screen and
+> the **Files** panel sits collapsed against the left edge. Click the
+> expand handle on the far left (the `>` arrow, its tooltip reads
+> "Expand files panel") to open it.
+>
+> Now walk the two views before we go on:
+> 1. **Map**: the single agent node on the canvas.
+> 2. **Files**: one row, with path / kind / metadata.
+>
+> Then, back in **Map**, click the node: the **Inspector** panel
+> slides out with its frontmatter (the YAML block at the top of
+> every `.md`, between the two `---` lines) and its links.
+>
+> Did the node show up?
+
+Wait for confirmation. Mark `init`: done.
+
+## Chapter `kinds` - The other kinds appear (~1 min)
+
+Leave the browser open and the terminal with `sm` running. You create four more nodes **without any cross-fixture links** yet, pure standalone nodes, so the tester sees four new dots pop in. Three new **kinds** show up in this step (skill, command, markdown), the fourth file is a second `markdown` node that the hub in the `connectors` chapter will point at via a real `references` link.
+
+Create these four files (with `Write`), exactly in this order. Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and skip files whose kind is not in the provider's supported set** (`agent-skills` / Antigravity: skip both `demo-agent` and `demo-command`, only the skill + the two markdown notes remain). Adjust the node count, the "four new nodes" message, and the file list shown to the tester in the sample below accordingly:
+
+1. `.claude/skills/demo-skill/SKILL.md` (kind: skill):
+   ```markdown
+   ---
+   name: demo-skill
+   description: |
+     Example skill that walks a file and returns a Markdown report.
+     Showcases the `skill` kind in the demo map.
+   inputs:
+     - name: target
+       type: path
+       description: File to process.
+       required: true
+   outputs:
+     - name: report
+       type: string
+       description: Markdown summary.
+   ---
+
+   # demo-skill
+
+   This skill walks a file and returns a report. Will be wired up
+   to the rest of the demo fixture in the next sub-step.
+
+   ## Steps
+   1. Read the `target`.
+   2. Validate the frontmatter against the schemas.
+   3. Generate the report.
+   ```
+
+2. `.claude/commands/demo-command.md` (kind: command):
+   ```markdown
+   ---
+   name: demo-command
+   description: |
+     Example slash-style command that wraps the demo-skill behind
+     a keyboard shortcut. Showcases the `command` kind.
+   shortcut: "ctrl+alt+d"
+   args:
+     - name: target
+       type: path
+       description: File the command will hand off to the skill.
+       required: true
+   ---
+
+   # demo-command
+
+   Quick keyboard entry point for running the demo flow on a
+   target file. Connectors land in the next sub-step.
+   ```
+
+3. `notes/todo.md`, classified as `kind: markdown` today
+   (the catch-all for `.md` files outside the
+   skill / agent / command folders):
+   ```markdown
+   ---
+   name: Demo TODO list
+   description: |
+     Live list of things to review in the demo. Will become the
+     hub that points to the rest of the fixture in the next
+     sub-step.
+   tags: [notes, demo]
+   ---
+
+   # Pending
+   ```
+
+4. `notes/demo-guideline.md`, second `kind: markdown` node, the
+   one the hub will reach via a real markdown link in the
+   `connectors` chapter:
+   ```markdown
+   ---
+   name: demo-guideline
+   description: |
+     Static reference notes that the rest of the demo points at.
+     Showcases a second markdown node so the demo can exercise
+     the `references` link kind without ambiguity.
+   tags: [notes, demo]
+   ---
+
+   # Demo Guideline
+
+   Conventions the demo fixture follows:
+
+   - Names match the file basename.
+   - Frontmatter `description` is short and human-readable.
+   - Body stays minimal, only what's needed to teach the kind.
+   ```
+
+Tell the tester:
+
+> Look at the browser. Four new nodes should have popped in:
+> `demo-skill`, `demo-command`, `notes/todo`, and `demo-guideline`.
+> Five total now, **still unconnected**: they're floating dots.
+> The viewport auto-fits whenever a node is added or removed, so
+> all five should be visible without panning.
+>
+> What I just did behind the scenes: I created four new files in
+> your project, and the watcher picked them up on its own, that's
+> why four new dots appeared without you running anything:
+>
+> - `.claude/skills/demo-skill/SKILL.md` (kind: skill)
+> - `.claude/commands/demo-command.md` (kind: command)
+> - `notes/todo.md` (kind: markdown)
+> - `notes/demo-guideline.md` (kind: markdown)
+>
+> Same loop you'll use yourself in the next step, only this time
+> the writes came from me.
+>
+> Did the four appear? Confirm so we can wire them up.
+
+Wait for confirmation. Mark `kinds`: done.
+
+## Chapter `first-edit` - Your first edit (the watcher reacts) (~1 min)
+
+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 → map updates", which the `ignore` chapter reuses verbatim.
+
+Tell the tester:
+
+> Your turn. First, in the browser, **expand the `demo-agent`
+> card** (click the chevron / arrow on the card to open it). That
+> reveals the description currently showing for the node, that's
+> the field you'll edit next, so leave the card open and the
+> change will be obvious.
+>
+> ⚠ Heads-up: the inspector header shows a couple of action
+> buttons (**Bump version**, **Refresh body**). **Don't click
+> them yet**, they write files to your project and we cover that
+> flow deliberately in the annotations chapter. For now, just look.
+>
+> Now open `.claude/agents/demo-agent.md` in your editor of
+> choice. In the **frontmatter** at the top of the file, 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. Mark `first-edit`: done.
+
+## Chapter `connectors` - The connectors light up (~2 min)
+
+You edit `notes/todo.md` so it becomes the **hub** that points to each of the other four nodes. Each bullet uses a syntax that maps to a specific **link kind**:
+
+- an `@handle` token → kind `mentions`
+- a `/slash` token → kind `invokes`
+- a markdown link `[text](path)` → kind `references`
+
+Four bullets, three kinds (the `invokes` kind shows up twice because both the command and the skill are addressed by slash).
+
+Apply with `Edit` on `notes/todo.md` (do not rewrite the file). Per §Provider detection, **substitute `.claude/` with the detected `<provider_dir>` and drop any bullet whose target node was not created in the `kinds` chapter** (on `agent-skills` / Antigravity there is no agent and no command → skip the `@demo-agent` and `/demo-command` bullets, two connectors land).
+
+**Edit `notes/todo.md`**: append these bullets after the `# Pending` heading:
+
+```markdown
+- [ ] Brief @demo-agent on the rough edges.
+- [ ] Run /demo-command before publishing.
+- [ ] Trigger /demo-skill when the input lands.
+- [ ] Re-read the
+      [demo-guideline](./demo-guideline.md) before shipping.
+```
+
+Tell the tester:
+
+> Look at the magic again. `notes/todo` is now the hub: four
+> arrows light up between it and the other nodes, and the UI
+> palette colours each arrow by the link kind it carries:
+>
+> - `notes/todo → demo-agent` (kind: `mentions`)
+> - `notes/todo → demo-command` (kind: `invokes`)
+> - `notes/todo → demo-skill` (kind: `invokes`)
+> - `notes/todo → demo-guideline` (kind: `references`)
+>
+> The kind comes from the syntax in the bullet: an `@handle` is
+> always a mention, a `/command` is always an invoke, a markdown
+> link is always a reference. Four arrows, three kinds, three
+> colours on the canvas (the two `invokes` share a colour, as you
+> would expect).
+>
+> Notice too that the connectors have different transparency.
+> Skill-map estimates how sure it is of each connection: a
+> `[text](file.md)` that points at a real file (confidence 1.00,
+> now that the target exists) looks solid, while an `@handle` that
+> resolves to no node sits at 0.5 (ambiguous) and looks
+> translucent. The opacity tells that story at a glance: the more
+> solid the arrow, the more reliable the inference.
+>
+> Confirm when you see it. If a connector is missing, refresh the
+> browser and let me know.
+
+If a connector is missing, do not advance, the next chapter inspects the same hub edit. Mark `connectors`: done.
+
+## Chapter `inspector` - The inspector and linked nodes (~1 min)
+
+The connector opacity tells the confidence story at a glance; the exact per-link breakdown lives in the Inspector. Open it on the hub so the tester registers the surface before the `edit-link` chapter changes topology.
+
+> 🆕 Open the Inspector for `notes/todo` (click the node on the
+> map). Scroll down to the **Linked nodes** panel: it has two
+> sections, **Outgoing** and **Incoming**. `notes/todo` lists 4
+> links under Outgoing (it's the hub pointing at four nodes) and 0
+> under Incoming; if you open the Inspector for any of the four
+> targeted nodes, you'll see 1 under Incoming. Each row shows the
+> link kind (`mentions`, `invokes`, `references`) and a badge with
+> its confidence: the numeric value (`1.00`, `0.50`, …).
+>
+> Let me know when you see it.
+
+After the tester confirms, drop this tip:
+
+> 💡 Tip: if all these changes left the nodes crowded together,
+> the map toolbar has a **Reset layout** button: it re-runs the
+> auto-layout so everything reads better. It asks for confirmation
+> because it discards any positions you moved by hand.
+
+Wait for confirmation. Mark `inspector`: done.
+
+## Chapter `edit-link` - Edit a link, the topology changes (~3 min)
+
+**Context**: the `first-edit` chapter had the tester edit a scalar (`description`) and watch the inspector card refresh. This chapter raises the bar: edit a Markdown link and watch the MAP TOPOLOGY change (a connector disappears). Same watcher, different surface.
+
+The server has been live since the `init` chapter, leave it running; this chapter and the next two (the workspace tour, then `.skillmapignore`) reuse it.
+
+> Your turn. Edit `notes/todo.md` with your editor of choice and
+> delete the bullet that contains `@demo-agent`. Save. Watch the
+> UI.
+>
+> Expected: the `notes/todo → demo-agent` connector (kind:
+> `mentions`) disappears in real time. The two nodes stay in the
+> **Map**; only the edge goes.
+
+You verify by reading `notes/todo.md` to confirm the change was applied. (On `agent-skills`, where the `@demo-agent` bullet was never created in the `connectors` chapter, ask the tester to remove the only bullet they did add and watch THAT connector vanish, the lesson is the same.) Once they confirm, leave the server running, the next chapter reuses it. Mark `edit-link`: done.
+
+## Chapter `workspace` - Navigate the workspace (files, search, isolate) (~2 min)
+
+**Context**: you've built the graph and understood it; this beat is about *moving around* it. The workspace has two halves: the **Map** you've been working in, and a **Files** panel, a folder tree of every node. You'll open that tree, filter it with the search box, and use **isolate** to collapse the map down to a single node and the things it touches. No file edits here, pure navigation, and the same `sm` session you booted back in the `init` chapter is still running.
+
+Per §Provider detection, on `agent-skills` / Antigravity the fixture has fewer nodes (`demo-skill` plus the two `notes/` files), so swap the node names below for ones that exist in that set; the gestures are identical.
+
+**Beat 1, open the Files panel (tester does this).**
+
+> Make sure the **Files** panel is open, the one you expanded back
+> in the first chapter on the left edge. If you collapsed it since,
+> click the expand handle (the `>` arrow, tooltip "Expand files
+> panel") to reopen it. The sidebar shows a **folder tree** (a
+> nested view of your folders and the nodes inside them): your five
+> nodes grouped under `.claude/` and `notes/`, each row showing its
+> kind and how many links go in and out.
+>
+> Tell me when the tree is open.
+
+**Beat 2, search (tester does this).**
+
+> At the top of that sidebar there's a search box (placeholder
+> `Search…`). Type `guideline`. Watch both halves at once: the tree
+> narrows down to `demo-guideline` and the **Map** drops every node
+> except `demo-guideline`. The search matches a node's name, path,
+> tags or description, and filters live as you type, no Enter
+> needed.
+>
+> Now clear the box. All five nodes come back, in both the tree and
+> the Map. Confirm you saw it filter and then restore.
+
+**Beat 3, isolate (tester does this).**
+
+> Last one. In the tree, find the `notes/todo` row: at its right
+> edge there's a small **sitemap** icon (its tooltip reads "Isolate
+> this node and its direct links on the map"). Click it.
+>
+> The Map collapses to `notes/todo` plus only the nodes it links to
+> (`demo-command`, `demo-skill`, `demo-guideline`). `demo-agent`,
+> which lost its only connector back in the last step, drops out of
+> view, and the Inspector opens on `notes/todo`. That's how you
+> focus on one node's neighborhood when a map gets busy.
+>
+> To bring the rest back, look at the toolbar along the bottom of
+> the Map: there's a **Show all** button (an eye icon, tooltip
+> "Clear the map selection and show every node again"). Click it and
+> all five nodes return.
+>
+> Did the map isolate and then restore?
+
+Leave the server running, the next chapter (`.skillmapignore`) is the last one that uses it. Mark `workspace`: done.
+
+## Chapter `ignore` - Silence a file via .skillmapignore (~2 min)
+
+Earlier chapters showed the watcher picking up new files and edits (yours and theirs). This chapter flips the direction: a file the tester DOES NOT want in the map (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 1, you create one new fixture file (the agent does this).**
+
+`Write` `notes/private-credentials.md`, kind `markdown`, 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 skill-map's map. Demonstrates the .skillmapignore
+  flow.
+---
+
+# Private
+
+API_TOKEN: example-not-real
+```
+
+Confirm the file appears in the map as a sixth node (`notes/private-credentials`). The watcher sees it like any other `.md`, that's the point of the demo.
+
+**Beat 2, 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 as a tester-facing message (apply the host-dependent rendering rule) so the tester sees what their cwd holds:
+
+> One last step. Here's what your directory looks like right now:
+
+```
+.                            ← your cwd
+├── .claude/
+│   ├── agents/demo-agent.md
+│   ├── commands/demo-command.md
+│   └── skills/
+│       ├── demo-skill/SKILL.md
+│       └── sm-tutorial/SKILL.md   ← the tutorial you loaded
+├── .skill-map/              ← project DB + settings (managed)
+├── .skillmapignore          ← the file we're about to edit
+└── notes/
+    ├── todo.md
+    ├── demo-guideline.md
+    └── private-credentials.md   ← what we want to hide
+```
+
+> 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 3, the tester edits `.skillmapignore` (NOT the agent).**
+
+Per Inviolable rule #2, the agent does 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 the literal pattern `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
+> **Map** 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 `ignore`: done.