docugate 0.2.1 → 0.2.3

package/README.md

@@ -1,251 +1,252 @@
-# docugate
-
-DocuGate publishes documentation straight from the markdown in your GitHub repositories and shows a walkthrough pill on your running app so any developer can see what each element on screen is and where its data comes from.
-
-```sh
-npm i -g docugate
-```
-
----
-
-## Quick start
-
-`cd` into your app's repository, then run:
-
-```sh
-docugate init
-```
-
-It walks you through four steps:
-
-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.
-
-Once that is done:
-
-```sh
-docugate tour serve
-```
-
-Start your app in another terminal, open it in the browser, and the pill appears in the corner.
-
----
-
-## Tours
-
-A tour helps a developer who is new to a codebase see what each element on screen is and where its data comes from. For each screen there is one markdown file in `.docugate/tour/`. Each file has front matter with a `route` and a `title`, then one `##` section per stop.
-
-**Example stop:**
-
-```markdown
----
-route: /invoices/:id
-title: Invoice detail
----
-
-## Total
-target: [data-tour="invoice-total"]
-data: GET /api/invoices/:id → total
-code: frontend/src/screens/InvoiceDetail.tsx
-source: backend/src/billing.ts
-docs: https://example.com/docs/billing
-
-The amount due: the subtotal plus tax, computed by `totals()` in the backend.
-```
-
-Fields:
-
-| Field | Required | Meaning |
-| --- | --- | --- |
-| `target` | yes | CSS selector for the element. Prefer `[data-tour="…"]`. |
-| `data` | no | Request and field: `METHOD /path → field`. |
-| `code` | yes | File that renders the element, relative to the repository root. |
-| `source` | no | File where the value is computed, when that is elsewhere. |
-| `docs` | no | URL to relevant documentation. |
-
-The prose paragraph after the fields explains what the element is and why its value is what it is.
-
-Tour files are yours. `docugate tour init` never overwrites a file that already exists.
-
----
-
-## The pill
-
-When `docugate tour serve` is running, the pill appears in the corner of your app. It has two modes:
-
-- **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.
-
-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.
-
-`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.
-
----
-
-## Keeping tours true
-
-A tour is only useful while it is true, so `docugate check` verifies every claim in `.docugate/tour/` against the code. For each stop it warns when:
-
-- the `code` file, or the `source` file, no longer exists;
-- the `code` file, and the files it imports, no longer mention the endpoint in `data`;
-- the `code` file no longer contains the `data-tour` value in `target` (a value passed through a prop counts);
-- a required field is missing, or two stops on one screen point at the same element.
-
-Rename `invoice-total` in a component and `check` tells you which stop went stale.
-
-It checks your docs folder too:
-
-- **Errors:** broken links between pages, links that leave the docs folder, two files that become the same URL, an unreadable `docugate.json`, an empty docs folder, or more than 300 pages.
-- **Warnings:** pages with no `# Title`, front matter, `.mdx` files, no landing page, and `sidebar` entries that match nothing.
-
-It exits with 1 when there are errors. Add `--strict` to fail on warnings too, which is how stale tour stops fail a build.
-
-Use it in CI:
-
-```yaml
-# .github/workflows/docs.yml
-name: Docs
-on: [push, pull_request]
-jobs:
-  check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-      - run: npx docugate@0.2 check --strict
-```
-
-Pin the version in CI, as above. Without a pin, the rules being enforced can change between two runs of the same workflow, which turns a green build red with nothing in the commit to explain it.
-
----
-
-## Commands
-
-| Command | Main flags | What it does |
-| --- | --- | --- |
-| `docugate init` | `--dir`, `--title`, `--role frontend\|backend\|both`, `--yes` | Set up this repository for DocuGate (interactive). |
-| `docugate check` | `--dir`, `--strict` | Check docs and tour files the way DocuGate will read them. |
-| `docugate openapi` | `--from`, `--out`, `--include`, `--exclude`, `--redact`, `--check` | Prepare an OpenAPI spec for the API reference. |
-| `docugate login` | | Sign in to DocuGate with GitHub. |
-| `docugate logout` | | Sign out and delete saved credentials. |
-| `docugate whoami` | | Print the currently signed-in user. |
-| `docugate tour init` | `--max-cost <n>`, `--team-id <id>` | Write the first tour with IBM Bob (uses Bob Shell). |
-| `docugate tour serve` | `--port <n>` (default 4178) | Start the local server that serves tour data for the pill. |
-| `docugate tour install` | `--port <n>`, `--remove` | Add (or remove) the pill loader from your app's HTML or layout. |
-| `docugate tour export <file>` | | Write every tour screen to a single JSON file. |
-
-Run every command from the root of your repository.
-
----
-
-## Try it on the demo
-
-Clone [docugate-demo](https://github.com/Docugate/docugate-demo), a small full-stack app with a pre-written tour:
-
-```sh
-git clone https://github.com/Docugate/docugate-demo
-cd docugate-demo
-
-# install dependencies and start the app
-npm install
-npm run dev
-```
-
-In a second terminal:
-
-```sh
-cd docugate-demo
-docugate tour serve
-```
-
-Open the app in the browser. The pill appears in the bottom-right corner.
-
----
-
-## Several repositories in one space
-
-A space can merge docs from a frontend, a backend, and a mobile app into one set of pages. `docugate init` connects the repository it runs in to one of your spaces once you are signed in; you can also add repositories from a space's settings on [trydocugate.site](https://www.trydocugate.site/dashboard).
-
-Run `init` and `check` in each repository that contributes docs, and answer the role question in each: the tour lives in the frontend, and its `source` lines can point into the backend. Every one gets its own `docugate.json`, naming its own docs folder. `check` reads the repository it is run in, which is why its 300-page limit is per repository rather than per space.
-
-See [Merging repositories](https://www.trydocugate.site/docs/merging-repositories).
-
----
-
-## `openapi`
-
-Takes the OpenAPI 3 spec your backend already produces and writes the version you want published: only the public paths, without sensitive fields, with keys in a stable order so it reviews cleanly in a pull request.
-
-```sh
-docugate openapi --from http://localhost:3000/openapi.json \
-  --exclude "/internal/**" --redact passwordHash --out openapi.json
-```
-
-- `--from`: a `.json`, `.yaml` or `.yml` file, or a URL serving one.
-- `--include` / `--exclude`: path globs; `*` matches within one segment and `**` matches across segments. Both can be repeated.
-- `--redact`: a property name to remove from every schema and example. Can be repeated.
-- `--check`: do not write anything; exit with 1 if the committed file is out of date. Useful in CI.
-
-Instead of passing flags every time, set the same options in `docugate.json`:
-
-```json
-{
-  "docsDir": "docs",
-  "api": {
-    "generate": {
-      "from": "http://localhost:3000/openapi.json",
-      "output": "openapi.json",
-      "exclude": ["/internal/**"],
-      "redact": ["passwordHash"]
-    }
-  }
-}
-```
-
----
-
-## `docugate.json`
-
-One per repository, at its root.
-
-| Key | Meaning |
-| --- | --- |
-| `docsDir` | The folder DocuGate reads. Defaults to `docs`. |
-| `title` | The space's title. |
-| `role` | Repository role: `frontend`, `backend`, or `both`. Set by `docugate init`. |
-| `sidebar` | File and folder names in the order the sidebar should show them. Orders this repository's own pages, not the whole space. |
-| `api.generate` | Defaults for `docugate openapi`. |
-
----
-
-## IBM Bob 2.0 hackathon
-
-This repository is DocuGate's entry to the IBM Bob 2.0 hackathon (lablab.ai, September 25 to 27, 2026). To be clear about what was built when:
-
-**Before the event:** the CLI that was already in DocuGate's private repository: `docugate init`, `docugate check`, and `docugate openapi`. Moved here with its history.
-
-**During the event, with IBM Bob.** Each task has its session summary and export in `bob_sessions/`, and a plan where Bob planned first:
-
-| Task | What Bob built |
-| --- | --- |
-| 01 | The first tour: Bob read the Ledgerly demo and wrote `.docugate/tour/invoice-detail.md`, tracing each value to its endpoint and backend file. |
-| 02 | The tour format in code (`parseTourFile`, `serializeTourFile`, `loadTours`, `matchRoute`) and the tour checks in `docugate check`. |
-| 03 | `docugate tour serve` (tour data, live change events, saving stops) and `docugate tour export`. |
-| 04 | The pill: walkthrough, inspector and Add to tour, in a shadow DOM with no dependencies. |
-| 05 | One command: `docugate init` walks through the whole setup, and `docugate tour install` adds the pill to the app. |
-| 06 | `docugate login`, `logout` and `whoami`, and connecting the repository to a space during `init`. |
-| 07 | This README. |
-
-`docugate tour init` also runs IBM Bob itself, through Bob Shell. It installs a Tour Writer mode that may only edit `.docugate/tour/`, asks Bob to read the app's code, and never changes a tour file the user already has.
-
-**During the event, without Bob:** the Ledgerly demo app; the website side of `docugate login` on trydocugate.site; and fixes found while testing, such as Windows short paths in `tour serve` and the sign-in link on Windows.
-
----
-
-## Licence
-
-MIT
+# docugate
+
+DocuGate publishes documentation straight from the markdown in your GitHub repositories and shows a walkthrough pill on your running app so any developer can see what each element on screen is and where its data comes from.
+
+```sh
+npm i -g docugate
+```
+
+---
+
+## Quick start
+
+`cd` into your app's repository, then run:
+
+```sh
+docugate init
+```
+
+It walks you through four steps:
+
+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.
+
+Once that is done:
+
+```sh
+docugate tour serve
+```
+
+Start your app in another terminal, open it in the browser, and the pill appears in the corner.
+
+---
+
+## Tours
+
+A tour helps a developer who is new to a codebase see what each element on screen is and where its data comes from. For each screen there is one markdown file in `.docugate/tour/`. Each file has front matter with a `route` and a `title`, then one `##` section per stop.
+
+**Example stop:**
+
+```markdown
+---
+route: /invoices/:id
+title: Invoice detail
+---
+
+## Total
+target: [data-tour="invoice-total"]
+data: GET /api/invoices/:id → total
+code: frontend/src/screens/InvoiceDetail.tsx
+source: backend/src/billing.ts
+docs: https://example.com/docs/billing
+
+The amount due: the subtotal plus tax, computed by `totals()` in the backend.
+```
+
+Fields:
+
+| Field | Required | Meaning |
+| --- | --- | --- |
+| `target` | yes | CSS selector for the element. Prefer `[data-tour="…"]`. |
+| `data` | no | Request and field: `METHOD /path → field`. |
+| `code` | yes | File that renders the element, relative to the repository root. |
+| `source` | no | File where the value is computed, when that is elsewhere. |
+| `docs` | no | URL to relevant documentation. |
+
+The prose paragraph after the fields explains what the element is and why its value is what it is.
+
+Tour files are yours. `docugate tour init` never overwrites a file that already exists.
+
+---
+
+## The pill
+
+When `docugate tour serve` is running, the pill appears in the corner of your app. It has two modes:
+
+- **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.
+
+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.
+
+`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.
+
+---
+
+## Keeping tours true
+
+A tour is only useful while it is true, so `docugate check` verifies every claim in `.docugate/tour/` against the code. For each stop it warns when:
+
+- the `code` file, or the `source` file, no longer exists;
+- the `code` file, and the files it imports, no longer mention the endpoint in `data`;
+- the `code` file no longer contains the `data-tour` value in `target` (a value passed through a prop counts);
+- a required field is missing, or two stops on one screen point at the same element.
+
+Rename `invoice-total` in a component and `check` tells you which stop went stale.
+
+It checks your docs folder too:
+
+- **Errors:** broken links between pages, links that leave the docs folder, two files that become the same URL, an unreadable `docugate.json`, an empty docs folder, or more than 300 pages.
+- **Warnings:** pages with no `# Title`, front matter, `.mdx` files, no landing page, and `sidebar` entries that match nothing.
+
+It exits with 1 when there are errors. Add `--strict` to fail on warnings too, which is how stale tour stops fail a build.
+
+Use it in CI:
+
+```yaml
+# .github/workflows/docs.yml
+name: Docs
+on: [push, pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npx docugate@0.2 check --strict
+```
+
+Pin the version in CI, as above. Without a pin, the rules being enforced can change between two runs of the same workflow, which turns a green build red with nothing in the commit to explain it.
+
+---
+
+## Commands
+
+| Command | Main flags | What it does |
+| --- | --- | --- |
+| `docugate init` | `--dir`, `--title`, `--role frontend\|backend\|both`, `--yes` | Set up this repository for DocuGate (interactive). |
+| `docugate check` | `--dir`, `--strict` | Check docs and tour files the way DocuGate will read them. |
+| `docugate openapi` | `--from`, `--out`, `--include`, `--exclude`, `--redact`, `--check` | Prepare an OpenAPI spec for the API reference. |
+| `docugate login` | | Sign in to DocuGate with GitHub. |
+| `docugate logout` | | Sign out and delete saved credentials. |
+| `docugate whoami` | | Print the currently signed-in user. |
+| `docugate tour init` | `--max-cost <n>`, `--team-id <id>` | Write the first tour with IBM Bob (uses Bob Shell). |
+| `docugate tour serve` | `--port <n>` (default 4178) | Start the local server that serves tour data for the pill. |
+| `docugate tour install` | `--port <n>`, `--remove` | Add (or remove) the pill loader from your app's HTML or layout. |
+| `docugate tour export <file>` | | Write every tour screen to a single JSON file. |
+
+Run every command from the root of your repository.
+
+---
+
+## Try it on the demo
+
+Clone [docugate-demo](https://github.com/Docugate/docugate-demo), a small full-stack app with a pre-written tour:
+
+```sh
+git clone https://github.com/Docugate/docugate-demo
+cd docugate-demo
+
+# install dependencies and start the app
+npm install
+npm run dev
+```
+
+In a second terminal:
+
+```sh
+cd docugate-demo
+docugate tour serve
+```
+
+Open the app in the browser. The pill appears in the bottom-right corner.
+
+---
+
+## Several repositories in one space
+
+A space can merge docs from a frontend, a backend, and a mobile app into one set of pages. `docugate init` connects the repository it runs in to one of your spaces once you are signed in; you can also add repositories from a space's settings on [trydocugate.site](https://www.trydocugate.site/dashboard).
+
+Run `init` and `check` in each repository that contributes docs, and answer the role question in each: the tour lives in the frontend, and its `source` lines can point into the backend. Every one gets its own `docugate.json`, naming its own docs folder. `check` reads the repository it is run in, which is why its 300-page limit is per repository rather than per space.
+
+See [Merging repositories](https://www.trydocugate.site/docs/merging-repositories).
+
+---
+
+## `openapi`
+
+Takes the OpenAPI 3 spec your backend already produces and writes the version you want published: only the public paths, without sensitive fields, with keys in a stable order so it reviews cleanly in a pull request.
+
+```sh
+docugate openapi --from http://localhost:3000/openapi.json \
+  --exclude "/internal/**" --redact passwordHash --out openapi.json
+```
+
+- `--from`: a `.json`, `.yaml` or `.yml` file, or a URL serving one.
+- `--include` / `--exclude`: path globs; `*` matches within one segment and `**` matches across segments. Both can be repeated.
+- `--redact`: a property name to remove from every schema and example. Can be repeated.
+- `--check`: do not write anything; exit with 1 if the committed file is out of date. Useful in CI.
+
+Instead of passing flags every time, set the same options in `docugate.json`:
+
+```json
+{
+  "docsDir": "docs",
+  "api": {
+    "generate": {
+      "from": "http://localhost:3000/openapi.json",
+      "output": "openapi.json",
+      "exclude": ["/internal/**"],
+      "redact": ["passwordHash"]
+    }
+  }
+}
+```
+
+---
+
+## `docugate.json`
+
+One per repository, at its root.
+
+| Key | Meaning |
+| --- | --- |
+| `docsDir` | The folder DocuGate reads. Defaults to `docs`. |
+| `title` | The space's title. |
+| `role` | Repository role: `frontend`, `backend`, or `both`. Set by `docugate init`. |
+| `freshness` | How often DocuGate checks that the docs still match the code: `push`, `daily`, `weekly` or `off`. Set by `docugate init`; the scheduled check itself is coming soon. |
+| `sidebar` | File and folder names in the order the sidebar should show them. Orders this repository's own pages, not the whole space. |
+| `api.generate` | Defaults for `docugate openapi`. |
+
+---
+
+## IBM Bob 2.0 hackathon
+
+This repository is DocuGate's entry to the IBM Bob 2.0 hackathon (lablab.ai, September 25 to 27, 2026). To be clear about what was built when:
+
+**Before the event:** the CLI that was already in DocuGate's private repository: `docugate init`, `docugate check`, and `docugate openapi`. Moved here with its history.
+
+**During the event, with IBM Bob.** Each task has its session summary and export in `bob_sessions/`, and a plan where Bob planned first:
+
+| Task | What Bob built |
+| --- | --- |
+| 01 | The first tour: Bob read the Ledgerly demo and wrote `.docugate/tour/invoice-detail.md`, tracing each value to its endpoint and backend file. |
+| 02 | The tour format in code (`parseTourFile`, `serializeTourFile`, `loadTours`, `matchRoute`) and the tour checks in `docugate check`. |
+| 03 | `docugate tour serve` (tour data, live change events, saving stops) and `docugate tour export`. |
+| 04 | The pill: walkthrough, inspector and Add to tour, in a shadow DOM with no dependencies. |
+| 05 | One command: `docugate init` walks through the whole setup, and `docugate tour install` adds the pill to the app. |
+| 06 | `docugate login`, `logout` and `whoami`, and connecting the repository to a space during `init`. |
+| 07 | This README. |
+
+`docugate tour init` also runs IBM Bob itself, through Bob Shell. It installs a Tour Writer mode that may only edit `.docugate/tour/`, asks Bob to read the app's code, and never changes a tour file the user already has.
+
+**During the event, without Bob:** the Ledgerly demo app; the website side of `docugate login` on trydocugate.site; and fixes found while testing, such as Windows short paths in `tour serve` and the sign-in link on Windows.
+
+---
+
+## Licence
+
+MIT

package/dist/api.js

@@ -3,6 +3,11 @@ import { loadCredentials, saveCredentials } from './auth.js';
 export const BASE_URL = process.env.DOCUGATE_URL ?? 'https://www.trydocugate.site';
 const ERROR_MESSAGES = {
     pro_required_sources: 'Connecting more than one repository to a space needs DocuGate Pro',
+    space_limit: 'The free plan has one space. Connect this repository to it, or upgrade to Pro',
+    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',
+    github_required: 'Sign in with GitHub to create a space',
 };
 function friendlyError(code) {
     return ERROR_MESSAGES[code] ?? `DocuGate said: ${code}`;
@@ -53,6 +58,13 @@ export async function getSpaces() {
     const res = await apiFetch('/api/spaces/mine');
     return res.json();
 }
+export async function createSpace(repo, name, docsDir) {
+    const res = await apiFetch('/api/spaces', {
+        method: 'POST',
+        body: JSON.stringify({ repo, name, docsDir }),
+    });
+    return (await res.json()).space;
+}
 export async function connectRepo(spaceId, repo, docsDir) {
     await apiFetch(`/api/spaces/${spaceId}/sources`, {
         method: 'POST',

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

@@ -1,9 +1,9 @@
 import { createInterface } from 'node:readline';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { CONFIG_FILE, loadConfig } from './config.js';
-import { tourInit, BobMissingError, BobKeyMissingError } from './tour-init.js';
+import { tourInit, BobMissingError, BobKeyMissingError, readBobKey, saveBobKey } 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,
@@ -57,6 +57,80 @@ function makeDefaultIO() {
         },
     };
 }
+/**
+ * The nearest folder above `root`, inside the same Git repository, that has
+ * DocuGate set up already (a docugate.json), if any.
+ */
+export function setUpAbove(root) {
+    if (existsSync(join(root, '.git')))
+        return undefined;
+    let dir = dirname(root);
+    while (dir !== dirname(dir)) {
+        if (existsSync(join(dir, CONFIG_FILE)))
+            return dir;
+        if (existsSync(join(dir, '.git')))
+            return undefined;
+        dir = dirname(dir);
+    }
+    return undefined;
+}
+/** Sets one key in docugate.json, keeping everything else as it was. */
+function saveSetting(root, key, value) {
+    const path = join(root, CONFIG_FILE);
+    let existing = {};
+    if (existsSync(path)) {
+        try {
+            existing = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            // unreadable: start again with this key
+        }
+    }
+    existing[key] = value;
+    writeFileSync(path, JSON.stringify(existing, null, 2) + '\n');
+}
+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.
+ */
+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',
+        'Skip the tour for now',
+    ]);
+    if (pick !== 1)
+        return false;
+    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();
+    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.');
+    return true;
+}
+function openInBrowser(url) {
+    const [cmd, args] = process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]]
+        : process.platform === 'darwin' ? ['open', [url]]
+            : ['xdg-open', [url]];
+    try {
+        spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch {
+        // the URL is printed above
+    }
+}
+export const FRESHNESS = [
+    { value: 'push', label: 'On every push' },
+    { value: 'daily', label: 'Once a day (recommended: fewer AI runs)' },
+    { value: 'weekly', label: 'Once a week' },
+    { value: 'off', label: 'Never, I will ask for it' },
+];
 function saveRole(root, role) {
     const path = join(root, CONFIG_FILE);
     let existing = {};
@@ -71,7 +145,43 @@ function saveRole(root, role) {
     existing.role = role;
     writeFileSync(path, JSON.stringify(existing, null, 2) + '\n');
 }
-const VALID_ROLES = new Set(['frontend', 'backend', 'both']);
+const ROLE_CHOICES = [{ role: 'frontend' }, { role: 'backend' }, { role: 'both' }];
+const FRONTEND_DIRS = ['frontend', 'client', 'web'];
+const BACKEND_DIRS = ['backend', 'server', 'api'];
+const FRONTEND_MARKERS = ['index.html', 'vite.config.ts', 'vite.config.js', 'next.config.js', 'next.config.mjs', 'next.config.ts', 'angular.json', 'svelte.config.js'];
+const BACKEND_MARKERS = ['go.mod', 'requirements.txt', 'pyproject.toml', 'manage.py', 'pom.xml', 'build.gradle', 'Gemfile', 'composer.json'];
+/**
+ * What the repository probably is, from its folders and files, so the question
+ * can suggest an answer. Only a suggestion: the person always confirms it.
+ */
+export function guessRole(root) {
+    const has = (name) => existsSync(join(root, name));
+    const front = FRONTEND_DIRS.some(has);
+    const back = BACKEND_DIRS.some(has);
+    if (front && back)
+        return 'both';
+    if (FRONTEND_MARKERS.some(has) || front)
+        return 'frontend';
+    if (BACKEND_MARKERS.some(has) || back)
+        return 'backend';
+    return undefined;
+}
+/**
+ * A numbered choice: prints the options, and takes only a number. Enter picks
+ * the default. Nobody types a word during setup.
+ */
+export async function choose(io, question, options, fallback = 1) {
+    io.print('');
+    io.print(`  ${question}`);
+    options.forEach((option, i) => io.print(`    ${i + 1}  ${option}`));
+    for (;;) {
+        const answer = (await io.ask(`  Choose 1-${options.length} [${fallback}]`, String(fallback))).trim();
+        const n = Number(answer);
+        if (Number.isInteger(n) && n >= 1 && n <= options.length)
+            return n;
+        io.print(`  Type a number from 1 to ${options.length}.`);
+    }
+}
 function defaultGetRemote(root) {
     try {
         const remote = execFileSync('git', ['remote', 'get-url', 'origin'], {
@@ -97,6 +207,16 @@ export async function initFlow(root, options = {}) {
     const io = options.io ?? makeDefaultIO();
     const yes = options.yes ?? false;
     const port = options.port ?? DEFAULT_PORT;
+    // One project gets one setup and one tour. Run inside frontend/ of a
+    // project already set up at its root, and init points there instead of
+    // starting a second one.
+    const parent = setUpAbove(root);
+    if (parent) {
+        io.print(`  This project is already set up in ${parent}.`);
+        io.print(`  One project has one tour: run docugate commands from that folder.`);
+        const above = loadConfig(parent);
+        return { created: [], kept: [], docsDir: above.docsDir, role: above.config.role, alreadySetUp: parent };
+    }
     // ── Step 1: base repo setup (docugate.json + docs/) ──────────────────────
     const base = init(root, { dir: options.dir, title: options.title });
     // ── Step 2: determine role ────────────────────────────────────────────────
@@ -116,15 +236,19 @@ export async function initFlow(root, options = {}) {
             role = 'both';
         }
         else {
-            // Interactive: ask once; re-prompt on invalid answer.
-            let answer = '';
-            while (!VALID_ROLES.has(answer)) {
-                answer = await io.ask('Is this repository the frontend, the backend, or both? [frontend/backend/both]', 'both');
-                if (!VALID_ROLES.has(answer)) {
-                    io.print(`  Please answer frontend, backend, or both.`);
-                }
-            }
-            role = answer;
+            // Interactive: a numbered choice with examples, the likely answer
+            // suggested from the folders in the repository.
+            const guess = guessRole(root);
+            const guessNumber = String(ROLE_CHOICES.findIndex((c) => c.role === guess) + 1);
+            const n = await choose(io, `What is in this repository?${guess ? ` (it looks like ${guess})` : ''}`, [
+                'Frontend   the app people see: React, Vue, Svelte, Next.js, plain HTML',
+                'Backend    the API or server: Node, Python, Go, Java, ...',
+                'Both       frontend and backend in one repository, for example:\n' +
+                    '                 my-app/\n' +
+                    '                 ├─ frontend/   (or client/, web/)\n' +
+                    '                 └─ backend/    (or server/, api/)',
+            ], guessNumber === '0' ? 3 : Number(guessNumber));
+            role = ROLE_CHOICES[n - 1].role;
         }
     }
     if (!savedRole) {
@@ -174,8 +298,11 @@ export async function initFlow(root, options = {}) {
         if (!signedIn) {
             let doLogin = yes;
             if (!yes) {
-                const answer = await io.ask('Sign in to DocuGate now? [Y/n]', 'y');
-                doLogin = !/^n(o)?$/i.test(answer);
+                doLogin =
+                    (await choose(io, 'Sign in to DocuGate, so this repository can feed a space?', [
+                        'Yes, open the browser to sign in',
+                        'Skip for now (docugate login does it later)',
+                    ])) === 1;
             }
             if (doLogin) {
                 try {
@@ -207,55 +334,84 @@ export async function initFlow(root, options = {}) {
                     connectError = `Couldn't load spaces: ${err.message}`;
                     io.print(`  warning  ${connectError}`);
                 }
-                if (spaces.length === 0 && !connectError) {
-                    io.print(`  No spaces found. Create one first: ${BASE_URL}/dashboard/new`);
+                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
                 }
-                else if (spaces.length > 0) {
-                    const { docsDir: repoDocsDir } = loadConfig(root);
-                    if (yes) {
-                        // --yes: auto-connect only when there is exactly one space.
-                        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 (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}".`);
                         }
-                        else {
-                            io.print(`  Multiple spaces found — run docugate init again without --yes to choose:`);
-                            for (const s of spaces)
-                                io.print(`    ${s.owner}/${s.slug}  ${s.name}`);
+                        catch (err) {
+                            connectError = err.message;
+                            io.print(`  warning  ${connectError}`);
                         }
                     }
-                    else {
-                        // Interactive: list spaces and ask.
-                        io.print(`  Your spaces:`);
-                        for (let i = 0; i < spaces.length; i++) {
-                            io.print(`    ${i + 1}. ${spaces[i].name}  (${spaces[i].owner}/${spaces[i].slug})`);
+                    else if (spaces.length > 1) {
+                        io.print(`  Several spaces found: run docugate init again without --yes to choose.`);
+                    }
+                }
+                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.`);
                         }
-                        const answer = await io.ask(`Connect ${repoSlug} to which space? [1-${spaces.length}/skip]`, 'skip');
-                        const idx = parseInt(answer, 10) - 1;
-                        if (!isNaN(idx) && idx >= 0 && idx < spaces.length) {
+                        else {
                             try {
-                                await connectFn(spaces[idx].id, repoSlug, repoDocsDir);
-                                io.print(`  Connected ${repoSlug} to space "${spaces[idx].name}".`);
+                                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 connecting to a space.`);
-                        }
+                    }
+                    else {
+                        io.print(`  Skipped. docugate init connects it any time.`);
                     }
                 }
             }
         }
     }
+    // ── Step 3c: how often the docs are checked against the code ─────────────
+    if (io.isTTY && !loaded.config.freshness) {
+        const n = yes
+            ? 2
+            : await choose(io, 'How often should DocuGate check that your docs still match the code?', FRESHNESS.map((f) => f.label), 2);
+        saveSetting(root, 'freshness', FRESHNESS[n - 1].value);
+        io.print(`  Saved: ${FRESHNESS[n - 1].label.split(' (')[0].toLowerCase()}. Change "freshness" in docugate.json any time.`);
+    }
     // ── Step 4: tour steps (frontend / both only) ─────────────────────────────
     let tourResult;
     let tourError;
@@ -264,8 +420,16 @@ export async function initFlow(root, options = {}) {
         // Decide whether to run tour init.
         let runTour = yes;
         if (!yes && io.isTTY) {
-            const answer = await io.ask('Write the tour with IBM Bob? (costs Bobcoins) [y/N]', 'n');
-            runTour = /^y(es)?$/i.test(answer);
+            const pick = await choose(io, 'Set up the tour: which AI should read your code and write it?', [
+                'IBM Bob (uses Bobcoins)',
+                'IBM watsonx (coming soon)',
+                'Skip, I will write it in the browser',
+            ], 3);
+            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) {
             try {
@@ -290,8 +454,11 @@ export async function initFlow(root, options = {}) {
         // tour install: ask in TTY unless --yes.
         let runInstall = yes;
         if (!yes && io.isTTY) {
-            const answer = await io.ask('Add the pill loader to your app? [Y/n]', 'y');
-            runInstall = !/^n(o)?$/i.test(answer);
+            runInstall =
+                (await choose(io, 'Add the DocuGate pill to your app? (development only)', [
+                    'Yes, add it',
+                    'Skip, I will run docugate tour install later',
+                ])) === 1;
         }
         if (runInstall) {
             installResult = tourInstall(root, { port });

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', 'sidebar', 'api']);
+export const KNOWN_KEYS = new Set(['$schema', 'docsDir', 'title', 'role', 'freshness', 'sidebar', 'api']);

package/dist/tour-init.js

@@ -1,7 +1,8 @@
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { dirname, 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
@@ -75,9 +76,30 @@ 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. */
+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;
+    }
+}
+export function saveBobKey(key) {
+    mkdirSync(dirname(bobKeyPath()), { recursive: true });
+    writeFileSync(bobKeyPath(), JSON.stringify({ key }) + '\n', { mode: 0o600 });
+}
 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/package.json

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