Document the public Gapwise CLI

README.md

@@ -50,7 +50,7 @@ The docs follow released first-party contracts rather than inventing parallel be
 - [`ios`](https://github.com/GapwiseHQ/ios) owns the native iOS implementation;
 - [`ai`](https://github.com/GapwiseHQ/ai) owns live MCP/OAuth delegation behavior;
 - [`data`](https://github.com/GapwiseHQ/data) owns canonical public campus facts and provenance for supported universities;
-- [`cli`](https://github.com/GapwiseHQ/cli) scaffolds new university adapters and campus datasets;
+- [`cli`](https://github.com/GapwiseHQ/cli) discovers public campus data and scaffolds university integrations ([guide](https://docs.gapwise.ca/cli/));
 - [`status`](https://github.com/GapwiseHQ/status) owns operational state and incident communication.
 
 ---

astro.config.mjs

@@ -119,6 +119,10 @@ export default defineConfig({
             { label: "Python", slug: "sdk/python" },
           ],
         },
+        {
+          label: "CLI",
+          items: [{ label: "Gapwise CLI", slug: "cli" }],
+        },
         {
           label: "API",
           items: [

src/content/docs/cli.md

@@ -0,0 +1,65 @@
+---
+title: Gapwise CLI
+description: Install the official Gapwise command-line tool for multi-university campus discovery, public API queries, and university integration scaffolding.
+---
+
+The [Gapwise CLI](https://github.com/GapwiseHQ/cli) is an open-source command-line interface for developers and campus data contributors. It queries the [public API](/api/) for university and campus discovery, buildings, residences, places, and routing. Its maintainer commands scaffold and validate integrations in sibling `gapwise` and `data` checkouts. It does not access a student's private timetable or account.
+
+## Install and maintain
+
+Use Node.js **22 or newer**. The intended canonical npm identity is [`@gapwise/cli`](https://www.npmjs.com/package/@gapwise/cli). The initial npm publication is pending owner authentication; the public GitHub installation is available now:
+
+```sh
+npm install -g github:GapwiseHQ/cli
+gapwise --version
+gapwise --help
+```
+
+Once the registry release is verified, install or upgrade with `npm install -g @gapwise/cli`. To upgrade the GitHub installation, rerun `npm install -g github:GapwiseHQ/cli`. Uninstall with `npm uninstall -g @gapwise/cli`. The [CLI repository](https://github.com/GapwiseHQ/cli) has the MIT license, tests, release workflow, and source history.
+
+## Discover universities and campuses
+
+```sh
+gapwise universities
+gapwise campuses --university uoft
+gapwise campuses --university carleton
+gapwise campuses --university york
+```
+
+Gapwise currently supports 11 universities and 13 campus models. Discovery shows canonical IDs, names, and routing availability. Public campus queries require `--university ID`; otherwise the API's historical U of T default could silently give the wrong edition's data. `--campus` selects one of that university's campus IDs; omitting it uses that university's default campus.
+
+## Query public campus facts
+
+```sh
+gapwise buildings --university carleton --query library
+gapwise residences --university york --limit 10
+gapwise buildings --university tmu --category academic
+gapwise places --university uoft --campus utm --kind study
+gapwise route --university carleton --from TB --to ML
+```
+
+The CLI reports empty results when a campus has no matching public records. Routing is refused when the selected campus is not routable; route results retain API warnings and verification status. Place availability and route coverage are source dependent.
+
+For scripts, add `--json` to print the full `{ data, meta }` response to stdout. Errors go to stderr and set a nonzero exit code:
+
+```sh
+gapwise buildings --university carleton --query library --json
+```
+
+The CLI is intentionally a thin public API client. For pagination, advanced queries, application integrations, and all public v1 operations, use the [API reference](/api/) or [official SDKs](/sdk/javascript/).
+
+## University integration tooling
+
+Clone [cli](https://github.com/GapwiseHQ/cli), [gapwise](https://github.com/GapwiseHQ/gapwise), and [data](https://github.com/GapwiseHQ/data) as sibling repositories. Pass their parent directory with `--workspace PATH` or `GAPWISE_WORKSPACE` if they are elsewhere. App validation and development also require the runtimes used by those repositories, including Bun.
+
+```sh
+gapwise university create example-university --name "Example University" --dry-run
+gapwise university validate carleton
+gapwise university test carleton
+gapwise university dev carleton
+gapwise data validate carleton
+```
+
+The scaffold starts inactive with empty campus data and a deliberately unimplemented timetable adapter. Review source rights and evidence before activation. See [Add a university](/guides/add-university/) for the full workflow.
+
+Gapwise is an independent project and is not affiliated with or endorsed by the supported universities.

src/content/docs/guides/add-university.md

@@ -12,11 +12,13 @@ Gapwise currently supports 11 universities across Canada: University of Toronto
 Check out `gapwise`, `data`, and `cli` as sibling repositories. From `cli`:
 
 ```sh
-node bin/gapwise.mjs university create example-university --dry-run
-node bin/gapwise.mjs university create tmu \
-  --name "Toronto Metropolitan University" --short-name TMU
+gapwise university create example-university --dry-run
+gapwise university create example-university \
+  --name "Example University" --short-name Example
 ```
 
+See the [CLI installation and usage guide](/cli/) before running these commands. The `tmu` ID is already registered and cannot be created again.
+
 The command adds one entry to `gapwise/universities.json`, a timetable adapter and failing fixture test, and empty campus/academic snapshots. It creates no product screen or style copy. The new entry has `status: scaffold`, routing disabled, and no invented buildings, entrances, or paths.
 
 ## Add evidence and ingestion
@@ -30,10 +32,10 @@ The command adds one entry to `gapwise/universities.json`, a timetable adapter a
 ## Verify and deploy
 
 ```sh
-node cli/bin/gapwise.mjs data validate tmu
-node cli/bin/gapwise.mjs university validate tmu
-node cli/bin/gapwise.mjs university test tmu
-node cli/bin/gapwise.mjs university dev tmu
+gapwise data validate example-university
+gapwise university validate example-university
+gapwise university test example-university
+gapwise university dev example-university
 ```
 
 Run the `gapwise` typecheck, lint, unit tests, production build, and browser tests. Check desktop and mobile map selection, timetable import, Today, gap calculations, and route states. The local development URL uses `?university=tmu`; production host resolution uses the manifest. Configure DNS and the hosting provider for `tmu.gapwise.ca`, then verify the preview and live host before announcing support.

src/content/docs/index.mdx

@@ -66,6 +66,7 @@ Pick the interface that matches the semantics and trust boundary your project ac
 | Documentation | `https://docs.gapwise.ca` | Human-readable contracts, guides, architecture, and security |
 | Public API | `https://api.gapwise.ca/v1` | Stable deterministic campus intelligence |
 | OpenAPI | `https://api.gapwise.ca/openapi.json` | Machine-readable API contract |
+| CLI | `https://docs.gapwise.ca/cli/` | Campus discovery and university integration tooling |
 | Gapwise Data | `https://data.gapwise.ca` | Canonical raw campus data, schemas, provenance, and downloads |
 | Raw dataset manifest | `https://data.gapwise.ca/datasets/utm/latest/manifest.json` | Integrity-checkable raw artifact discovery |
 | AI / MCP | `https://ai.gapwise.ca/api/mcp` | Permissioned assistant integration |
@@ -83,6 +84,7 @@ The canonical public API exposes versioned buildings and places across 11 suppor
 - JavaScript / TypeScript (JSR): `jsr:@gapwise/sdk@0.1.2`
 - JavaScript / TypeScript (GitHub Packages mirror): `@gapwisehq/sdk` (historical 0.1.1 under `@gapwise-for-uoft/sdk`)
 - Python: `python -m pip install gapwise==0.1.1`
+- CLI: [installation and commands](/cli/) · [GapwiseHQ/cli](https://github.com/GapwiseHQ/cli)
 
 Successful responses use `{ data, meta }`; errors use a nested structured error envelope with a request ID. Both official SDK implementations target the same v1 contract. `@gapwise/sdk@0.1.2` is published on npm and JSR, the same JavaScript SDK is mirrored publicly on GitHub Packages as `@gapwisehq/sdk` (historical 0.1.1 under `@gapwise-for-uoft/sdk`), and `gapwise==0.1.1` is published on PyPI through Trusted Publishing and has been independently clean-installed against the production API. The GitHub Packages mirror uses the organization-scoped package name required by GitHub and does not replace the canonical `@gapwise/sdk` identity.
 

src/content/docs/platform/ecosystem.md

@@ -16,7 +16,7 @@ All canonical repositories are owned by the **Gapwise** GitHub organization at `
 | `GapwiseHQ/ios` | native iOS UX, device integration, secure mobile persistence, and iOS distribution |
 | `GapwiseHQ/ai` | OAuth/MCP delegation, permission checks, minimized delegated snapshots, and bounded AI actions |
 | `GapwiseHQ/data` | campus-data provenance, evidence, schemas, attribution, transformations, and reuse guidance |
-| `GapwiseHQ/cli` | repeatable university scaffolding and validation commands |
+| [`GapwiseHQ/cli`](https://github.com/GapwiseHQ/cli) | Public campus discovery and queries, plus repeatable university scaffolding and validation ([guide](/cli/)) |
 | `GapwiseHQ/docs` | canonical public documentation of released first-party contracts |
 | `GapwiseHQ/status` | independently deployed service health and incident communication |