@skill-map/cli 0.16.1 → 0.16.2

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

@@ -35,10 +35,58 @@ optional second phase (~30-40 min) covering the rest of the CLI.
 
 ## Tone
 
-- Español casual, neutro con un toque argentino. Frases cortas. Cero
-  jerga innecesaria.
-- Llamás al tester por su nombre si te lo dice; si no, "vos".
-- No sos condescendiente. Si pide algo que va a romper, lo avisás claro.
+- Spanish (when the tester's language is Spanish): casual, neutral,
+  NOT rioplatense. Short sentences. No unnecessary jargon. Use
+  `tú` form, not `vos` — `puedes`, `mira`, `prueba`, `crea`, NOT
+  `podés`, `mirá`, `probá`, `creá`. Avoid Argentine fillers
+  (`dale`, `bueno`, `che`, `re-`, `genial`).
+- Address the tester by name if they introduced themselves; if not,
+  the implicit second person from the verb is enough. No need to
+  invent a stand-in pronoun.
+- Don't be condescending. If they ask for something that will
+  break, say so directly.
+- **Translate product vocabulary into Spanish, do NOT leave English
+  loanwords embedded in Spanish prose.** When rendering tester-facing
+  copy in Spanish, use these equivalences:
+  - `kind` → `tipo` (skill-map talks about node "kinds"; in
+    Spanish output the word is `tipo` / `tipos`, NOT "kinds").
+  - `connector` → `conector`.
+  - `watcher` → `observador` (or rephrase: "skill-map sigue tus
+    cambios" instead of "el watcher detecta...").
+  - `scan` (verb) → `escanear`; `scan` (noun) → `escaneo`.
+  - `node` → `nodo`; `link` → `enlace` or `vínculo`; `frontmatter`
+    keep as-is (it's a technical term with no clean Spanish
+    equivalent — explain in parens per the rule above).
+  - File paths, frontmatter keys (`name`, `description`, `event`,
+    etc.), CLI verbs (`sm init`, `sm watch`), and code identifiers
+    stay English — that's the public surface, not jargon.
+  Anti-pattern (do NOT emit): "aparecen los otros cuatro kinds",
+  "el watcher detectó el cambio", "vamos a hacer un scan ahora".
+  Correct: "aparecen los otros cuatro tipos", "skill-map detectó
+  el cambio", "vamos a escanear ahora".
+- **Stay silent during backstage work.** Do NOT narrate operational
+  steps you're about to take or internal checks. Forbidden patterns
+  include "Voy a verificar primero que el directorio esté listo",
+  "Let me run `sm version` to confirm the binary works", "Mientras
+  esperás, te cuento el estado", "Vamos a ir paso a paso", "OK, ya
+  preparé los archivos, ahora seguimos con...", and any other
+  meta-narration of your own plumbing. Pre-flight checks, file
+  reads, `Bash ls`, `Write` of fixtures, state-file updates — all
+  silent. The tester only hears from you when (a) you need them to
+  do something, (b) a reveal landed and you want a confirm, or
+  (c) something failed and they need to know. Between those
+  moments, work without commentary.
+- **Explain technical terms in parentheses the first time you
+  mention them in a tester-facing blockquote.** Assume the tester
+  is non-technical; many will not know what `frontmatter`,
+  `findings`, `glob`, `watcher`, `connector`, `extractor`, or
+  `kind` mean. Examples:
+  - `frontmatter (the YAML block at the top of every .md, between the two --- lines)`
+  - `findings (any bugs or rough edges you spot — I'll log them for the team)`
+  - `glob (a pattern with wildcards, same shape as .gitignore)`
+  Internal narration in this SKILL.md does not need the gloss;
+  this rule is purely about what the agent says to the tester.
+  After the first mention in a session, the bare term is fine.
 - **Messages addressed to the tester are rendered as Markdown
   blockquotes** (lines prefixed with `> `): instructions, narrative
   context, numbered choice menus, prompts, confirmations. The
@@ -49,10 +97,10 @@ optional second phase (~30-40 min) covering the rest of the CLI.
   narrative and a command, write the narrative in a blockquote
   *above* the bare code block (not inside it).
 - **Mirror the tester's language**: if the first message they wrote
-  was in Spanish, run the conversation in Argentine Spanish (per
-  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.
+  was in Spanish, run the conversation in neutral Spanish (per
+  the Tone bullets above — `tú` form, no rioplatense); 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
@@ -81,15 +129,26 @@ optional second phase (~30-40 min) covering the rest of the CLI.
      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.
+   - **Configuration files have two-mode access**: backstage setup
+     vs teach moment.
+     - **Backstage setup (you DO edit)**: right after `sm init` in
+       Step 1, you append the tutorial's internal entries
+       (`sm-tutorial.md`, `findings.md`, `tutorial-state.yml`,
+       `sm-tutorial-report.md`, etc.) to the freshly created
+       `.skillmapignore` with `Edit`. That is plumbing — the
+       tester does not need to learn that the tutorial hides its
+       own scaffolding from the scan. Do it silently and move on.
+     - **Teach moment (you DO NOT edit)**: any time the SKILL
+       calls for a change to `.skillmapignore`,
+       `.skill-map/settings.json`,
+       `.skill-map/settings.local.json`, or `.gitignore` AS PART
+       OF A REVEAL OR LESSON (e.g. Reveal 5 in Step 2 hides a
+       private node by appending a pattern), 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 in a
+       teach moment 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
@@ -210,6 +269,12 @@ which sm
 sm version
 ```
 
+This check is **silent on success**. Do NOT narrate the result to
+the tester ("`sm` v X.Y.Z responded, all good"). Save the version
+internally and move on. The tester does not need a status report
+for a backstage health check; speaking up here adds noise without
+information. Only break the silence if something actually fails.
+
 If `sm` isn't installed, tell the tester:
 
 > You don't have `sm` yet. You'll need Node 20+ and then:
@@ -225,8 +290,8 @@ permissions issue. Suggest `node --version` and walk them through it.
 
 ### 3. Create the initial fixture (one node only)
 
-The tutorial builds the graph **progressively** in three reveals during
-Step 3 (Live UI). Right now, in pre-flight, you only create **one
+The tutorial builds the graph **progressively** in five reveals during
+Step 2 (Live UI). Right now, in pre-flight, you only create **one
 file** — a single agent — so the tester's first look at the UI
 shows exactly one node. The other four kinds (skill, command, hook,
 note) and the connectors between all five are added later, one
@@ -300,16 +365,13 @@ route:
     status: "not_started"   # not_started | in_progress | done | declined
     estimated_min: 35
 short_steps:
-  - id: "1-version"
-    title: "sm version"
-    status: "pending"
-  - id: "2-init"
+  - id: "1-init"
     title: "sm init"
     status: "pending"
-  - id: "3-ui-live"
+  - id: "2-ui-live"
     title: "⭐ Live UI: bare sm + live edits by the agent"
     status: "pending"
-  - id: "4-handoff"
+  - id: "3-handoff"
     title: "Wrap-up of the demo and offer to keep going"
     status: "pending"
 long_stages:
@@ -363,16 +425,7 @@ to resume (re-invoke the skill from the same dir).
 
 Always runs. The pedagogical hook is the live UI.
 
-### Step 1 — `sm version` (30 s)
-
-Already done in pre-flight. Confirm to the tester in one short
-blockquote, translated to their language:
-
-> OK, `sm` v X.Y.Z responded. Let's go.
-
-Mark `1-version: done`.
-
-### Step 2 — `sm init` (1 min)
+### Step 1 — `sm init` (1 min)
 
 **Context**: `sm init` creates a hidden `.skill-map/` folder in the
 cwd holding the database where skill-map stores what it learns about
@@ -403,9 +456,9 @@ export.*
 dump.sql
 ```
 
-Mark `2-init: done`.
+Mark `1-init: done`.
 
-### Step 3 — ⭐ Live UI (4-5 min)
+### Step 2 — ⭐ Live UI (4-5 min)
 
 **Context**: typing `sm` alone (no arguments) in an initialised dir
 starts the UI server with the watcher built in. One process, one
@@ -444,8 +497,9 @@ 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.
+> 1. **The browser** — where the graph will update in real time.
+>    Leave it ready to navigate to a URL; we'll get the link in a
+>    moment.
 > 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.
@@ -458,22 +512,31 @@ Tell the tester:
 > 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.
+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):
+
+> In the terminal you opened for `sm`, run the command above. 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.
 
 #### Reveal 1 — the lone agent
 
 Tell the tester:
 
-> The server is running. Open the URL it printed (typically
-> **http://127.0.0.1:4242**).
->
 > You'll see exactly **one node** in the graph: `demo-agent` (kind
 > `agent`). That's our starting point.
 >
 > Walk the 3 views before we go on:
 > 1. **Graph** — the single agent node.
 > 2. **List** — one row, with path / kind / metadata.
-> 3. **Inspector** — click the node to see frontmatter and links.
+> 3. **Inspector** — click the node to see its frontmatter (the
+>    YAML block at the top of every `.md`, between the two `---`
+>    lines) and links.
 >
 > Did the node show up?
 
@@ -602,10 +665,18 @@ 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.
+> 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.
+>
+> Now open `.claude/agents/demo-agent.md` in your editor of
+> choice. In the **frontmatter** (the YAML block at the top of
+> the file, between the two `---` lines), 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
@@ -731,9 +802,6 @@ the tester sees what their cwd holds:
 > │   ├── 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
@@ -781,9 +849,9 @@ verify the appended pattern landed correctly (in case
 allowed. Once confirmed, ask them to stop the server with
 **Ctrl+C** in the terminal before continuing.
 
-Mark `3-ui-live: done`.
+Mark `2-ui-live: done`.
 
-### Step 4 — Wrap-up of the demo and offer to keep going (30 s)
+### Step 3 — Wrap-up of the demo and offer to keep going (30 s)
 
 > All set! That's the heart of skill-map: you edit a `.md` and the
 > UI sees it instantly. In **~7 minutes** you've already seen the
@@ -838,9 +906,9 @@ Save into `tester.level` and modulate:
 they can do it from their editor.
 
 This stage needs the server running. **Check first** before asking
-them to launch it: many testers leave it running from Step 3 and
+them to launch it: many testers leave it running from Step 2 and
 the demo wraps without an explicit Ctrl+C. Word the prompt as a
-conditional, e.g. "If the server from Step 3 is still up, leave it
+conditional, e.g. "If the server from Step 2 is still up, leave it
 — if not, run `sm` again from the tutorial cwd and reopen the
 browser." Do not just say "start it again" — that risks a second
 process trying to bind the same port and confusing the tester.
@@ -963,8 +1031,9 @@ generate a report file to send to Pusher**:
 
 > Thanks! That's a wrap. Before closing:
 >
-> Want me to generate a consolidated **report file** (recap of the
-> walkthrough + findings + environment) ready to send to **Pusher**?
+> Want me to generate a consolidated **report file** (a recap of
+> the walkthrough + findings — the bugs or rough edges you spotted
+> along the way — + environment info) ready to send to **Pusher**?
 > I'll save it as `<cwd>/sm-tutorial-report.md`.
 >
 > 1. **Yes, generate it**

package/dist/cli.js

@@ -617,6 +617,18 @@ function readIgnoreFileText(scopeRoot) {
     return void 0;
   }
 }
+async function readIgnoreFileTextStable(scopeRoot, opts = {}) {
+  const pollMs = opts.pollMs ?? 50;
+  const maxAttempts = opts.maxAttempts ?? 10;
+  let prev = readIgnoreFileText(scopeRoot);
+  for (let i = 0; i < maxAttempts; i++) {
+    await new Promise((r) => setTimeout(r, pollMs));
+    const curr = readIgnoreFileText(scopeRoot);
+    if (curr === prev) return curr;
+    prev = curr;
+  }
+  return prev;
+}
 var cachedDefaults = null;
 function loadDefaultsText() {
   if (cachedDefaults !== null) return cachedDefaults;
@@ -7362,7 +7374,7 @@ import { Command as Command8, Option as Option8 } from "clipanion";
 // package.json
 var package_default = {
   name: "@skill-map/cli",
-  version: "0.16.1",
+  version: "0.16.2",
   description: "skill-map reference implementation \u2014 kernel + CLI + adapters.",
   license: "MIT",
   type: "module",
@@ -11591,11 +11603,10 @@ async function runWatchLoop(opts) {
   const runtimeCtx = defaultRuntimeContext();
   const { cwd } = runtimeCtx;
   const loadEffectiveConfig = () => loadConfig({ scope: "project", strict: opts.strict, ...runtimeCtx }).effective;
-  const buildCurrentIgnoreFilter = (cfgIn) => {
-    const text = readIgnoreFileText(cwd);
+  const composeIgnoreFilter = (cfgIn, ignoreFileText) => {
     const filterOpts = {};
     if (cfgIn.ignore.length > 0) filterOpts.configIgnore = cfgIn.ignore;
-    if (text !== void 0) filterOpts.ignoreFileText = text;
+    if (ignoreFileText !== void 0) filterOpts.ignoreFileText = ignoreFileText;
     return buildIgnoreFilter(filterOpts);
   };
   let cfg;
@@ -11606,7 +11617,7 @@ async function runWatchLoop(opts) {
     context.stderr.write(tx(WATCH_TEXTS.configLoadFailure, { message }));
     return ExitCode.Error;
   }
-  let ignoreFilter = buildCurrentIgnoreFilter(cfg);
+  let ignoreFilter = composeIgnoreFilter(cfg, readIgnoreFileText(cwd));
   let strict = opts.strict || cfg.scan.strict === true;
   const debounceMs = cfg.scan.watch.debounceMs;
   const dbPath = defaultProjectDbPath(runtimeCtx);
@@ -11743,7 +11754,8 @@ async function runWatchLoop(opts) {
       if (stopRequested) return;
       try {
         cfg = loadEffectiveConfig();
-        ignoreFilter = buildCurrentIgnoreFilter(cfg);
+        const stableText = await readIgnoreFileTextStable(cwd);
+        ignoreFilter = composeIgnoreFilter(cfg, stableText);
         strict = opts.strict || cfg.scan.strict === true;
         await handleBatch();
       } catch (err) {
@@ -13237,15 +13249,14 @@ function createWatcherService(opts) {
       cwd,
       homedir: opts.runtimeContext.homedir
     }).effective;
-    const buildCurrentIgnoreFilter = (cfgIn) => {
-      const ignoreFileText = readIgnoreFileText(cwd);
+    const composeIgnoreFilter = (cfgIn, ignoreFileText) => {
       const filterOpts = {};
       if (cfgIn.ignore.length > 0) filterOpts.configIgnore = cfgIn.ignore;
       if (ignoreFileText !== void 0) filterOpts.ignoreFileText = ignoreFileText;
       return buildIgnoreFilter(filterOpts);
     };
     let cfg = loadEffectiveConfig();
-    let ignoreFilter = buildCurrentIgnoreFilter(cfg);
+    let ignoreFilter = composeIgnoreFilter(cfg, readIgnoreFileText(cwd));
     const debounceMs = opts.debounceMsOverride ?? cfg.scan.watch.debounceMs;
     const pluginRuntime = opts.options.noPlugins ? emptyPluginRuntime() : await loadPluginRuntime({ scope: opts.options.scope });
     for (const warn of pluginRuntime.warnings) {
@@ -13321,7 +13332,8 @@ function createWatcherService(opts) {
         if (stopped) return;
         try {
           cfg = loadEffectiveConfig();
-          ignoreFilter = buildCurrentIgnoreFilter(cfg);
+          const stableText = await readIgnoreFileTextStable(cwd);
+          ignoreFilter = composeIgnoreFilter(cfg, stableText);
           await runOneBatch();
         } catch (err) {
           const message = formatErrorMessage(err);