docs: the docs site and schemars-docgen are documented as part of the komorebi repository

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

crates/schemars-docgen/README.md

@@ -0,0 +1,23 @@
+# schemars-docgen
+
+Writes the reference pages of the docs site (`starlight/`) from a JSON Schema made by `schemars`: one MDX page with
+every type, property, default and enum variant of `schemas/<platform>/schema.json` or `schema.bar.json`, with links
+between the types.
+
+It is a development tool: no release ships it, and it is not a default member of the workspace, so a bare
+`cargo build` leaves it out. Run it from the tree:
+
+```sh
+just docgen    # on Windows or macOS: the schema pages, the command pages and the komorebic page, into starlight/
+```
+
+or by hand, for one schema:
+
+```sh
+cargo run -p schemars-docgen -- schemas/macos/schema.json --output page.mdx --title "komorebi.json" --description "..."
+```
+
+`ENUMS.md` is the analysis of how `schemars` writes each shape of Rust enum into a schema, which is what the tool
+turns back into text.
+
+`nix build .#schemars-docgen` builds it, and `nix build .#checkSets.docgen-lint .#checkSets.docgen-test` check it.

docs/dev/ARCHITECTURE-UNIFIED.md

@@ -24,7 +24,7 @@ The root `Cargo.toml` is the only workspace. One rule says where a member lives:
   the `komorebi` binary;
 - every **library** and every **development tool** lives under `crates/<package name>/`: the daemon
   libraries of the three platforms, the shared crates, the end-to-end guests (`crates/komorebi-e2e-agent`,
-  `crates/komorebi-testwin`) and `crates/schemars-nixgen`.
+  `crates/komorebi-testwin`), `crates/schemars-nixgen` and `crates/schemars-docgen`.
 
 The platform-specific parts are:
 
@@ -36,7 +36,8 @@ The platform-specific parts are:
 
 Shared: `crates/` (the libraries; including `crates/komorebi-version`, the version string of the Linux and macOS
 binaries), `schemas/{windows,linux,macos}/` (the generated JSON schemas), one `deny.toml`, `rustfmt.toml`,
-`rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile` at the root. The old repositories'
+`rust-toolchain.toml`, `.gitignore`, `LICENSE.md` and `justfile` at the root; `starlight/` (the docs site, an Astro
+Starlight project whose reference pages `just docgen` writes with `crates/schemars-docgen`). The old repositories'
 workflows, dependabot files, the Homebrew formula template and the macOS docs-site files are kept, inert, in
 `docs/dev/old-ci/{linux,macos}/` for the CI and release plan. There is no `komorebi-for-kde/` or
 `komorebi-for-mac/` any more except the two flakes that `flake-one` is replacing.

docs/dev/CUTOVER-PLAN.md

@@ -359,7 +359,7 @@ from `master` see the new tree (1.4). **Release:** a revision on `master` that s
 | Linux (KDE) | zip of `komorebi`, `komorebic` for x86_64 and aarch64 (patchelf'ed to the system glibc loader, as the old `build` job did), `schema.json`; the **NixOS module** and overlay through the flake; no tarball existed | nix (native `komorebi`, `komorebic`), `ubuntu-24.04` and `ubuntu-24.04-arm` | `komorebi-<ver>-x86_64-unknown-linux-gnu.zip` |
 | macOS aarch64 | zip of `komorebi`, `komorebic`, `komorebi-bar` (nix `result/bin/*`), `checksums.txt`, Homebrew formula, the nix-darwin module through the flake | nix on a Mac (native `komorebi`, `komorebic`, `komorebi-bar`) | `komorebi-<ver>-aarch64-apple-darwin.zip` (no leading `v`: the old release.yaml included it, `komorebi-v0.1.1-...`; choose the Windows form) |
 | Schemas | `schemas/{windows,linux,macos}/schema*.json` attached to the release and published to the schema host | `just schemapub` (Cloudflare Pages `komorebi`, copies `schemas/<platform>/`) | per-platform files in the repository (decided); the published names are the open part of R5 |
-| Docs | **Starlight for all three platforms** (owner, R3); `gh-pages` (MkDocs, `mkdocs gh-deploy`: the last commit on `gh-pages` is "Deployed 8f982e45 with MkDocs version 1.6.1", i.e. a manual deploy) is deprecated: steps in 4.9. The Starlight reference by `just docgen starlight <repo>` | by hand | root `mkdocs.yml` keeps `exclude_docs` `/linux/`, `/macos/`, `/dev/` (commit `4eae178f`) only while MkDocs still builds anything (4.9) |
+| Docs | **Starlight for all three platforms** (owner, R3); `gh-pages` (MkDocs, `mkdocs gh-deploy`: the last commit on `gh-pages` is "Deployed 8f982e45 with MkDocs version 1.6.1", i.e. a manual deploy) is deprecated: steps in 4.9. The Starlight reference by `just docgen` (into `starlight/`) | by hand | root `mkdocs.yml` keeps `exclude_docs` `/linux/`, `/macos/`, `/dev/` (commit `4eae178f`) only while MkDocs still builds anything (4.9) |
 
 `crates.io`: no crate is published today as far as the repository says; do not start with 0.2.0.
 
@@ -395,7 +395,7 @@ What must change: (a) **one `nightly` release for the whole repository**: the Wi
 
 ### 4.9 Retiring the `gh-pages` site (R3: Starlight for all docs; gh-pages deprecated)
 
-Facts: Pages serves branch `gh-pages` at `https://lgug2z.github.io/komorebi/` (`gh api repos/LGUG2Z/komorebi/pages`); the branch is a manual `mkdocs gh-deploy` result; the old site is linked from `README.md`, `komorebic/src/windows.rs` and `komorebic/src/macos/mod.rs` (help text), `.github/ISSUE_TEMPLATE/config.yml` and `bug_report.yml`, and from every installed 0.1.x binary's help. Where the guide pages (installation, usage, common-workflows) are the source of truth after the move, in this repository's `docs/` or in the `komorebi-starlight` repository: **(unknown)**; `just docgen starlight` only generates the CLI pages and schema reference pages into Starlight.
+Facts: Pages serves branch `gh-pages` at `https://lgug2z.github.io/komorebi/` (`gh api repos/LGUG2Z/komorebi/pages`); the branch is a manual `mkdocs gh-deploy` result; the old site is linked from `README.md`, `komorebic/src/windows.rs` and `komorebic/src/macos/mod.rs` (help text), `.github/ISSUE_TEMPLATE/config.yml` and `bug_report.yml`, and from every installed 0.1.x binary's help. Where the guide pages (installation, usage, common-workflows) are the source of truth after the move, in this repository's `docs/` or in the Starlight site: **(unknown)**; the site is `starlight/` in this repository now (the `komorebi-starlight` history is merged in), and `just docgen` only generates the CLI pages and schema reference pages into it.
 Steps (owner): 1. Starlight has the guides of all three platforms (Windows from `docs/`, Linux from `docs/linux/`, macOS from `docs/macos/`) and its build passes. 2. Retarget the links above (and the `$schema`/docs links of 2.3 class F) to the Starlight address. 3. Replace the `gh-pages` content by a one-page redirect to Starlight and leave it for a period the owner chooses (old binaries and bookmarks still point to it), then disable Pages in the settings, then delete the branch last (back it up as a tag first; deleting is the only irreversible part). 4. **`mkdocs.yml` and the Windows docs source:** while MkDocs builds anything, the root `mkdocs.yml` keeps `exclude_docs` for `/linux/`, `/macos/` and `/dev/` (commit `4eae178f`) so a MkDocs build still excludes the other platforms' pages; when the last MkDocs build is gone, delete `mkdocs.yml`, `check_schema_docs.py` if it only serves it (check first), and decide whether the Windows Markdown under `docs/` stays as in-repo documentation (recommended: keep it, it is what `komorebic` and README link to and what Starlight can import) or moves wholly into Starlight.
 
 ## 5. Sequencing and gates

docs/dev/build-and-test.md

@@ -180,6 +180,22 @@ Nix, on a Mac: the `macos-*` checks (`macos-{clippy,fmt,toml-fmt,deny,nextest}`,
 `komorebi-bar` of `aarch64-darwin`. From Linux they can be evaluated only (`nix flake check --no-build
 --all-systems`, `nix eval`), which proves nothing builds.
 
+## The docs site (`starlight/`)
+
+The site is an Astro Starlight project, with the pages of Windows and macOS. The guides are written by hand in
+`starlight/src/content/docs/`; the reference is generated, and `just docgen` on Windows or macOS writes it in its
+final form into the same directory (`komorebic-<platform>.mdx`, `komorebi-<platform>.mdx`, `bar-<platform>.mdx`, and
+the page of every command in `starlight/src/data/cli/<platform>/`). Run it again after a change of a command, of its
+help or of `schemas/<platform>/`; it needs `node` (in the dev shell) and builds `komorebic` and `schemars-docgen`.
+
+```sh
+just docgen                          # the reference pages of this platform
+cd starlight && npm ci && npm run dev    # the site on localhost; `npm run build` makes dist/
+```
+
+`ci / starlight` runs `npm ci` and `npm run build` when a file of `starlight/` changes. `nix build
+.#checkSets.docgen-lint .#checkSets.docgen-test` checks the tool.
+
 ## 4. Windows e2e (QEMU guest)
 
 Full text: `e2e/platforms/qemu_windows/README.md` (building the golden image, every variable). Short form:

starlight/README.md

@@ -1,4 +1,15 @@
-# komorebi-starlight
+# starlight
 
-Experimental unified documentation site for komorebi for Windows and macOS built
-with Starlight.
+The documentation site of komorebi, for Windows and macOS, built with [Starlight](https://starlight.astro.build).
+
+```sh
+npm ci
+npm run dev      # the site on localhost, after generating the komorebic pages
+npm run build    # dist/, which `wrangler.jsonc` deploys
+```
+
+The guides are written by hand in `src/content/docs/`. The reference pages (`src/content/docs/reference/` and
+`src/data/cli/`) are generated: run `just docgen` from the root of the repository on Windows or macOS after a change
+of a command or of a schema, and commit what it writes. It writes the page of the platform it runs on, so the
+pages of the other one stay as they are. `komorebic-<platform>.mdx` is made by `scripts/generate-cli-reference.cjs`
+from the pages of the commands and is not committed (`npm run dev` and `npm run build` make it too).