docmind-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# docmind-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Check and preview your DocMind documentation **locally, before you push** — the
+same checks Publish runs, against your working tree. No login, no token.
+
+```bash
+npx docmind-cli check      # run once, nothing installed
+npx docmind-cli preview
+```
+
+Or install it once and use the `docmind` command:
+
+```bash
+npm install -g docmind-cli
+docmind check
+docmind preview
+```
+
+Needs Node.js 20 or later.
+
+Run it from your docs repository. It finds `navigation.yaml` (repo root,
+`docs/`, or two levels down), builds the whole site in memory exactly the way
+Publish does, and reports every problem with its file and line:
+
+```
+  docs/guides/setup/broken.md
+    ✕ :5    <NotAComponent> is not a DocMind component and will render as literal text. [unknown_component]
+    ✕ :9    <Card> is never closed. Add </Card>. [unclosed_component]
+
+  docs/guides/intro.md
+    ! :6    Link "nowhere.md" matches no page in this project. … [unknown_page]
+
+──────────────────────────────────────────────────────────────────────────────
+
+  ✕ Status: 2 errors, 6 warnings — Publish would be blocked
+  • Pages: 3 · API specs: 1 · Assets: 1
+  • Checked in 40ms
+```
+
+**Errors** (✕) are what would make Publish fail. **Warnings** (!) still publish.
+
+## Preview
+
+```bash
+npx docmind-cli preview --project acme
+```
+
+Open `http://localhost:4000` (the next free port if 4000 is taken) and it takes
+you to the docs at `/<project>/docs`. Every save rebuilds the site and the
+browser reloads by itself.
+
+It looks like your live docs because it **is** the live docs portal: the same
+components (top bar, Tabs, sidebar, page layout, "On this page", prev/next,
+footer, the 3-column API Reference with code samples) and the same stylesheet,
+fed from your checkout instead of a published site. The problems panel and the
+terminal show the same errors and warnings as `docmind check`.
+
+- **Search:** the search box and ⌘K work, over every page and API operation in
+  your checkout. Ranking uses the live site's scoring, but can differ slightly
+  (the live site also matches word stems and typos).
+- **API Reference:** overview, tags and operations, cURL / JavaScript /
+  TypeScript / Python / Java / Go samples, spec downloads, and **Try It** — sent
+  through the preview, so APIs on `localhost` work too.
+- **Role simulation:** pick a role in "View as" (bottom right), add
+  `?as=reader-client` to any URL, or start with `--role reader-client`.
+  Navigation, pages and search hide what that role cannot see. The list holds
+  the four roles every project has — Admin, Editor, Reader (Organisation),
+  Reader (Client) — then every role your `navigation.yaml` restricts to and any
+  in `docmind.yaml` `roles:`. `?as=` goes back to everything.
+- **Branding:** with `--project <slug>` and your DocMind URL (`--server`,
+  `DOCMIND_SERVER`, or `server:` in `docmind.yaml`) the preview fetches the
+  project's public theme — colours, logo, font. It is cached in
+  `~/.docmind/themes/`, and the default theme is used when neither is
+  available. No login is involved.
+- **Local only:** it listens on `127.0.0.1` and serves files from your
+  checkout; nothing is uploaded anywhere.
+- **Not in the preview** (they need your DocMind server and a login):
+  Discussion, "Was this helpful?" results (the buttons work but nothing is
+  saved), notifications, the account menu, Ask AI, and author / "Updated" dates.
+  A spec's custom overview settings (e.g. which code-sample languages to show)
+  live on the server, so the preview shows the defaults.
+
+## Options
+
+| | |
+|---|---|
+| `docmind check [dir]` | Check the repository at `dir` (default: current directory) |
+| `--docs-dir <path>` | The folder holding `navigation.yaml`, when detection guesses wrong |
+| `--errors-only` | Hide warnings |
+| `--format json` | Machine-readable output |
+| `docmind preview [dir]` | Serve the site locally with live reload |
+| `--port <n>` | Port to try first (default `4000`; `0` = any free port) |
+| `--role <role>` | Preview as this role |
+| `--project <slug>` / `--server <url>` | Use the project's branding |
+| `--no-color` | Plain output (also `NO_COLOR=1`) |
+
+Exit codes: `0` would publish · `1` Publish would be blocked · `2` command error.
+Use it in CI to stop a broken page reaching the publishing branch.
+
+## docmind.yaml (optional)
+
+```yaml
+docsDir: docs                       # where navigation.yaml lives
+roles: [partner, reader-organisation] # custom roles your navigation.yaml uses
+project: acme                       # preview: whose branding to use
+server: https://docs.example.com    # preview: your DocMind URL
+```
+
+## What it cannot check locally
+
+It has no access to your project's database, so two things are taken on trust
+and checked for real when you publish:
+
+- **Custom roles.** `admin`, `editor`, `reader-organisation`, `reader-client`
+  and `*` are known. Any other
+  role in `roles:` is a warning unless listed in `docmind.yaml`.
+- **`id:` values.** An entry's `id:` is assumed to name a row the project has.
+
+Entries **without** an `id:` (a page you just added) are handled the way
+Publish handles them: provisioned if the file exists, refused — and reported —
+if it does not. `docmind check` never writes to your files.