docugate 0.3.1 → 0.4.0

package/README.md

@@ -1,494 +1,496 @@
-# docugate
-
-DocuGate publishes documentation straight from the markdown in your GitHub repositories. This package is its command line, and it does three things:
-
-- **Keeps the docs true.** `docugate sync` reads what changed in your code, works out which pages that made wrong, and opens a pull request with the fix. Nobody has to remember to update the docs. [More](#docs-that-keep-up-with-your-code).
-- **Explains your app.** A walkthrough pill on your running app shows any developer what each element on screen is and where its data comes from. [More](#tours).
-- **Checks the result.** `docugate check` reads your docs and tours the way DocuGate will, so problems show up in CI instead of on the published page.
-
-```sh
-npm i -g docugate
-docugate              # opens DocuGate in your terminal: pick what to do next
-```
-
-Type `docugate` on its own and it opens, the way `claude` does: where your account, docs and space stand, and every next step in a list, with the one worth doing now under Enter. Arrow keys pick; in Git Bash and other terminals without them, type the number.
-
----
-
-## Quick start, step by step
-
-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. Open your project's folder.**
-
-```sh
-cd my-app
-```
-
-Use the root of the repository: the folder with `.git` and `package.json` in
-it. If your frontend and backend are two repositories, do steps 1 to 3 in each.
-
-**2. Install DocuGate in the project.**
-
-```sh
-npm i docugate
-```
-
-Like any other package: everyone who clones the project gets the same version,
-and CI too. (A repository with no `package.json`, like a Go or Python backend,
-can install the command on the computer instead with `npm i -g docugate`, and
-then drop the `npx` from the commands below.)
-
-**3. Set everything up.**
-
-```sh
-npx docugate init
-```
-
-It asks, one at a time:
-
-| 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. |
-| 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. The answer is saved as `freshness`; `docugate sync init` then adds the GitHub Action that does the checking. |
-| 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. |
-
-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
-[Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")   # Windows
-export BOB_API_KEY=<key>                                                # macOS, Linux
-```
-
-Setup writes `docugate.json` and `.docugate/tour/`. Commit both, so the next
-person who clones the repository needs no setup. When setup finishes it starts
-the tour server in the background, so the pill is there the first time you open
-the app (`--no-serve` skips that).
-
-**4. Run your app as usual, and open it.**
-
-```sh
-npm run dev
-```
-
-Setup added a `predev` script, so `npm run dev` starts the DocuGate tour server
-first (one line, "DocuGate tour ready") and then your app. The pill only
-appears while that server runs, which is why it never shows in production.
-
-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`.
-
-**5. Keep the tour true.**
-
-```sh
-npx 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
-npx docugate                 # the menu: pick what to do next
-npx docugate status          # where things stand, and what to do next
-npx docugate sync            # update the docs from what changed in the code
-npx docugate login           # sign in again, or on a new computer
-npx docugate whoami          # who am I signed in as?
-npx docugate tour init       # let IBM Bob write tours for screens that have none
-npx docugate tour install    # add the pill again (--remove takes it out)
-npx docugate tour serve      # start the tour server by hand
-npx docugate logout          # disconnect this computer
-```
-
-**Something not working?**
-
-| You see | Do this |
-| --- | --- |
-| No pill in the app | Start the app with `npm run dev` (it starts the tour server), or run `npx docugate tour serve`, 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. |
-
----
-
-## A developer space
-
-```sh
-docugate developers
-```
-
-One guided run sets up the docs developers read before they build on your API:
-
-1. Signs you in, if you are not.
-2. Finds your OpenAPI file (`openapi.json`, `.yaml`, `swagger.*`) and says how many endpoints it describes.
-3. Writes the first pages, `index.md`, `quickstart.md`, `authentication.md` and `errors.md`, in `docs/developers/`, where they are missing. It never overwrites a file.
-4. Offers to commit and push them, since a space reads GitHub, not your disk.
-5. Creates a public space for them, or uses the one that already reads this repository, and saves it in `docugate.json`.
-
-On Pro it carries on:
-
-6. Claims a subdomain such as `acme.trydocugate.site`, live at once.
-7. Asks where the API console sends requests from: the reader's browser, or through DocuGate with no CORS setup.
-8. Switches on API keys, with a scope per OpenAPI tag to start from, makes the verify secret, offers to put it in `.env` when git ignores that file, and prints the lines your Express, Hono or Fastify backend needs.
-
-Everything it sets stays editable in the space's settings on [trydocugate.site](https://www.trydocugate.site/dashboard).
-
-## Docs that keep up with your code
-
-Documentation goes stale because updating it is a chore nobody owns. `docugate sync` does the chore: it reads what changed in the code, finds the pages those changes made wrong, asks an AI model to correct them, and gives you the edits to review.
-
-```sh
-npx docugate sync --dry-run   # free and instant: which pages are probably out of date
-npx docugate sync             # write the edits into your docs folder
-npx docugate sync --pr        # push them and open a pull request instead
-```
-
-`sync` needs an AI key of your own, in `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (set `DOCUGATE_AI_BASE_URL` to use another OpenAI-compatible service). It talks to the provider directly: nothing goes through DocuGate's servers, and it works without a DocuGate account.
-
-**What it does, step by step**
-
-1. **Reads the changes** from git: the commits and a trimmed diff of each changed file, since the last sync. The first run looks back a day, a week or one commit, depending on `freshness`. `--since 7d`, a branch or a commit overrides it. Documentation, lockfiles, build output, binaries and anything that looks like a secret (`.env`, `*.pem`, files named `secret` or `credentials`) are never read.
-2. **Finds the pages that are affected.** A page counts when it names a changed file, mentions something the change added or removed (a function, a route, an environment variable), or is pinned to that code in `sync.map`. This part is free, and it is all `--dry-run` does.
-3. **Asks the model** for the new text of those pages, and only those. It is told to change what the diff requires and nothing else, to invent nothing, and to treat the code as data rather than instructions.
-4. **Checks the answer before writing it.** An edit is dropped unless it is a markdown page inside your docs folder, within 300 pages, without front matter. After writing, `docugate check` runs again, and an edit that breaks a link is put back as it was.
-5. **Hands it over.** With `--pr` the edits go on one branch, `docugate/sync`, and one pull request that lists every page and why it changed. Each run updates that same pull request rather than opening another. Nothing is ever merged for you, and closing the pull request changes nothing. The sync moves forward only when you merge it.
-
-**Make it automatic**
-
-```sh
-npx docugate sync init
-```
-
-This writes `.github/workflows/docugate-sync.yml`, timed by `freshness` in `docugate.json`:
-
-| `freshness` | When it runs |
-| --- | --- |
-| `push` | On every push to your default branch. |
-| `daily` | Every day. |
-| `weekly` | Every Monday (the default). |
-| `off` | Never. No workflow is written. |
-
-Do two things on GitHub, once: add your AI key as a repository secret named `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY`), and under Settings, Actions, General, tick "Allow GitHub Actions to create and approve pull requests". `sync init` prints both steps. The workflow is pinned to the version that wrote it, so a new release never changes what your CI does by surprise; run `sync init --force` to upgrade it. A sync's own commits never start another sync.
-
-**A heads-up on your own machine**
-
-```sh
-npx docugate sync hook install
-```
-
-After every commit, a git hook runs `sync --dry-run` and, if pages look out of date, says so in one line. It sends nothing, changes nothing and never fails a commit. `sync hook remove` takes it out.
-
-**Settings**, in `docugate.json`:
-
-```json
-{
-  "freshness": "weekly",
-  "sync": {
-    "provider": "anthropic",
-    "model": "claude-sonnet-5-5",
-    "include": ["server/**", "src/**"],
-    "exclude": ["**/*.test.ts"],
-    "map": { "docs/api.md": ["server/routes/**"] },
-    "maxFiles": 10,
-    "digest": false
-  }
-}
-```
-
-| Key | Meaning |
-| --- | --- |
-| `provider` | `anthropic` or `openai`. Defaults to whichever key is set. |
-| `model` | The model to use. |
-| `include` / `exclude` | Path globs for the code worth documenting. `*` stays within a folder, `**` crosses folders. |
-| `map` | Pin a page to the code it documents, when its text never names the files. DocuGate does not read front matter, so this is where that link lives. |
-| `maxFiles` | The most pages one run may change (10). |
-| `digest` | Also write a short "what changed" page, `changes/<date>.md`, for each run. |
-
-`sync` also lists tour stops that no longer match the code. It only reports them: a tour is yours, and DocuGate never edits one.
-
-**When it says no**
-
-| You see | Do this |
-| --- | --- |
-| "No AI key found" | Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` where you run it, or as an Actions secret. |
-| "shallow clone" | In GitHub Actions, set `fetch-depth: 0` on the checkout step. `sync init` already does. |
-| Pushed, but no pull request | Allow Actions to create pull requests (above), or set `GITHUB_TOKEN` when running it by hand. |
-| "Skipped: the changes only touch documentation" | Working as intended. A merged sync, or a docs-only change, never starts a sync. |
-
----
-
-## Moving around
-
-Run `docugate` in a terminal and you get a menu: arrow keys to move, type to search, Enter to run, Esc to leave. It shows where you are (signed in or not, how many pages, how far the docs are behind the code) and puts the step worth taking next under Enter, with a dot beside it. Not connected to DocuGate yet? Connecting your account is that step. When a command finishes, the menu comes back.
-
-- `docugate status` prints the same picture: your account, your docs, the sync (last run, whether the workflow and hook are on, how many commits and pages are behind), your tour, and one line saying what to do next. `--json` is for scripts.
-- `docugate help <command>`, or `docugate <command> --help`, shows one command's options and examples.
-- Mistype and it helps: `docugate chekc` suggests `check`, and an option a command does not have is an error with the nearest real one, not silently ignored.
-- `docugate completion powershell|bash|zsh` prints a completion script.
-- In CI, in a pipe, or with `--no-input`, nothing is ever asked: the menu does not open, the help prints as plain text, and a command that needs an answer fails with what to do. To use your DocuGate account in CI, set `DOCUGATE_TOKEN`.
-
----
-
-## 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 sits in a corner of your app,
-like the Next.js dev indicator. Drag it to any corner. Click it for two things:
-
-- **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 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.
-
----
-
-## 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` | | In a terminal: the menu. Elsewhere: the help. |
-| `docugate status` | `--json` | Where things stand: account, docs, sync and tour, and what to do next. |
-| `docugate sync` | `--dry-run`, `--since <when>`, `--pr`, `--yes`, `--max-files <n>`, `--model <name>`, `--quiet` | Update the docs from what changed in the code. |
-| `docugate sync init` | `--freshness push\|daily\|weekly\|off`, `--force` | Add the GitHub Action that runs sync on a schedule or on every push. |
-| `docugate sync hook install` | | Tell you after each commit which pages the code left behind. |
-| `docugate sync hook remove` | | Remove that hook. |
-| `docugate init` | `--dir`, `--title`, `--role frontend\|backend\|both`, `--yes`, `--no-serve` | Set up this repository for DocuGate (interactive). |
-| `docugate developers` | `--dir`, `--yes` | Set up a developer space: API reference, guides and keys (interactive). |
-| `docugate check` | `--dir`, `--strict` | Check docs and tour files the way DocuGate will read them. |
-| `docugate help [command]` | | Every command, or one command's options and examples. |
-| `docugate completion <shell>` | | Print a completion script for bash, zsh or powershell. |
-| `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), `--background` | 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. Every command also takes
-`--help`, and `--no-input` (which CI implies) to make sure it never stops to
-ask a question: it fails with what to do instead.
-
----
-
-## 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.
-
-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
-
-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"]
-    }
-  }
-}
-```
-
----
-
-## Checking API keys from your backend
-
-If you publish an API's docs on DocuGate Enterprise, the people reading them can generate an API key on the page. Your backend asks DocuGate whether each key is valid, with a secret from your space's settings, so a key you revoke stops on its next request. This package carries that check. It is separate from the command and has no dependencies of its own.
-
-```ts
-import { requireKey } from 'docugate/express' // or 'docugate/hono', 'docugate/fastify'
-
-app.use('/api', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))
-```
-
-The verified key is on `req.docugateKey` (Express and Fastify) or `c.get('docugateKey')` (Hono): who holds it, its scopes, and what is left of its allowance. Anything else, in any framework, can call the check directly:
-
-```ts
-import { verifyKey } from 'docugate/keys'
-
-const verdict = await verifyKey(key, { secret: process.env.DOCUGATE_VERIFY_SECRET! })
-if (!verdict.valid) return deny(verdict.code) // REVOKED, EXPIRED, USAGE_EXCEEDED, ...
-```
-
-`verifyKey` answers for every key, valid or not, and throws a `KeyServiceError` only when it could not get an answer. By default every request asks DocuGate, which is what makes a revoked key stop at once; `cacheSeconds` trades that for speed, and `failOpen` decides what happens when DocuGate cannot be reached (by default, the request is refused). The options, the exact request, and what each result means are in [API keys](https://www.trydocugate.site/docs/api-keys).
-
----
-
-## `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 the docs are checked against the code: `push`, `daily`, `weekly` or `off`. Set by `docugate init` or `docugate sync init`, which writes the GitHub Action to match. |
-| `sync` | Settings for `docugate sync`; see [Docs that keep up with your code](#docs-that-keep-up-with-your-code). The DocuGate site ignores it. |
-| `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`. |
-| `api.spec` | Where the OpenAPI file is, for a repository that does not keep it at `openapi.json` in the root or the docs folder. DocuGate draws an [API reference](https://www.trydocugate.site/docs/api-reference) from it. |
-
----
-
-## Built with IBM Bob
-
-The tour and pill began as DocuGate's entry to the IBM Bob 2.0 hackathon (lablab.ai, September 25 to 27, 2026), and IBM Bob still writes the first tour (`docugate tour init` runs it through Bob Shell, in a Tour Writer mode that may only edit `.docugate/tour/` and never changes a tour file you already have). Demo video: https://youtu.be/mgLUA-0r5MM. Live demo: https://docugate-demo.vercel.app/invoices/inv_1004
-
----
-
-## Licence
-
-MIT
+# docugate
+
+DocuGate publishes documentation straight from the markdown in your GitHub repositories. This package is its command line, and it does three things:
+
+- **Keeps the docs true.** `docugate sync` reads what changed in your code, works out which pages that made wrong, and opens a pull request with the fix. Nobody has to remember to update the docs. [More](#docs-that-keep-up-with-your-code).
+- **Explains your app.** A walkthrough pill on your running app shows any developer what each element on screen is and where its data comes from. [More](#tours).
+- **Checks the result.** `docugate check` reads your docs and tours the way DocuGate will, so problems show up in CI instead of on the published page.
+
+```sh
+npm i -g docugate
+docugate              # opens DocuGate in your terminal: pick what to do next
+```
+
+Type `docugate` on its own and it opens, the way `claude` does: where your account, docs and space stand, and every next step in a list, with the one worth doing now under Enter. Arrow keys pick; in Git Bash and other terminals without them, type the number.
+
+---
+
+## Quick start, step by step
+
+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. Open your project's folder.**
+
+```sh
+cd my-app
+```
+
+Use the root of the repository: the folder with `.git` and `package.json` in
+it. If your frontend and backend are two repositories, do steps 1 to 3 in each.
+
+**2. Install DocuGate in the project.**
+
+```sh
+npm i docugate
+```
+
+Like any other package: everyone who clones the project gets the same version,
+and CI too. (A repository with no `package.json`, like a Go or Python backend,
+can install the command on the computer instead with `npm i -g docugate`, and
+then drop the `npx` from the commands below.)
+
+**3. Set everything up.**
+
+```sh
+npx docugate init
+```
+
+It asks, one at a time:
+
+| 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. |
+| 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. The answer is saved as `freshness`; `docugate sync init` then adds the GitHub Action that does the checking. |
+| 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. |
+
+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
+[Environment]::SetEnvironmentVariable("BOB_API_KEY", "<key>", "User")   # Windows
+export BOB_API_KEY=<key>                                                # macOS, Linux
+```
+
+Setup writes `docugate.json` and `.docugate/tour/`. Commit both, so the next
+person who clones the repository needs no setup. When setup finishes it starts
+the tour server in the background, so the pill is there the first time you open
+the app (`--no-serve` skips that).
+
+**4. Run your app as usual, and open it.**
+
+```sh
+npm run dev
+```
+
+Setup added a `predev` script, so `npm run dev` starts the DocuGate tour server
+first (one line, "DocuGate tour ready") and then your app. The pill only
+appears while that server runs, which is why it never shows in production.
+
+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`.
+
+**5. Keep the tour true.**
+
+```sh
+npx 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
+npx docugate                 # the menu: pick what to do next
+npx docugate status          # where things stand, and what to do next
+npx docugate sync            # update the docs from what changed in the code
+npx docugate login           # sign in again, or on a new computer
+npx docugate whoami          # who am I signed in as?
+npx docugate tour init       # let IBM Bob write tours for screens that have none
+npx docugate tour install    # add the pill again (--remove takes it out)
+npx docugate tour serve      # start the tour server by hand
+npx docugate logout          # disconnect this computer
+```
+
+**Something not working?**
+
+| You see | Do this |
+| --- | --- |
+| No pill in the app | Start the app with `npm run dev` (it starts the tour server), or run `npx docugate tour serve`, 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. |
+
+---
+
+## A developer space
+
+```sh
+docugate developers
+```
+
+One guided run sets up the docs developers read before they build on your API:
+
+1. Signs you in, if you are not.
+2. Finds your OpenAPI file (`openapi.json`, `.yaml`, `swagger.*`) and says how many endpoints it describes.
+3. Writes the first pages, `index.md`, `quickstart.md`, `authentication.md` and `errors.md`, in `docs/developers/`, where they are missing. It never overwrites a file.
+4. Offers to commit and push them, since a space reads GitHub, not your disk.
+5. Creates a public space for them, or uses the one that already reads this repository, and saves it in `docugate.json`.
+
+On Pro it carries on:
+
+6. Claims a subdomain such as `acme.trydocugate.site`, live at once.
+7. Asks where the API console sends requests from: the reader's browser, or through DocuGate with no CORS setup.
+8. Switches on API keys, with a scope per OpenAPI tag to start from, makes the verify secret, offers to put it in `.env` when git ignores that file, and prints the lines your Express, Hono or Fastify backend needs.
+
+Everything it sets stays editable in the space's settings on [trydocugate.site](https://www.trydocugate.site/dashboard).
+
+## Docs that keep up with your code
+
+Documentation goes stale because updating it is a chore nobody owns. `docugate sync` does the chore: it reads what changed in the code, finds the pages those changes made wrong, asks an AI model to correct them, and gives you the edits to review.
+
+```sh
+npx docugate sync --dry-run   # free and instant: which pages are probably out of date
+npx docugate sync             # write the edits into your docs folder
+npx docugate sync --pr        # push them and open a pull request instead
+```
+
+`sync` needs an AI key of your own, in `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` (set `DOCUGATE_AI_BASE_URL` to use another OpenAI-compatible service). It talks to the provider directly: nothing goes through DocuGate's servers, and it works without a DocuGate account.
+
+**What it does, step by step**
+
+1. **Reads the changes** from git: the commits and a trimmed diff of each changed file, since the last sync. The first run looks back a day, a week or one commit, depending on `freshness`. `--since 7d`, a branch or a commit overrides it. Documentation, lockfiles, build output, binaries and anything that looks like a secret (`.env`, `*.pem`, files named `secret` or `credentials`) are never read.
+2. **Finds the pages that are affected.** A page counts when it names a changed file, mentions something the change added or removed (a function, a route, an environment variable), or is pinned to that code in `sync.map`. This part is free, and it is all `--dry-run` does.
+3. **Asks the model** for the new text of those pages, and only those. It is told to change what the diff requires and nothing else, to invent nothing, and to treat the code as data rather than instructions.
+4. **Checks the answer before writing it.** An edit is dropped unless it is a markdown page inside your docs folder, within 300 pages, without front matter. After writing, `docugate check` runs again, and an edit that breaks a link is put back as it was.
+5. **Hands it over.** With `--pr` the edits go on one branch, `docugate/sync`, and one pull request that lists every page and why it changed. Each run updates that same pull request rather than opening another. Nothing is ever merged for you, and closing the pull request changes nothing. The sync moves forward only when you merge it.
+
+**Make it automatic**
+
+```sh
+npx docugate sync init
+```
+
+This writes `.github/workflows/docugate-sync.yml`, timed by `freshness` in `docugate.json`:
+
+| `freshness` | When it runs |
+| --- | --- |
+| `push` | On every push to your default branch. |
+| `daily` | Every day. |
+| `weekly` | Every Monday (the default). |
+| `off` | Never. No workflow is written. |
+
+Do two things on GitHub, once: add your AI key as a repository secret named `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY`), and under Settings, Actions, General, tick "Allow GitHub Actions to create and approve pull requests". `sync init` prints both steps. The workflow is pinned to the version that wrote it, so a new release never changes what your CI does by surprise; run `sync init --force` to upgrade it. A sync's own commits never start another sync.
+
+**A heads-up on your own machine**
+
+```sh
+npx docugate sync hook install
+```
+
+After every commit, a git hook runs `sync --dry-run` and, if pages look out of date, says so in one line. It sends nothing, changes nothing and never fails a commit. `sync hook remove` takes it out.
+
+**Settings**, in `docugate.json`:
+
+```json
+{
+  "freshness": "weekly",
+  "sync": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-5-5",
+    "include": ["server/**", "src/**"],
+    "exclude": ["**/*.test.ts"],
+    "map": { "docs/api.md": ["server/routes/**"] },
+    "maxFiles": 10,
+    "digest": false
+  }
+}
+```
+
+| Key | Meaning |
+| --- | --- |
+| `provider` | `anthropic` or `openai`. Defaults to whichever key is set. |
+| `model` | The model to use. |
+| `include` / `exclude` | Path globs for the code worth documenting. `*` stays within a folder, `**` crosses folders. |
+| `map` | Pin a page to the code it documents, when its text never names the files. DocuGate does not read front matter, so this is where that link lives. |
+| `maxFiles` | The most pages one run may change (10). |
+| `digest` | Also write a short "what changed" page, `changes/<date>.md`, for each run. |
+
+`sync` also lists tour stops that no longer match the code. It only reports them: a tour is yours, and DocuGate never edits one.
+
+**When it says no**
+
+| You see | Do this |
+| --- | --- |
+| "No AI key found" | Set `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` where you run it, or as an Actions secret. |
+| "shallow clone" | In GitHub Actions, set `fetch-depth: 0` on the checkout step. `sync init` already does. |
+| Pushed, but no pull request | Allow Actions to create pull requests (above), or set `GITHUB_TOKEN` when running it by hand. |
+| "Skipped: the changes only touch documentation" | Working as intended. A merged sync, or a docs-only change, never starts a sync. |
+
+---
+
+## Moving around
+
+Run `docugate` in a terminal and you get a menu: arrow keys to move, type to search, Enter to run, Esc to leave. It shows where you are (signed in or not, how many pages, how far the docs are behind the code) and puts the step worth taking next under Enter, with a dot beside it. Not connected to DocuGate yet? Connecting your account is that step. When a command finishes, the menu comes back.
+
+- `docugate status` prints the same picture: your account, your docs, the sync (last run, whether the workflow and hook are on, how many commits and pages are behind), your tour, and one line saying what to do next. `--json` is for scripts.
+- `docugate help <command>`, or `docugate <command> --help`, shows one command's options and examples.
+- Mistype and it helps: `docugate chekc` suggests `check`, and an option a command does not have is an error with the nearest real one, not silently ignored.
+- `docugate completion powershell|bash|zsh` prints a completion script.
+- In CI, in a pipe, or with `--no-input`, nothing is ever asked: the menu does not open, the help prints as plain text, and a command that needs an answer fails with what to do. To use your DocuGate account in CI, set `DOCUGATE_TOKEN`.
+
+---
+
+## 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 sits in a corner of your app,
+like the Next.js dev indicator. Drag it to any corner. Click it for two things:
+
+- **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 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.
+
+---
+
+## 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` | | In a terminal: the menu. Elsewhere: the help. |
+| `docugate status` | `--json` | Where things stand: account, docs, sync and tour, and what to do next. |
+| `docugate sync` | `--dry-run`, `--since <when>`, `--pr`, `--yes`, `--max-files <n>`, `--model <name>`, `--quiet` | Update the docs from what changed in the code. |
+| `docugate sync init` | `--freshness push\|daily\|weekly\|off`, `--force` | Add the GitHub Action that runs sync on a schedule or on every push. |
+| `docugate sync hook install` | | Tell you after each commit which pages the code left behind. |
+| `docugate sync hook remove` | | Remove that hook. |
+| `docugate init` | `--dir`, `--title`, `--role frontend\|backend\|both`, `--yes`, `--no-serve` | Set up this repository for DocuGate (interactive). |
+| `docugate developers` | `--dir`, `--yes` | Set up a developer space: API reference, guides and keys (interactive). |
+| `docugate check` | `--dir`, `--strict` | Check docs and tour files the way DocuGate will read them. |
+| `docugate help [command]` | | Every command, or one command's options and examples. |
+| `docugate completion <shell>` | | Print a completion script for bash, zsh or powershell. |
+| `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 connect` | `--space`, `--frequency`, `--type`, `--backend-dir`, `--no-audit`, `--yes` | Connect this project to your account, to run it from the dashboard. |
+| `docugate audit` | `--fail-on`, `--json` | Check this project’s packages for known vulnerabilities. |
+| `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), `--background` | 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. Every command also takes
+`--help`, and `--no-input` (which CI implies) to make sure it never stops to
+ask a question: it fails with what to do instead.
+
+---
+
+## 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.
+
+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
+
+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"]
+    }
+  }
+}
+```
+
+---
+
+## Checking API keys from your backend
+
+If you publish an API's docs on DocuGate Enterprise, the people reading them can generate an API key on the page. Your backend asks DocuGate whether each key is valid, with a secret from your space's settings, so a key you revoke stops on its next request. This package carries that check. It is separate from the command and has no dependencies of its own.
+
+```ts
+import { requireKey } from 'docugate/express' // or 'docugate/hono', 'docugate/fastify'
+
+app.use('/api', requireKey({ secret: process.env.DOCUGATE_VERIFY_SECRET! }))
+```
+
+The verified key is on `req.docugateKey` (Express and Fastify) or `c.get('docugateKey')` (Hono): who holds it, its scopes, and what is left of its allowance. Anything else, in any framework, can call the check directly:
+
+```ts
+import { verifyKey } from 'docugate/keys'
+
+const verdict = await verifyKey(key, { secret: process.env.DOCUGATE_VERIFY_SECRET! })
+if (!verdict.valid) return deny(verdict.code) // REVOKED, EXPIRED, USAGE_EXCEEDED, ...
+```
+
+`verifyKey` answers for every key, valid or not, and throws a `KeyServiceError` only when it could not get an answer. By default every request asks DocuGate, which is what makes a revoked key stop at once; `cacheSeconds` trades that for speed, and `failOpen` decides what happens when DocuGate cannot be reached (by default, the request is refused). The options, the exact request, and what each result means are in [API keys](https://www.trydocugate.site/docs/api-keys).
+
+---
+
+## `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 the docs are checked against the code: `push`, `daily`, `weekly` or `off`. Set by `docugate init` or `docugate sync init`, which writes the GitHub Action to match. |
+| `sync` | Settings for `docugate sync`; see [Docs that keep up with your code](#docs-that-keep-up-with-your-code). The DocuGate site ignores it. |
+| `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`. |
+| `api.spec` | Where the OpenAPI file is, for a repository that does not keep it at `openapi.json` in the root or the docs folder. DocuGate draws an [API reference](https://www.trydocugate.site/docs/api-reference) from it. |
+
+---
+
+## Built with IBM Bob
+
+The tour and pill began as DocuGate's entry to the IBM Bob 2.0 hackathon (lablab.ai, September 25 to 27, 2026), and IBM Bob still writes the first tour (`docugate tour init` runs it through Bob Shell, in a Tour Writer mode that may only edit `.docugate/tour/` and never changes a tour file you already have). Demo video: https://youtu.be/mgLUA-0r5MM. Live demo: https://docugate-demo.vercel.app/invoices/inv_1004
+
+---
+
+## Licence
+
+MIT