docugate 0.2.4 → 0.2.6

package/README.md

@@ -44,14 +44,15 @@ It asks, one at a time:
 | --- | --- |
 | 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. |
+| Where should the documentation live? | **1** creates a new space, with a new GitHub repository on your account to hold its markdown (`<project>-docs`, with a first page). Or pick one of your spaces. The pill then links to the published docs. |
 | 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
+IBM Bob reads its API key from the `BOB_API_KEY` environment variable. If you
+saved it under another name (say `IBM_BOB_KEY`), setup finds it and asks before
+using it. If there is none, 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

package/dist/api.js

@@ -7,6 +7,8 @@ const ERROR_MESSAGES = {
     pro_required: 'Private repositories need DocuGate Pro',
     no_repo_access: "DocuGate can't see this repository. Install the DocuGate GitHub App on it first",
     slug_taken: 'You already have a space with this name',
+    repo_exists: 'You already have a repository with this name on GitHub',
+    app_permission: "DocuGate isn't allowed to create repositories on your account yet. Accept the DocuGate app's updated permissions at https://github.com/settings/installations, then try again",
     github_required: 'Sign in with GitHub to create a space',
 };
 function friendlyError(code) {
@@ -45,7 +47,7 @@ export async function apiFetch(path, init = {}) {
             // ignore JSON parse failure
         }
         if (code)
-            throw new Error(friendlyError(code));
+            throw Object.assign(new Error(friendlyError(code)), { code });
         throw new Error(`DocuGate request failed with status ${res.status}`);
     }
     return res;
@@ -65,6 +67,17 @@ export async function createSpace(repo, name, docsDir) {
     });
     return (await res.json()).space;
 }
+/**
+ * Creates a repository on the person's GitHub account, as them. With `docs`,
+ * it is a documentation repository that starts with docs/index.md.
+ */
+export async function createRepo(name, isPrivate, docs) {
+    const res = await apiFetch('/api/repos', {
+        method: 'POST',
+        body: JSON.stringify({ name, private: isPrivate, docs: Boolean(docs), title: docs?.title }),
+    });
+    return (await res.json());
+}
 export async function connectRepo(spaceId, repo, docsDir) {
     await apiFetch(`/api/spaces/${spaceId}/sources`, {
         method: 'POST',

package/dist/init.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { basename, dirname, join } from 'node:path';
 import { CONFIG_FILE, loadConfig } from './config.js';
 import { tourInit, BobMissingError, BobKeyMissingError, readBobKey, useBobKeyForThisRun } from './tour-init.js';
+import { bobKeyCandidates, startSpinner } from './spinner.js';
 import { tourInstall, pillSnippetLine, DEFAULT_PORT } from './tour-install.js';
 import { login, loadCredentials } from './auth.js';
 /**
@@ -57,6 +58,67 @@ export function makeDefaultIO() {
         },
     };
 }
+/**
+ * A new space and the repository that holds its docs: the repository is
+ * created on the person's account with docs/index.md in it, then the space is
+ * made from it. Returns the space, or undefined when something stopped it
+ * (every reason is printed).
+ */
+async function createDocsSpace(io, projectName, baseUrl, options) {
+    const visibility = await choose(io, 'Who can read the docs repository on GitHub?', [
+        'Public',
+        'Private (a space from a private repository needs DocuGate Pro)',
+    ]);
+    const repoName = `${projectName.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-|-$/g, '')}-docs`;
+    const stop = startSpinner(['Creating the docs repository on GitHub', 'Writing its first page', 'Almost there']);
+    let repo;
+    try {
+        repo = await (options.createDocsRepoFn ?? (async (name, priv, title) => {
+            const { createRepo } = await import('./api.js');
+            return createRepo(name, priv, { title });
+        }))(repoName, visibility === 2, projectName);
+        stop();
+        io.print(`  Created ${repo.url}`);
+    }
+    catch (err) {
+        stop();
+        io.print(`  warning  ${err.message}`);
+        return undefined;
+    }
+    const createFn = options.createSpaceFn ?? (async (r, name, dir) => {
+        const { createSpace } = await import('./api.js');
+        return createSpace(r, name, dir);
+    });
+    // A space only ever reads a repository DocuGate can see. One installed on
+    // selected repositories may not include the new one yet: offer the install
+    // and try again once.
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const stopSpace = startSpinner(['Setting up your space', 'Reading the docs repository']);
+        try {
+            const space = await createFn(repo.repo, projectName, 'docs');
+            stopSpace();
+            io.print(`  Created space "${space.name}"`);
+            if (repo.seeded === false)
+                io.print(`  Add markdown files to docs/ in ${repo.repo} and they become pages.`);
+            return space;
+        }
+        catch (err) {
+            stopSpace();
+            io.print(`  warning  ${err.message}`);
+            if (err.code !== 'no_repo_access' || attempt > 0)
+                return undefined;
+            const fix = await choose(io, `The DocuGate GitHub App can't see ${repo.repo} yet.`, [
+                'Add it to the app (opens GitHub), then try again',
+                'Skip for now',
+            ]);
+            if (fix !== 1)
+                return undefined;
+            (options.openUrl ?? openInBrowser)(`${baseUrl}/api/auth/github?install=1`);
+            await io.ask(`  On GitHub, add ${repo.repo} (or choose All repositories) and save. Then press Enter here`, '');
+        }
+    }
+    return undefined;
+}
 /**
  * The nearest folder above `root`, inside the same Git repository, that has
  * DocuGate set up already (a docugate.json), if any.
@@ -185,53 +247,6 @@ 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'], {
@@ -366,93 +381,76 @@ export async function initFlow(root, options = {}) {
                 }
             }
         }
-        // ── 3b: connect this repository to a space ────────────────────────────────
+        // ── 3b: the space that holds this project's documentation ─────────────────
+        // A space reads markdown from a GitHub repository. A new space gets its own
+        // documentation repository, created on the person's account; an existing
+        // space can be picked instead. Either way docugate.json remembers it, so the
+        // pill can link to the published docs.
         if (signedIn) {
-            // 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);
+            const repoSlug = getRemoteFn(root);
+            let spaces = [];
+            try {
+                spaces = (await getSpacesFn()).spaces;
             }
-            if (!repoSlug) {
-                io.print(`  A space reads from a GitHub repository, so this one can't be connected yet.`);
+            catch (err) {
+                connectError = `Couldn't load spaces: ${err.message}`;
+                io.print(`  warning  ${connectError}`);
             }
-            else {
-                // List spaces.
-                let spaces = [];
+            const { docsDir: repoDocsDir, config } = loadConfig(root);
+            const projectName = config.title ?? repoSlug?.split('/')[1] ?? basename(root);
+            const hasRepo = (sp) => Boolean(repoSlug) && (sp.sources ?? []).some((src) => src.repo.toLowerCase() === repoSlug.toLowerCase());
+            const already = spaces.find(hasRepo);
+            const linkSpace = (sp) => {
+                saveSetting(root, 'space', `${sp.owner}/${sp.slug}`);
+                io.print(`  Docs will be published at ${BASE_URL}/${sp.owner}/${sp.slug}`);
+            };
+            const connectProject = async (sp) => {
+                if (!repoSlug || hasRepo(sp))
+                    return;
                 try {
-                    const res = await getSpacesFn();
-                    spaces = res.spaces;
+                    await connectFn(sp.id, repoSlug, repoDocsDir);
+                    io.print(`  Connected ${repoSlug} to space "${sp.name}".`);
                 }
                 catch (err) {
-                    connectError = `Couldn't load spaces: ${err.message}`;
+                    connectError = err.message;
                     io.print(`  warning  ${connectError}`);
                 }
-                const { docsDir: repoDocsDir } = loadConfig(root);
-                const hasRepo = (sp) => (sp.sources ?? []).some((src) => src.repo.toLowerCase() === repoSlug.toLowerCase());
-                const already = spaces.find(hasRepo);
-                if (connectError) {
-                    // the warning is printed already; carry on with the rest of setup
+            };
+            if (connectError) {
+                // the warning is printed already; carry on with the rest of setup
+            }
+            else if (yes) {
+                // --yes: use the space only when there is no doubt which one is meant.
+                const only = already ?? (spaces.length === 1 ? spaces[0] : undefined);
+                if (only) {
+                    await connectProject(only);
+                    linkSpace(only);
+                }
+                else if (spaces.length > 1) {
+                    io.print(`  Several spaces found: run docugate init again without --yes to choose.`);
                 }
-                else if (yes) {
-                    // --yes: connect only when there is no doubt which space is meant.
-                    if (already) {
-                        io.print(`  ${repoSlug} is already in space "${already.name}".`);
-                    }
-                    else if (spaces.length === 1) {
-                        try {
-                            await connectFn(spaces[0].id, repoSlug, repoDocsDir);
-                            io.print(`  Connected ${repoSlug} to space "${spaces[0].name}".`);
-                        }
-                        catch (err) {
-                            connectError = err.message;
-                            io.print(`  warning  ${connectError}`);
-                        }
-                    }
-                    else if (spaces.length > 1) {
-                        io.print(`  Several spaces found: run docugate init again without --yes to choose.`);
-                    }
+            }
+            else {
+                const choices = [
+                    'Create a new space, with a new repository for its docs',
+                    ...spaces.map((sp) => `${sp.name}  (${sp.owner}/${sp.slug})${hasRepo(sp) ? '  already has this project' : ''}`),
+                    'Skip for now',
+                ];
+                const pick = await choose(io, `Where should the documentation for ${projectName} live?`, choices, already ? spaces.indexOf(already) + 2 : 1);
+                if (pick === 1) {
+                    const created = await createDocsSpace(io, projectName, BASE_URL, options);
+                    if (created)
+                        linkSpace(created);
+                    else
+                        connectError = 'The space was not created.';
+                }
+                else if (pick <= spaces.length + 1) {
+                    const sp = spaces[pick - 2];
+                    await connectProject(sp);
+                    linkSpace(sp);
                 }
                 else {
-                    // Interactive: create a space, or pick one, or skip. Numbers only.
-                    const choices = [
-                        `Create a new space for ${repoSlug}`,
-                        ...spaces.map((sp) => `${sp.name}  (${sp.owner}/${sp.slug})${hasRepo(sp) ? '  already reads this repository' : ''}`),
-                        'Skip for now',
-                    ];
-                    const pick = await choose(io, `Which DocuGate space should document ${repoSlug}?`, choices, already ? spaces.indexOf(already) + 2 : 1);
-                    if (pick === 1) {
-                        try {
-                            const createFn = options.createSpaceFn ?? (async (repo, name, dir) => {
-                                const { createSpace } = await import('./api.js');
-                                return createSpace(repo, name, dir);
-                            });
-                            const created = await createFn(repoSlug, loadConfig(root).config.title ?? repoSlug.split('/')[1], repoDocsDir);
-                            io.print(`  Created space "${created.name}": ${BASE_URL}/${created.owner}/${created.slug}`);
-                        }
-                        catch (err) {
-                            connectError = err.message;
-                            io.print(`  warning  ${connectError}`);
-                        }
-                    }
-                    else if (pick <= spaces.length + 1) {
-                        const sp = spaces[pick - 2];
-                        if (hasRepo(sp)) {
-                            io.print(`  ${repoSlug} is already in space "${sp.name}". Nothing to change.`);
-                        }
-                        else {
-                            try {
-                                await connectFn(sp.id, repoSlug, repoDocsDir);
-                                io.print(`  Connected ${repoSlug} to space "${sp.name}".`);
-                            }
-                            catch (err) {
-                                connectError = err.message;
-                                io.print(`  warning  ${connectError}`);
-                            }
-                        }
-                    }
-                    else {
-                        io.print(`  Skipped. docugate init connects it any time.`);
-                    }
+                    io.print(`  Skipped. docugate init sets it up any time.`);
                 }
             }
         }
@@ -481,18 +479,46 @@ export async function initFlow(root, options = {}) {
             if (pick === 2)
                 io.print('  IBM watsonx is coming soon. Skipped for now: run docugate tour init when you are ready.');
             runTour = pick === 1;
-            if (runTour && !readBobKey() && !options.runBob)
-                runTour = await askForBobKey(io, options.openUrl);
+            if (runTour && !readBobKey() && !options.runBob) {
+                // The key may be in the environment under another name.
+                const [other] = bobKeyCandidates();
+                if (other) {
+                    const use = await choose(io, `BOB_API_KEY is not set, but ${other} is. Is that your IBM Bob key?`, [
+                        `Yes, use ${other} for this run`,
+                        'No',
+                    ]);
+                    if (use === 1) {
+                        useBobKeyForThisRun(process.env[other]);
+                        io.print(`  Tip: rename it to BOB_API_KEY in your environment so Bob finds it next time.`);
+                    }
+                }
+                if (!readBobKey())
+                    runTour = await askForBobKey(io, options.openUrl);
+            }
         }
         if (runTour) {
+            // Bob takes a minute or two. Show it working, the way an assistant does.
+            const stop = options.runBob
+                ? () => undefined
+                : startSpinner([
+                    'IBM Bob is reading your screens and routes',
+                    'Following each value to the endpoint it comes from',
+                    'Tracing it into the backend',
+                    'Writing the tour, one step per element',
+                    'Checking every file it names exists',
+                    'Still working: bigger apps take a little longer',
+                ]);
             try {
                 tourResult = tourInit(root, { runBob: options.runBob });
+                stop();
+                io.print(`  IBM Bob wrote the tour.`);
             }
             catch (error) {
+                stop();
                 // Bob missing or failed — describe what went wrong, then continue.
                 if (error instanceof BobKeyMissingError) {
                     tourError =
-                        `Bob Shell needs an API key. Set BOB_API_KEY, then run docugate tour init.`;
+                        `IBM Bob did not accept the key. Check BOB_API_KEY holds an Inference key from bob.ibm.com, then run docugate tour init.`;
                 }
                 else if (error instanceof BobMissingError) {
                     tourError =

package/dist/rules.js

@@ -58,4 +58,4 @@ export function firstHeading(content) {
     const heading = content.match(/^#\s+(.+)$/m);
     return heading ? heading[1].trim() : null;
 }
-export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'sidebar', 'api']);
+export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'space', 'sidebar', 'api']);

package/dist/spinner.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+/**
+ * A live "working on it" line for the waits in setup: a spinner, the elapsed
+ * time, and a status that changes every few seconds, so a minute of IBM Bob
+ * reading the code never looks like a frozen terminal.
+ *
+ * It runs in a small child process, so it keeps moving even while the main
+ * process is blocked waiting on Bob Shell. Only in a terminal; elsewhere it
+ * prints the first status once.
+ */
+export function startSpinner(statuses) {
+    if (!process.stderr.isTTY || process.env.CI) {
+        process.stderr.write(`  ${statuses[0]}...\n`);
+        return (finalLine) => {
+            if (finalLine)
+                process.stderr.write(`${finalLine}\n`);
+        };
+    }
+    const script = `
+    const statuses = JSON.parse(process.argv[1]);
+    const frames = ['⠋','⠙','⠹','⠸','⠼','⠴','⠦','⠧','⠇','⠏'];
+    const start = Date.now();
+    let i = 0;
+    const cols = () => process.stderr.columns || 80;
+    setInterval(() => {
+      const secs = Math.floor((Date.now() - start) / 1000);
+      const status = statuses[Math.min(Math.floor(secs / 6), statuses.length - 1)];
+      const line = '  ' + frames[i++ % frames.length] + ' ' + status + '... ' + secs + 's';
+      process.stderr.write('\\r' + line.slice(0, cols() - 1).padEnd(cols() - 1));
+    }, 90);
+  `;
+    const child = spawn(process.execPath, ['-e', script, JSON.stringify(statuses)], {
+        stdio: ['ignore', 'ignore', 'inherit'],
+    });
+    return (finalLine) => {
+        child.kill();
+        const width = process.stderr.columns || 80;
+        process.stderr.write(`\r${' '.repeat(width - 1)}\r`);
+        if (finalLine)
+            process.stderr.write(`${finalLine}\n`);
+    };
+}
+/** Environment variables that look like an IBM Bob key under another name. */
+export function bobKeyCandidates(env = process.env) {
+    return Object.keys(env)
+        .filter((name) => name !== 'BOB_API_KEY' && env[name])
+        .filter((name) => /BOB|IBM|WATSONX/i.test(name) && /KEY|TOKEN|SECRET/i.test(name))
+        .sort();
+}

package/dist/tour-server.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, watch,
 import { join, relative, resolve, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadTours, matchRoute, parseTourFile, routeToFilename, serializeTourFile } from './tour.js';
+import { loadConfig } from './config.js';
 // ---------------------------------------------------------------------------
 // Security helpers
 // ---------------------------------------------------------------------------
@@ -91,11 +92,19 @@ function handleGetTour(req, res, root) {
     const pathname = url.searchParams.get('path') ?? '/';
     const tours = loadTours(root);
     const match = tours.find((t) => matchRoute(t.route, pathname));
+    const docsUrl = publishedDocsUrl(root);
     if (!match) {
-        sendJson(res, 404, { error: 'not found' });
+        sendJson(res, 404, { error: 'not found', docsUrl });
         return;
     }
-    sendJson(res, 200, { route: match.route, title: match.title, file: match.file, stops: match.stops });
+    sendJson(res, 200, { route: match.route, title: match.title, file: match.file, docsUrl, stops: match.stops });
+}
+/** Where this project's docs are published, from the space docugate init saved. */
+export function publishedDocsUrl(root) {
+    const space = loadConfig(root).config.space;
+    if (!space || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(space))
+        return undefined;
+    return `${process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site'}/${space}`;
 }
 function handleGetEvents(req, res, root) {
     const tourDir = join(root, '.docugate', 'tour');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docugate",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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

@@ -104,11 +104,14 @@ async function fetchTour(base) {
     }
     try {
         const res = await fetch(`${base}/tour?path=${encodeURIComponent(pathname)}`, { signal: AbortSignal.timeout(3000) });
-        if (res.status === 404)
-            return { alive: true, tour: null };
+        if (res.status === 404) {
+            const body = (await res.json().catch(() => ({})));
+            return { alive: true, tour: null, docsUrl: body.docsUrl };
+        }
         if (!res.ok)
             return { alive: false, tour: null };
-        return { alive: true, tour: (await res.json()) };
+        const tour = (await res.json());
+        return { alive: true, tour, docsUrl: tour.docsUrl };
     }
     catch {
         return { alive: false, tour: null };
@@ -247,6 +250,8 @@ kbd {
   font-size: 12px;
   color: #8f8f8f;
 }
+.docs-link { margin-left: auto; color: #F4C43F; text-decoration: none; }
+.docs-link:hover { color: #ffd35c; background: rgba(244, 196, 63, 0.1); }
 .menu-foot .live { display: inline-flex; align-items: center; gap: 6px; }
 .menu-foot .live::before { content: ""; width: 6px; height: 6px; border-radius: 50%; background: #45d483; box-shadow: 0 0 0 3px rgba(69, 212, 131, 0.15); }
 .link-btn { border: 0; background: none; color: #a1a1a1; font: inherit; cursor: pointer; padding: 2px 4px; border-radius: 5px; }
@@ -601,6 +606,8 @@ class DocugatePill {
         this.listCollapsed = false;
         /** Hidden for this page view only: a reload, or Alt+Shift+D, brings it back. */
         this.hidden = false;
+        /** The project's published docs on DocuGate, when init linked a space. */
+        this.docsUrl = null;
         this.retarget = null;
         /** When a re-attached step is saved, the target it had before. */
         this.editingFrom = null;
@@ -640,9 +647,10 @@ class DocugatePill {
         this.render();
     }
     async load() {
-        const { alive, tour } = await fetchTour(this.base);
+        const { alive, tour, docsUrl } = await fetchTour(this.base);
         this.alive = alive;
         this.tour = tour;
+        this.docsUrl = docsUrl ?? null;
     }
     render() {
         this.removePill();
@@ -921,7 +929,17 @@ class DocugatePill {
         hide.textContent = 'Hide';
         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);
+        foot.append(status);
+        if (this.docsUrl && /^https:\/\//.test(this.docsUrl)) {
+            const docs = document.createElement('a');
+            docs.className = 'link-btn docs-link';
+            docs.href = this.docsUrl;
+            docs.target = '_blank';
+            docs.rel = 'noopener noreferrer';
+            docs.textContent = 'Open the docs ↗';
+            foot.append(docs);
+        }
+        foot.append(hide);
         return foot;
     }
     /** Steps seen on this screen in this tab, by target, so the checklist shows progress. */