docugate 0.2.2 → 0.2.4

package/README.md

@@ -8,28 +8,114 @@ npm i -g docugate
 
 ---
 
-## Quick start
+## Quick start, step by step
 
-`cd` into your app's repository, then run:
+Follow these in order. Every question during setup is a numbered choice: type
+the number and press Enter, or just press Enter for the suggested one.
+
+**1. Install DocuGate, once per computer.**
+
+```sh
+npm i -g docugate
+```
+
+This gives you the `docugate` command in every folder. To pin a version for a
+team instead, run `npm i -D docugate` inside the project and put `npx` in front
+of each command below.
+
+**2. Open your project's folder.**
+
+```sh
+cd my-app
+```
+
+Use the root of the repository: the folder with `.git` in it. If your frontend
+and backend are two repositories, do steps 2 to 4 in each one.
+
+**3. Set everything up.**
 
 ```sh
 docugate init
 ```
 
-It walks you through four steps:
+It asks, one at a time:
 
-1. **Repository role.** Say whether this repository is the frontend, the backend, or both.
-2. **Sign in and connect.** Sign in to DocuGate with GitHub and connect this repository to a space.
-3. **IBM Bob writes the tour.** Bob reads the code and writes one `.docugate/tour/*.md` file for each screen it finds.
-4. **The pill is added to your app.** The dev-only loader snippet is inserted into your HTML or layout file.
+| Question | What to choose |
+| --- | --- |
+| What is in this repository? | **1** Frontend, **2** Backend, or **3** Both (a `frontend/` and a `backend/` folder in one repository). It suggests one from your folders. |
+| Sign in to DocuGate? | **1** opens your browser to sign in with GitHub. You come back to your editor when it is done. **2** skips it; `docugate login` does it later. |
+| Which DocuGate space should document this repository? | **1** creates a new space for it, or pick one of yours. A space already reading this repository is marked. |
+| How often should DocuGate check your docs still match the code? | On every push, daily (suggested, fewer AI runs), weekly, or never. |
+| Set up the tour: which AI should write it? | **1** IBM Bob reads your code and writes the tour. **2** IBM watsonx is coming soon. **3** skips it; you can write the tour in the browser. Frontend and both only. |
+| Add the DocuGate pill to your app? | **1** adds a few lines to your `index.html` or Next.js layout that load the pill in development only. |
+| Start the tour server now? | **1** starts it, so the pill shows right away. |
+
+IBM Bob reads its API key from the `BOB_API_KEY` environment variable. If it is
+not set, setup opens the page where you create a key and lets you paste it for
+that one run; DocuGate never saves it. To set it for good (then open a new terminal):
+
+```powershell
+[Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")   # Windows
+export BOB_API_KEY=<key>                                                # macOS, Linux
+```
 
-Once that is done:
+Setup writes `docugate.json` and `.docugate/tour/`. Commit both, so the next
+person who clones the repository needs no setup.
+
+**4. Start the tour server while you work.**
 
 ```sh
 docugate tour serve
 ```
 
-Start your app in another terminal, open it in the browser, and the pill appears in the corner.
+Leave it running in its own terminal. The pill only appears while it runs,
+which is why the pill never shows in production. If you started it at the end
+of step 3, it is already running.
+
+**5. Run your app as usual, in another terminal, and open it.**
+
+```sh
+npm run dev
+```
+
+The DocuGate pill sits in the bottom-right corner. Click it:
+
+- **Walkthrough** lists the page's steps with your progress. Click a step to
+  go to it, the pencil to fix it, or **Add a step**.
+- **Inspector** is one switch. With it on, click anything: you see what it is
+  and where its data comes from, and you can edit it. Click something with no
+  explanation yet, and the same click lets you add one.
+
+Every change is saved straight into `.docugate/tour/`, so it shows up in `git diff`.
+
+**6. Keep the tour true.**
+
+```sh
+docugate check
+```
+
+It checks every step against the code and warns about any that went stale,
+for example after a rename. Put it in CI so a stale tour fails the build (see
+[Keeping tours true](#keeping-tours-true)).
+
+**Later, when you need them:**
+
+```sh
+docugate login           # sign in again, or on a new computer
+docugate whoami          # who am I signed in as?
+docugate tour init       # let IBM Bob write tours for screens that have none
+docugate tour install    # add the pill again (--remove takes it out)
+docugate logout          # disconnect this computer
+```
+
+**Something not working?**
+
+| You see | Do this |
+| --- | --- |
+| No pill in the app | Check `docugate tour serve` is running, then refresh the page. |
+| Bob can't run | Choose IBM Bob again in `docugate init` to paste a key, or install Bob Shell: https://bob.ibm.com/docs/shell/getting-started/install-and-setup |
+| Port 4178 is busy | `docugate tour serve --port 4179` and `docugate tour install --port 4179` |
+| "Already set up in ..." | You ran it in a subfolder. Run commands from the folder it names. |
 
 ---
 
@@ -73,14 +159,24 @@ Tour files are yours. `docugate tour init` never overwrites a file that already
 
 ## The pill
 
-When `docugate tour serve` is running, the pill appears in the corner of your app. It has two modes:
+When `docugate tour serve` is running, the pill sits in a corner of your app,
+like the Next.js dev indicator. Drag it to any corner. Click it for two things:
 
-- **Walkthrough.** Steps through every stop on the current screen in order, highlighting each element and showing its tour card.
-- **Inspector.** Hovering highlights an element; clicking it shows its stop: what it is and where its data comes from. An element with no stop yet offers **Add to tour**, a small form that saves the stop straight into the tour file, and tells you which `data-tour` attribute to add when the element has none.
+- **Walkthrough.** The page's steps as a checklist with progress. Start from
+  any step: the page dims, a ring marks the element, and a card says what it
+  is and where its data comes from. Each step has a pencil to fix it, and
+  **Add a step** adds one.
+- **Inspector.** One switch. With it on, clicking an element shows its step,
+  with **Edit** to correct what the AI or anyone else got wrong, and **Remove**.
+  Clicking an element with no step lets you add it, and tells you which
+  `data-tour` attribute to put on it. Code and source files open in your
+  editor at the element's line.
 
-The pill stays on every page while the server runs, including pages with no tour yet, so their first stop can be added from the browser. Edits to the tour files show up on the page as you save them.
+The pill shows on every page while the server runs, including pages with no
+tour yet, so their first step can be added from the browser.
 
-`docugate tour install` adds the pill for you. It only loads when the app runs on `localhost` and the tour server answers, so it never shows in production.
+`docugate tour install` adds the pill for you. It only loads when the app runs
+on `localhost` and the tour server answers, so it never shows in production.
 
 ---
 
@@ -164,6 +260,8 @@ docugate tour serve
 
 Open the app in the browser. The pill appears in the bottom-right corner.
 
+Or try it without installing anything: https://docugate-demo.vercel.app/invoices/inv_1004. The hosted demo reads a copy of the tour, so editing is turned off there.
+
 ---
 
 ## Several repositories in one space

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { check } from './check.js';
 import { loadConfig } from './config.js';
-import { initFlow } from './init.js';
+import { choose, initFlow, makeDefaultIO } from './init.js';
 import { buildOpenApi, isCurrent, writeOpenApi } from './openapi.js';
 import { BobKeyMissingError, BobMissingError, tourInit } from './tour-init.js';
 import { tourInstall, hasPillSnippet, pillSnippetLine, DEFAULT_PORT } from './tour-install.js';
@@ -197,13 +198,27 @@ async function main() {
             if (roleFlag && !['frontend', 'backend', 'both'].includes(roleFlag)) {
                 fail(`--role must be frontend, backend, or both.`);
             }
-            await initFlow(root, {
+            const port = one('port') !== undefined ? parseInt(one('port'), 10) : DEFAULT_PORT;
+            const result = await initFlow(root, {
                 dir: one('dir'),
                 title: one('title'),
                 role: roleFlag,
                 yes: args.bools.has('yes'),
-                port: one('port') !== undefined ? parseInt(one('port'), 10) : undefined,
+                port,
             });
+            // The pill only shows while the tour server runs, so setup ends by
+            // offering to start it rather than leaving one more command to remember.
+            const where = result.alreadySetUp ?? root;
+            const hasTour = result.role === 'frontend' || result.role === 'both';
+            if (hasTour && process.stdin.isTTY && !args.bools.has('yes')) {
+                const io = makeDefaultIO();
+                const pick = await choose(io, 'Start the tour server now, so the pill shows in your app?', [
+                    'Yes, start it (leave this terminal open, then run your app as usual)',
+                    'Later: docugate tour serve',
+                ]);
+                if (pick === 1)
+                    await serveTour(where, port);
+            }
             return;
         }
         case 'check': {
@@ -329,24 +344,7 @@ ${dim(`Bob: ${parts.join(', ')}`)}`);
                     return;
                 }
                 case 'serve': {
-                    const tourDir = `${root}/.docugate/tour`;
-                    if (!existsSync(tourDir)) {
-                        console.error(`${red('error')} .docugate/tour/ not found. Run ${green('docugate tour init')} first.`);
-                        process.exit(2);
-                    }
-                    const port = parseInt(one('port') ?? '4178', 10);
-                    const server = await startTourServer(root, port);
-                    const url = `http://localhost:${server.port}`;
-                    const screens = loadTours(root);
-                    console.log(`${green('Tour server')}  ${url}`);
-                    console.log(`${plural(screens.length, 'screen')} loaded from .docugate/tour/`);
-                    if (!hasPillSnippet(root)) {
-                        console.log(`${dim('Hint: run')} ${green('docugate tour install')} ${dim('to add the pill to your app automatically.')}`);
-                    }
-                    // Keep the process alive; Ctrl-C will stop it.
-                    process.on('SIGINT', () => { server.close(); process.exit(0); });
-                    process.on('SIGTERM', () => { server.close(); process.exit(0); });
-                    await new Promise(() => { });
+                    await serveTour(root, parseInt(one('port') ?? '4178', 10));
                     return;
                 }
                 case 'export': {
@@ -371,3 +369,28 @@ main().catch((error) => {
     console.error(`${red('error')} ${error.message}`);
     process.exit(1);
 });
+/**
+ * Serves the tour to the pill until Ctrl-C. Starts even when there is no tour
+ * yet: the pill then shows on every page, and its inspector writes the first
+ * step, so a failed or skipped AI step never leaves the app without it.
+ */
+async function serveTour(root, port) {
+    mkdirSync(join(root, '.docugate', 'tour'), { recursive: true });
+    const server = await startTourServer(root, port);
+    const url = `http://localhost:${server.port}`;
+    const screens = loadTours(root);
+    console.log(`${green('Tour server')}  ${url}`);
+    if (screens.length) {
+        console.log(`${plural(screens.length, 'screen')} loaded from .docugate/tour/`);
+    }
+    else {
+        console.log(`No tour yet. Open your app: the pill shows on every page, and its Inspector adds the first step.`);
+    }
+    if (!hasPillSnippet(root)) {
+        console.log(`${dim('Hint: run')} ${green('docugate tour install')} ${dim('to add the pill to your app automatically.')}`);
+    }
+    console.log(dim('Leave this running while you work. Ctrl-C stops it.'));
+    process.on('SIGINT', () => { server.close(); process.exit(0); });
+    process.on('SIGTERM', () => { server.close(); process.exit(0); });
+    await new Promise(() => { });
+}

package/dist/init.js

@@ -3,7 +3,7 @@ import { execFileSync, spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { CONFIG_FILE, loadConfig } from './config.js';
-import { tourInit, BobMissingError, BobKeyMissingError, readBobKey, saveBobKey } from './tour-init.js';
+import { tourInit, BobMissingError, BobKeyMissingError, readBobKey, useBobKeyForThisRun } from './tour-init.js';
 import { tourInstall, pillSnippetLine, DEFAULT_PORT } from './tour-install.js';
 import { login, loadCredentials } from './auth.js';
 /**
@@ -39,7 +39,7 @@ export function init(root, opts = {}) {
     }
     return { created, kept, docsDir };
 }
-function makeDefaultIO() {
+export function makeDefaultIO() {
     const isTTY = Boolean(process.stdin.isTTY);
     return {
         isTTY,
@@ -91,13 +91,13 @@ function saveSetting(root, key, value) {
 }
 const BOB_KEYS_URL = 'https://bob.ibm.com/docs/ide/account/api-keys';
 /**
- * Bob Shell runs on its own with an API key, not the IDE sign-in. Setup gets
- * one without anyone editing environment variables: open the page that makes
- * it, paste it, and it is kept in ~/.docugate/bob.json, outside the repository.
+ * Bob Shell runs on its own with an API key, not the IDE sign-in, and reads it
+ * from BOB_API_KEY. When that is not set, setup can take a pasted key for this
+ * one run only: DocuGate never stores it, and says how to set it for good.
  */
 async function askForBobKey(io, openUrl) {
-    const pick = await choose(io, 'IBM Bob needs an API key to write the tour. Get one now?', [
-        'Yes, open the page to create an Inference key, then paste it here',
+    const pick = await choose(io, 'IBM Bob needs an API key (BOB_API_KEY is not set in your environment).', [
+        'Paste a key for this run only (opens the page that creates one)',
         'Skip the tour for now',
     ]);
     if (pick !== 1)
@@ -105,13 +105,16 @@ async function askForBobKey(io, openUrl) {
     io.print(`  In your Bob instance: API keys, then create an Inference key.`);
     io.print(`  ${BOB_KEYS_URL}`);
     (openUrl ?? openInBrowser)(BOB_KEYS_URL);
-    const key = (await io.ask('  Paste the key and press Enter (it stays on this computer)', '')).trim();
+    const key = (await io.ask('  Paste the key and press Enter (used for this run only, never saved)', '')).trim();
     if (!key) {
         io.print('  No key pasted. Skipped the tour: run docugate tour init when you have one.');
         return false;
     }
-    saveBobKey(key);
-    io.print('  Key saved in ~/.docugate/bob.json. It is never written into the repository.');
+    useBobKeyForThisRun(key);
+    io.print('  Using the key for this run only. To keep it for next time, set it in your environment:');
+    io.print(process.platform === 'win32'
+        ? '    [Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")   (then open a new terminal)'
+        : '    export BOB_API_KEY=<key>   (add it to your shell profile)');
     return true;
 }
 function openInBrowser(url) {
@@ -182,6 +185,53 @@ export async function choose(io, question, options, fallback = 1) {
         io.print(`  Type a number from 1 to ${options.length}.`);
     }
 }
+function run(cmd, args, cwd) {
+    try {
+        const out = execFileSync(cmd, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], shell: process.platform === 'win32' });
+        return { ok: true, out: out.trim() };
+    }
+    catch (err) {
+        const e = err;
+        return { ok: false, out: (e.stderr ?? e.message).trim() };
+    }
+}
+/**
+ * A space reads from a GitHub repository. When the project has none yet, offer
+ * to create one with the GitHub CLI, which is already signed in as the person,
+ * and push the code to it. Returns owner/name, or null when skipped or failed.
+ * DocuGate's own GitHub sign-in is not given the right to create repositories.
+ */
+async function createGitHubRepo(root, io) {
+    const pick = await choose(io, 'This project is not on GitHub yet, and a space reads from a GitHub repository.', [
+        'Create a GitHub repository for it now (uses the GitHub CLI)',
+        'Skip for now',
+    ]);
+    if (pick !== 1)
+        return null;
+    if (!run('gh', ['auth', 'status'], root).ok) {
+        io.print('  The GitHub CLI is not installed or not signed in.');
+        io.print('  Install it from https://cli.github.com, run gh auth login, then docugate init again.');
+        return null;
+    }
+    if (!run('git', ['rev-parse', 'HEAD'], root).ok) {
+        io.print('  Commit your code first (git add -A, then git commit), then run docugate init again.');
+        return null;
+    }
+    const visibility = await choose(io, 'Who can see the repository?', [
+        'Public',
+        'Private (a space from a private repository needs DocuGate Pro)',
+    ]);
+    const name = basename(root).replace(/[^A-Za-z0-9._-]+/g, '-');
+    const made = run('gh', ['repo', 'create', name, visibility === 1 ? '--public' : '--private', '--source', '.', '--remote', 'origin', '--push'], root);
+    if (!made.ok) {
+        io.print(`  Could not create the repository: ${made.out.split(/\r?\n/).pop()}`);
+        return null;
+    }
+    const slug = defaultGetRemote(root);
+    if (slug)
+        io.print(`  Created https://github.com/${slug} and pushed your code.`);
+    return slug;
+}
 function defaultGetRemote(root) {
     try {
         const remote = execFileSync('git', ['remote', 'get-url', 'origin'], {
@@ -318,10 +368,13 @@ export async function initFlow(root, options = {}) {
         }
         // ── 3b: connect this repository to a space ────────────────────────────────
         if (signedIn) {
-            // Read git remote.
-            const repoSlug = getRemoteFn(root);
+            // Read git remote; a project not on GitHub yet can be put there first.
+            let repoSlug = getRemoteFn(root);
+            if (!repoSlug && !yes) {
+                repoSlug = await (options.createRepoFn ?? createGitHubRepo)(root, io);
+            }
             if (!repoSlug) {
-                io.print(`  This repository has no GitHub remote yet, so it can't be connected to a space.`);
+                io.print(`  A space reads from a GitHub repository, so this one can't be connected yet.`);
             }
             else {
                 // List spaces.

package/dist/tour-init.js

@@ -1,8 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { join } from 'node:path';
 import { isMap, isSeq, parseDocument } from 'yaml';
 // `docugate tour init` writes the first tour of an app by asking IBM Bob
 // (through Bob Shell) to read the code. Bob does the reading; this file makes
@@ -76,30 +75,20 @@ export class BobMissingError extends Error {
 /** Bob Shell's headless mode signs in with an API key, not the IDE's IBMid session. */
 export class BobKeyMissingError extends Error {
 }
-/** Where `docugate init` keeps the Bob API key: the home folder, never the repository. */
-export function bobKeyPath() {
-    return join(homedir(), '.docugate', 'bob.json');
-}
-/** The Bob API key: BOB_API_KEY if set, else the one saved during setup. */
+/**
+ * The Bob API key comes from the environment only: BOB_API_KEY. DocuGate never
+ * writes it anywhere. A key pasted during setup is put in this process's
+ * environment for that one run, and is gone when the command ends.
+ */
 export function readBobKey() {
-    if (process.env.BOB_API_KEY)
-        return process.env.BOB_API_KEY;
-    try {
-        return JSON.parse(readFileSync(bobKeyPath(), 'utf8')).key || undefined;
-    }
-    catch {
-        return undefined;
-    }
+    return process.env.BOB_API_KEY || undefined;
 }
-export function saveBobKey(key) {
-    mkdirSync(dirname(bobKeyPath()), { recursive: true });
-    writeFileSync(bobKeyPath(), JSON.stringify({ key }) + '\n', { mode: 0o600 });
+export function useBobKeyForThisRun(key) {
+    process.env.BOB_API_KEY = key;
 }
 const defaultRunBob = (args, cwd) => {
-    const key = readBobKey();
     const result = spawnSync('bob', args, {
         cwd,
-        env: key ? { ...process.env, BOB_API_KEY: key } : process.env,
         encoding: 'utf8',
         // `bob` is a .cmd shim on Windows, which only runs through a shell.
         shell: process.platform === 'win32',

package/dist/tour-server.js

@@ -1,6 +1,6 @@
 import { spawn } from 'node:child_process';
 import { createServer } from 'node:http';
-import { existsSync, mkdirSync, readFileSync, realpathSync, watch, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, watch, writeFileSync } from 'node:fs';
 import { join, relative, resolve, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadTours, matchRoute, parseTourFile, routeToFilename, serializeTourFile } from './tour.js';
@@ -174,6 +174,52 @@ async function handlePutStop(req, res, root) {
     writeFileSync(filepath, serializeTourFile(tour));
     sendJson(res, 200, { ok: true });
 }
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.docugate', '.bob', 'coverage', '.vercel']);
+const CODE_FILE = /\.(tsx|jsx|ts|js|vue|svelte|html|astro)$/;
+/**
+ * The repository file that renders an element with this data-tour value, so
+ * the pill fills in "the file that shows it" instead of asking. A file with
+ * data-tour="value" wins over one that only passes the value along as a prop.
+ */
+export function findTourFile(root, value) {
+    const exact = new RegExp(`data-tour=["']${value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']`);
+    const quoted = new RegExp(`["']${value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}["']`);
+    let fallback;
+    let seen = 0;
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (++seen > 20000)
+                return undefined;
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith('.'))
+                    continue;
+                const found = walk(abs);
+                if (found)
+                    return found;
+            }
+            else if (CODE_FILE.test(entry.name)) {
+                const text = readFileSync(abs, 'utf8');
+                const rel = relative(root, abs).split('\\').join('/');
+                if (exact.test(text))
+                    return rel;
+                if (!fallback && quoted.test(text))
+                    fallback = rel;
+            }
+        }
+        return undefined;
+    };
+    return walk(root) ?? fallback;
+}
+function handleFind(req, res, root) {
+    const value = new URL(req.url ?? '/', 'http://localhost').searchParams.get('value') ?? '';
+    const path = value ? findTourFile(root, value) : undefined;
+    if (!path) {
+        sendJson(res, 404, { error: 'not found' });
+        return;
+    }
+    sendJson(res, 200, { path });
+}
 /** DELETE /stop { route, target }: removes one stop, leaving the rest of the file as it was. */
 async function handleDeleteStop(req, res, root) {
     let body;
@@ -309,6 +355,9 @@ export function startTourServer(root, port) {
                     sendJson(res, 500, { error: err.message });
                 });
             }
+            else if (req.method === 'GET' && path === '/find') {
+                handleFind(req, res, root);
+            }
             else if (req.method === 'POST' && path === '/open') {
                 handleOpen(req, res, root).catch((err) => {
                     sendJson(res, 500, { error: err.message });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docugate",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Command-line tools for DocuGate: set up, check and prepare the documentation DocuGate reads straight from your repository.",
   "type": "module",
   "bin": {

package/pill/dist/pill.js

@@ -50,6 +50,30 @@ function suggestSelector(el) {
     const tag = el.tagName.toLowerCase();
     return { selector: `[data-tour="${tag}"]`, needsAttribute: true };
 }
+/**
+ * A CSS selector that finds exactly this element today, for one with no
+ * data-tour attribute yet: its id if it has one, else the tag and position
+ * from the nearest ancestor with an id, or from the body.
+ */
+function uniqueSelector(el) {
+    if (el.id)
+        return `#${CSS.escape(el.id)}`;
+    const parts = [];
+    let node = el;
+    while (node && node !== document.body && node !== document.documentElement) {
+        if (node.id) {
+            parts.unshift(`#${CSS.escape(node.id)}`);
+            break;
+        }
+        const tag = node.tagName.toLowerCase();
+        const siblings = node.parentElement ? Array.from(node.parentElement.children).filter((c) => c.tagName === node.tagName) : [];
+        parts.unshift(siblings.length > 1 ? `${tag}:nth-of-type(${siblings.indexOf(node) + 1})` : tag);
+        node = node.parentElement;
+    }
+    if (!parts[0]?.startsWith('#'))
+        parts.unshift('body');
+    return parts.join(' > ');
+}
 // ---------------------------------------------------------------------------
 // Server URL: read from this script's own src attribute
 // ---------------------------------------------------------------------------
@@ -382,10 +406,12 @@ kbd {
 .step-edit svg { width: 15px; height: 15px; }
 .step-row:hover .step-edit, .step-edit:focus-visible { opacity: 1; }
 .step-edit:hover { color: #F4C43F; background: rgba(255, 255, 255, 0.07); }
-.step-edit:disabled { display: none; }
+.step-row .step:disabled + .step-edit { opacity: 1; color: #F4C43F; }
 .add-step { color: #a1a1a1; }
 .add-step .num { border-style: dashed; font-size: 14px; font-weight: 400; }
 .add-step:hover { background: rgba(255, 255, 255, 0.06); color: #ededed; }
+.wt-start { display: flex; align-items: center; justify-content: center; gap: 8px; width: 100%; height: 34px; margin: 4px 0 2px; }
+.wt-start svg { width: 13px; height: 13px; }
 .wt-empty { margin: 4px 8px 6px; font-size: 12.5px; line-height: 1.5; color: #a1a1a1; }
 .item-text { display: flex; flex-direction: column; gap: 1px; }
 .menu-list { border-top: 1px solid rgba(255, 255, 255, 0.07); }
@@ -527,7 +553,6 @@ function renderProse(el, prose) {
 }
 const CORNERS = ['bottom-right', 'bottom-left', 'top-right', 'top-left'];
 const CORNER_KEY = 'docugate-pill-corner';
-const HIDDEN_KEY = 'docugate-pill-hidden';
 const EDGE = 16;
 /** The corner nearest to a point, for snapping the badge where it is dropped. */
 function nearestCorner(x, y, width, height) {
@@ -574,6 +599,11 @@ class DocugatePill {
         this.inspEl = null;
         this.inspectedPath = location.pathname;
         this.listCollapsed = false;
+        /** Hidden for this page view only: a reload, or Alt+Shift+D, brings it back. */
+        this.hidden = false;
+        this.retarget = null;
+        /** When a re-attached step is saved, the target it had before. */
+        this.editingFrom = null;
         this.highlightEl = null;
         this.evtSource = null;
         this.isStaticMode = false;
@@ -592,6 +622,12 @@ class DocugatePill {
         document.body.appendChild(this.host);
         this.init();
         this.patchHistory();
+        document.addEventListener('keydown', (e) => {
+            if (e.altKey && e.shiftKey && e.code === 'KeyD') {
+                e.preventDefault();
+                this.setHidden(!this.hidden);
+            }
+        });
         if (!this.isStaticMode) {
             this.listenEvents();
         }
@@ -610,15 +646,8 @@ class DocugatePill {
     }
     render() {
         this.removePill();
-        if (!this.alive)
+        if (!this.alive || this.hidden)
             return;
-        try {
-            if (sessionStorage.getItem(HIDDEN_KEY))
-                return;
-        }
-        catch {
-            // storage blocked: show the pill
-        }
         const stops = this.tour?.stops.length ?? 0;
         const btn = document.createElement('button');
         btn.className = `pill-btn surface${this.inspectorActive ? ' inspecting' : ''}`;
@@ -688,6 +717,20 @@ class DocugatePill {
             this.toggleMenu();
         });
     }
+    setHidden(hidden) {
+        this.hidden = hidden;
+        if (hidden) {
+            if (this.inspectorActive)
+                this.stopInspector();
+            if (this.walkthroughActive)
+                this.stopWalkthrough();
+            this.removePill();
+            this.toast('Pill hidden. Reload the page, or press Alt+Shift+D, to bring it back.');
+        }
+        else {
+            this.render();
+        }
+    }
     removePill() {
         this.pillBtn?.remove();
         this.pillBtn = null;
@@ -761,6 +804,26 @@ class DocugatePill {
         section.appendChild(head);
         if (this.listCollapsed)
             return section;
+        const playable = stops.filter((st) => document.querySelector(st.target) !== null);
+        if (playable.length) {
+            const allSeen = playable.every((st) => seen.has(st.target));
+            const resume = playable.find((st) => !seen.has(st.target));
+            const start = document.createElement('button');
+            start.className = 'wt-btn primary wt-start';
+            start.innerHTML = `<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M5 3.5v9l7-4.5z" fill="currentColor"/></svg><span></span>`;
+            start.querySelector('span').textContent = allSeen
+                ? 'Watch again'
+                : done && resume
+                    ? `Continue from step ${stops.indexOf(resume) + 1}`
+                    : 'Start walkthrough';
+            start.addEventListener('click', () => {
+                this.closeMenu();
+                if (allSeen)
+                    this.resetVisited();
+                this.startWalkthrough(allSeen ? undefined : resume);
+            });
+            section.appendChild(start);
+        }
         const list = document.createElement('div');
         list.className = 'steps';
         stops.forEach((stop, i) => {
@@ -785,12 +848,20 @@ class DocugatePill {
                 edit.className = 'step-edit';
                 edit.setAttribute('aria-label', `Edit step ${i + 1}, ${stop.heading}`);
                 edit.innerHTML = `<svg viewBox="0 0 16 16" aria-hidden="true"><path d="M10.5 3.5l2 2L6 12H4v-2z" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"/></svg>`;
-                edit.disabled = !onPage;
+                if (!onPage)
+                    edit.setAttribute('aria-label', `Point step ${i + 1}, ${stop.heading}, at an element`);
                 edit.addEventListener('click', () => {
                     const el = document.querySelector(stop.target);
                     this.closeMenu();
-                    if (el)
+                    if (el) {
                         this.showInspPopup(el, stop, true);
+                        return;
+                    }
+                    // The step points at nothing on this page: the next click picks its element.
+                    this.retarget = stop;
+                    if (!this.inspectorActive)
+                        this.toggleInspector();
+                    this.toast(`Click the element "${stop.heading}" should point to.`);
                 });
                 row.appendChild(edit);
             }
@@ -848,18 +919,8 @@ class DocugatePill {
         const hide = document.createElement('button');
         hide.className = 'link-btn';
         hide.textContent = 'Hide';
-        hide.title = 'Hide until this tab is reloaded';
-        hide.addEventListener('click', () => {
-            try {
-                sessionStorage.setItem(HIDDEN_KEY, '1');
-            }
-            catch {
-                // hidden for now only
-            }
-            if (this.inspectorActive)
-                this.stopInspector();
-            this.removePill();
-        });
+        hide.title = 'Hide the pill. Reload the page or press Alt+Shift+D to bring it back.';
+        hide.addEventListener('click', () => this.setHidden(true));
         foot.append(status, hide);
         return foot;
     }
@@ -872,6 +933,14 @@ class DocugatePill {
             return new Set();
         }
     }
+    resetVisited() {
+        try {
+            sessionStorage.removeItem(`docugate-seen:${this.tour?.route ?? location.pathname}`);
+        }
+        catch {
+            // nothing remembered, nothing to reset
+        }
+    }
     markVisited(target) {
         const seen = this.visited();
         seen.add(target);
@@ -1105,6 +1174,15 @@ class DocugatePill {
             return;
         e.preventDefault();
         e.stopPropagation();
+        if (this.retarget) {
+            // Re-attach a step whose element was missing: same step, this element.
+            const old = this.retarget;
+            this.retarget = null;
+            const { selector, needsAttribute } = suggestSelector(el);
+            this.showInspPopup(el, { ...old, target: needsAttribute ? uniqueSelector(el) : selector }, true);
+            this.editingFrom = old.target;
+            return;
+        }
         const stop = this.findStopForElement(el);
         if (stop) {
             this.showInspPopup(el, stop);
@@ -1135,7 +1213,9 @@ class DocugatePill {
      * With no stop, it opens as the form for a new one.
      */
     showInspPopup(el, stop, editing = false) {
+        const from = this.editingFrom;
         this.closeInspPopup();
+        this.editingFrom = from;
         const panel = document.createElement('div');
         panel.className = 'insp-popup surface';
         panel.setAttribute('role', 'dialog');
@@ -1247,10 +1327,10 @@ class DocugatePill {
             { key: 'heading', label: 'Name', value: existing?.heading ?? '', placeholder: 'e.g. Total' },
             { key: 'prose', label: 'What it is', value: existing?.prose ?? '', multi: true, placeholder: 'e.g. The amount due: the subtotal plus tax, computed by `totals()`.' },
             { key: 'data', label: 'Data', value: existing?.data ?? '', placeholder: 'e.g. GET /api/invoices/:id → total' },
-            { key: 'code', label: 'Code file', value: existing?.code ?? '', placeholder: 'e.g. src/screens/Invoice.tsx' },
+            { key: 'code', label: 'File that shows it', value: existing?.code ?? '', placeholder: 'A path in your repository, e.g. src/pages/Home.tsx' },
             { key: 'source', label: 'Source file', value: existing?.source ?? '', placeholder: 'Optional: where the value is computed' },
             { key: 'docs', label: 'Docs link', value: existing?.docs ?? '', placeholder: 'Optional' },
-            { key: 'target', label: 'Selector', value: existing?.target ?? selector },
+            { key: 'target', label: 'Selector', value: existing?.target ?? (needsAttribute ? uniqueSelector(el) : selector) },
         ];
         const inputs = {};
         const form = document.createElement('form');
@@ -1273,12 +1353,25 @@ class DocugatePill {
         if (needsAttribute && !existing) {
             const warn = document.createElement('div');
             warn.className = 'add-form-warn';
-            warn.append('Add ');
+            const slug = tourValue(selector) ?? '';
             const code = document.createElement('code');
-            code.textContent = `data-tour="${tourValue(selector) ?? ''}"`;
-            warn.append(code, ' to this element in your code, so the stop keeps finding it.');
+            code.textContent = `data-tour="${slug}"`;
+            const sel = document.createElement('code');
+            sel.textContent = selector;
+            warn.append('This works now. To keep it working after a redesign, add ', code, ' to the element in your code, then set Selector to ', sel, '.');
             form.appendChild(warn);
         }
+        // Fill in the file for them: the tour server knows which file has this data-tour.
+        const value = tourValue(existing?.target ?? selector);
+        if (!this.isStaticMode && !inputs.code.value && value && !needsAttribute) {
+            fetch(`${this.base}/find?value=${encodeURIComponent(value)}`)
+                .then((r) => (r.ok ? r.json() : null))
+                .then((found) => {
+                if (found?.path && !inputs.code.value)
+                    inputs.code.value = found.path;
+            })
+                .catch(() => undefined);
+        }
         const error = document.createElement('p');
         error.className = 'panel-error';
         error.hidden = true;
@@ -1335,14 +1428,20 @@ class DocugatePill {
                 docs: value('docs') || undefined,
                 prose: value('prose'),
             };
-            const missing = !stop.heading ? 'a name' : !stop.code ? 'the code file' : !stop.target ? 'a selector' : '';
+            const missing = !stop.heading ? 'a name' : !stop.code ? 'the file that shows it' : !stop.target ? 'a selector' : '';
             if (missing) {
                 error.textContent = `Add ${missing} first.`;
                 error.hidden = false;
                 return;
             }
+            if (/^[a-z]+:\/\/|^localhost/i.test(stop.code)) {
+                error.textContent = 'The file is a path in your repository, like src/pages/Home.tsx, not the page address.';
+                error.hidden = false;
+                return;
+            }
             save.disabled = true;
-            const saved = await this.saveStop(stop, existing?.target);
+            const saved = await this.saveStop(stop, this.editingFrom ?? existing?.target);
+            this.editingFrom = null;
             save.disabled = false;
             if (!saved) {
                 error.textContent = 'Could not save. Is docugate tour serve still running?';
@@ -1372,6 +1471,7 @@ class DocugatePill {
         this.inspPopup?.remove();
         this.inspPopup = null;
         this.inspEl = null;
+        this.editingFrom = null;
     }
     showAddForm(el, existing) {
         this.showInspPopup(el, existing ?? null, true);