@zebradil/docs-kit 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 German Lashevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,137 @@
-# Temporary Holding Version
+# docs-kit
 
-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.
+Shared kit for generating browsable documentation and a landing page for small OSS projects.
+
+- One content contract (`docs/site.yaml` + Diátaxis page tree) across all projects.
+- One layout, swappable designs (theme = CSS tokens).
+- Reference pages generated from code (CLI `--help`, config schema), never handwritten.
+- Reusable GitHub Actions workflow: generate, build, deploy to GitHub Pages.
+- Agent skills (Claude Code plugin): [`docs-audit`](skills/docs-audit/SKILL.md), [`docs-bootstrap`](skills/docs-bootstrap/SKILL.md), [`docs-write`](skills/docs-write/SKILL.md).
+
+## Claude Code plugin
+
+This repository is a Claude Code plugin marketplace with one plugin, `docs-kit`, holding the three skills. In a Claude Code session:
+
+```text
+/plugin marketplace add Zebradil/docs-kit
+/plugin install docs-kit@docs-kit
+```
+
+The shell equivalents are `claude plugin marketplace add Zebradil/docs-kit` and `claude plugin install docs-kit@docs-kit`. The skills run as `/docs-kit:docs-audit` and so on, or when a request matches their description.
+
+Recommended flow in a consuming project:
+
+1. `docs-audit` writes the gap report `docs/.audit.md`; it never edits docs.
+2. Review the report: reorder, drop, or fix gaps before any prose lands.
+3. `docs-bootstrap` sets up `docs/`, `site.yaml`, the workflow, and Renovate, then opens a PR.
+4. `docs-write` closes one gap per run with one PR. Repeat, re-auditing when the code moves.
+
+The plugin carries no `version`, so its version is the commit it was installed from. Third-party marketplaces do not auto-update by default; pull the latest `main` with `claude plugin marketplace update docs-kit && claude plugin update docs-kit@docs-kit`.
+
+## Content contract
+
+Every consuming project has a `docs/site.yaml` validated by [`schema/site.schema.json`](schema/site.schema.json); see [`examples/site.yaml`](examples/site.yaml). Validate one locally:
+
+```sh
+npm ci
+node schema/validate.mjs path/to/docs/site.yaml
+```
+
+## Using the kit
+
+The repository root is the npm package [`@zebradil/docs-kit`](https://www.npmjs.com/package/@zebradil/docs-kit), published from each release tag ([ADR 0007](docs/adr/0007-publish-to-npm.md)). A consuming project's `docs/` needs three files besides `site.yaml` and its pages under `src/content/docs/`:
+
+<!-- x-release-please-start-version -->
+```jsonc
+// package.json
+{ "private": true, "type": "module", "dependencies": { "@zebradil/docs-kit": "0.10.0" } }
+```
+<!-- x-release-please-end -->
+
+```js
+// astro.config.mjs
+import docsKit from '@zebradil/docs-kit';
+
+export default docsKit({ site: 'site.yaml' });
+```
+
+```js
+// src/content.config.mjs
+export { collections } from '@zebradil/docs-kit/content';
+```
+
+Build with `npm ci && npx astro build` from `docs/`. The site is served at `https://<owner>.github.io/<repo>/`, derived from `repo:` in `site.yaml`; with `domain:` set, it is served at `https://<domain>/`. [`packages/docs-kit/fixture/`](packages/docs-kit/fixture/) is a complete example.
+
+To count visitors, set `analytics:` in `site.yaml`; the script is loaded on every page with the given `data-*` attributes:
+
+```yaml
+analytics:
+  script: https://stats.example.dev/app.js
+  attributes:
+    data-website-id: 00000000-0000-0000-0000-000000000000
+```
+
+For coding agents and LLMs, every site serves [`/llms.txt`](https://llmstxt.org), an index of all pages, and `/llms-full.txt`, all pages in one file. Each page's Markdown source is also served at its URL with `.md` appended (`/guides/configure/` → `/guides/configure.md`), with relative links made absolute. GitHub Pages cannot vary a response on the `Accept` header, so the `.md` URLs are the only Markdown route.
+
+### Publishing with GitHub Actions
+
+[`.github/workflows/docs.yml`](.github/workflows/docs.yml) is a reusable workflow. A consuming project calls it from `.github/workflows/docs.yml`, pinned to the same tag as the kit in `docs/package.json`:
+
+<!-- x-release-please-start-version -->
+```yaml
+name: docs
+on:
+  push: { branches: [main] }
+  pull_request:
+permissions: { contents: read, pages: write, id-token: write }
+jobs:
+  docs:
+    uses: Zebradil/docs-kit/.github/workflows/docs.yml@v0.10.0
+```
+<!-- x-release-please-end -->
+
+Keep `uses:` on its own indented line: Renovate's github-actions manager finds refs line by line and misses one inside a flow mapping.
+
+The caller must grant `pages: write` and `id-token: write`: a called workflow can only narrow the caller's token permissions, never widen them, and the deploy job needs both.
+
+On every run it installs `docs/` with `npm ci`, builds the CLI with `reference.cli.build` (run from the repository root) when set, regenerates the CLI reference with `help2md` into `docs/src/content/docs/reference/cli`, and builds the site with `npx astro build` (which validates `site.yaml`). On a pull request it fails if the regenerated reference differs from the committed one and prints the diff. On a push to the default branch it deploys `docs/dist` to GitHub Pages.
+
+Inputs, all optional:
+
+| Input | Default | Use |
+|---|---|---|
+| `directory` | `docs` | Docs directory, relative to the repository root. |
+| `nix` | `false` | Install Nix first, for `build: nix build` and friends. |
+| `deploy` | `true` | Deploy on pushes to the default branch. |
+
+Runs on `ubuntu-latest`, which already has Rust (cargo, rustup) and Go (default version linked into `/usr/bin`; a newer `go` line in `go.mod` makes Go download that toolchain itself); see the [runner image tool list](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md).
+
+One manual step per repository, by its owner: enable Pages with GitHub Actions as the source, in Settings → Pages → Build and deployment → Source: GitHub Actions, or:
+
+```sh
+gh api --method POST repos/<owner>/<repo>/pages -f build_type=workflow
+```
+
+Until then the deploy job fails. This repository builds [the fixture](packages/docs-kit/fixture/) through the workflow ([`pages.yml`](.github/workflows/pages.yml)) and deploys it only when the repository variable `PAGES_ENABLED` is `true`; set it after enabling Pages (`gh variable set PAGES_ENABLED --body true`).
+
+Terms used across the kit are defined in [`CONTEXT.md`](CONTEXT.md).
+
+Status: pre-release. Kit, workflow and skills are in place; no `v*` tag yet, first pilot pending. See the design map issue (#1).
+
+## refgen/help2md
+
+Generates CLI reference pages from `--help` output (clap and cobra), one Starlight page per command:
+
+```sh
+node refgen/help2md.mjs --bin target/release/kasha --out docs/src/content/docs/reference/cli
+```
+
+The kit ships it as the `help2md` binary, so a consuming project runs the version it pins, from `docs/`:
+
+```sh
+npx --no-install help2md --bin ../target/release/kasha --out src/content/docs/reference/cli
+```
+
+`--no-install` matters: without it, a missing kit makes `npx` fetch an unrelated `help2md` package from the npm registry.
+
+Pages are named after the command path (`kasha.md`, `kasha-config-set.md`). `help` and cobra's default `completion` are skipped. Tests: `node --test`.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@zebradil/docs-kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebradil/docs-kit.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./packages/docs-kit/index.mjs",
+    "./content": "./packages/docs-kit/content.mjs"
+  },
+  "bin": {
+    "help2md": "refgen/help2md.mjs"
+  },
+  "files": [
+    "packages/docs-kit",
+    "!packages/docs-kit/fixture",
+    "schema/site.schema.json",
+    "schema/validate.mjs",
+    "refgen/help2md.mjs"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "validate": "node schema/validate.mjs"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "0.42.10",
+    "@fontsource-variable/fraunces": "5.3.0",
+    "@fontsource-variable/instrument-sans": "5.3.0",
+    "@fontsource-variable/jetbrains-mono": "5.3.0",
+    "@fontsource-variable/schibsted-grotesk": "5.3.0",
+    "@fontsource/ibm-plex-mono": "5.3.0",
+    "@fontsource/outfit": "5.3.0",
+    "ajv": "8.20.0",
+    "astro": "7.4.7",
+    "yaml": "2.9.1"
+  },
+  "version": "0.10.0"
+}

package/packages/docs-kit/Cascade.astro

@@ -0,0 +1,205 @@
+---
+// The cascade panel: one request falling through ordered tiers of backends, one tab per scenario.
+import { TabItem, Tabs } from '@astrojs/starlight/components';
+import site from 'virtual:docs-kit/site';
+import { escape, inline } from './text.mjs';
+
+const cascade = site.cascade;
+const glyph = { hit: '●', miss: '×', down: '○', idle: '·' };
+const word = { hit: 'hit', miss: 'miss', down: 'down', idle: 'not asked' };
+const state = (scenario, id) => scenario.states[id] ?? { state: 'idle' };
+---
+
+<section class="kit-cascade" aria-labelledby="kit-cascade-title">
+  <div class="kit-cascade-head">
+    <h2 id="kit-cascade-title">{cascade.title ?? 'How a request falls through'}</h2>
+    {cascade.request && <code>{cascade.request}</code>}
+  </div>
+  {
+    cascade.hub && (
+      <div class="kit-cascade-hub">
+        <span class="kit-cascade-hub-name">{cascade.hub.name}</span>
+        {cascade.hub.body && <span class="kit-cascade-hub-body" set:html={inline(cascade.hub.body)} />}
+      </div>
+    )
+  }
+  <Tabs>
+    {
+      cascade.scenarios.map((scenario) => (
+        <TabItem label={scenario.label}>
+          <ol class="kit-cascade-tiers">
+            {cascade.tiers.map((tier) => (
+              <li class="kit-cascade-tier">
+                <div class="kit-cascade-tier-name">
+                  {tier.label && <span>{tier.label}</span>}
+                  <strong>{tier.name}</strong>
+                </div>
+                <ul>
+                  {tier.backends.map((b) => {
+                    const s = state(scenario, b.id);
+                    return (
+                      <li class="kit-cascade-backend" data-state={s.state}>
+                        <code>{b.name}</code>
+                        <span>
+                          {glyph[s.state]} {word[s.state]}
+                          {s.text && ` · ${s.text}`}
+                        </span>
+                      </li>
+                    );
+                  })}
+                </ul>
+              </li>
+            ))}
+          </ol>
+          {scenario.note && <p class="kit-cascade-note" set:html={inline(scenario.note)} />}
+        </TabItem>
+      ))
+    }
+  </Tabs>
+</section>
+
+<style is:global>
+  .kit-cascade {
+    border: 1px solid var(--sl-color-hairline-light);
+    border-radius: 1.5rem;
+    overflow: hidden;
+  }
+  .kit-cascade-head {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    align-items: baseline;
+    gap: 0.5rem 1.5rem;
+    padding: 1.125rem 1.5rem;
+    border-bottom: 1px solid var(--sl-color-hairline-light);
+  }
+  .kit-landing .kit-cascade-head h2 {
+    margin: 0;
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+    font-weight: 400;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--sl-color-gray-3);
+  }
+  .kit-cascade-head code {
+    padding: 0;
+    background: none;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-2);
+  }
+  .kit-cascade-hub {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.75rem 1.25rem;
+    padding: 1.25rem 1.5rem;
+    border-bottom: 1px solid var(--sl-color-hairline-light);
+    background-image: radial-gradient(circle, var(--sl-color-gray-5) 1.4px, transparent 1.6px);
+    background-size: 12px 12px;
+  }
+  .kit-cascade-hub-name {
+    padding: 0.5rem 0.875rem;
+    border-radius: 0.625rem;
+    background: var(--sl-color-white);
+    color: var(--sl-color-black);
+    font-weight: 700;
+  }
+  .kit-cascade-hub-body {
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.375rem;
+    background: var(--sl-color-black);
+    color: var(--sl-color-gray-2);
+  }
+  /* Starlight's tab strip, inset to line up with the panel's rows. */
+  .kit-cascade starlight-tabs {
+    display: block;
+  }
+  .kit-cascade starlight-tabs .tablist-wrapper {
+    padding: 0.75rem 1.5rem 0;
+  }
+  .kit-cascade [role='tabpanel'] {
+    margin: 0;
+  }
+  .kit-cascade-tiers,
+  .kit-cascade-tier ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .kit-cascade-tier {
+    display: flex;
+    flex-wrap: wrap;
+    margin: 0;
+    border-bottom: 1px dashed var(--sl-color-hairline-light);
+  }
+  .kit-cascade-tier:last-child {
+    border-bottom: 0;
+  }
+  .kit-cascade-tier-name {
+    flex: 1 1 10rem;
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    padding: 1.375rem 1.5rem;
+  }
+  .kit-cascade-tier-name span {
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+    color: var(--sl-color-gray-3);
+  }
+  .kit-cascade-tier-name strong {
+    font-size: var(--sl-text-lg);
+    color: var(--sl-color-white);
+  }
+  .kit-cascade-tier ul {
+    flex: 999 1 30rem;
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(15rem, 1fr));
+    gap: 0.75rem;
+    padding: 1.125rem 1.5rem;
+  }
+  .kit-cascade-backend {
+    display: flex;
+    flex-direction: column;
+    gap: 0.375rem;
+    margin: 0;
+    padding: 0.875rem 1rem;
+    border: 1px solid var(--sl-color-hairline-light);
+    border-radius: 0.875rem;
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+    color: var(--sl-color-gray-3);
+  }
+  .kit-cascade-backend code {
+    padding: 0;
+    background: none;
+    font-size: var(--sl-text-sm);
+    overflow-wrap: anywhere;
+    color: var(--sl-color-gray-3);
+  }
+  .kit-cascade-backend[data-state='hit'] {
+    border: 1.5px solid var(--sl-color-accent);
+    background: var(--sl-color-accent-low);
+    color: var(--sl-color-text-accent);
+  }
+  .kit-cascade-backend[data-state='hit'] code {
+    color: var(--sl-color-white);
+  }
+  .kit-cascade-backend[data-state='down'] {
+    border: 1.5px dashed var(--sl-color-orange);
+    color: var(--sl-color-orange-high);
+  }
+  .kit-cascade-backend:is([data-state='down'], [data-state='miss']) code {
+    color: var(--sl-color-gray-2);
+  }
+  .kit-cascade-note {
+    margin: 0;
+    padding: 1rem 1.5rem;
+    border-top: 1px solid var(--sl-color-hairline-light);
+    background: var(--sl-color-bg-nav);
+    font-size: var(--sl-text-sm);
+    line-height: 1.5;
+    color: var(--sl-color-gray-2);
+  }
+</style>

package/packages/docs-kit/Diff.astro

@@ -0,0 +1,134 @@
+---
+// The diff panel: a change on one side, the files it changes in each target on the other, one tab per target.
+import { Code, TabItem, Tabs } from '@astrojs/starlight/components';
+import site from 'virtual:docs-kit/site';
+import { inline } from './text.mjs';
+
+const diff = site.diff;
+const count = (files, sign) => files.flatMap((f) => f.diff.split('\n')).filter((l) => l.startsWith(sign)).length;
+const summary = (files) =>
+  files.length
+    ? `${files.length} ${files.length === 1 ? 'file' : 'files'} changed, +${count(files, '+')} −${count(files, '-')}`
+    : 'No changes';
+// Expressive Code's own `diff` language leaves a diff with hunk headers unmarked, so the kit turns the
+// +/- column into ins/del line markers, marks the hunk headers, and highlights the file in its own language.
+const file = ({ path, diff }) => {
+  const marks = { ins: [], del: [], mark: [] };
+  const lines = diff.replace(/\n$/, '').split('\n').map((line, i) => {
+    if (line.startsWith('@@')) return marks.mark.push(i + 1) && line;
+    if (line[0] === '+') marks.ins.push(i + 1);
+    if (line[0] === '-') marks.del.push(i + 1);
+    return line.slice(1);
+  });
+  const meta = Object.entries(marks).filter(([, n]) => n.length).map(([k, n]) => `${k}={${n}}`);
+  return { code: lines.join('\n'), lang: path.split('.').pop().replace(/^yml$/, 'yaml'), meta: [`title="${path}"`, ...meta].join(' ') };
+};
+---
+
+<section class="kit-diff" aria-labelledby="kit-diff-title">
+  <div class="kit-diff-head">
+    <h2 id="kit-diff-title">{diff.title ?? 'What a change looks like'}</h2>
+    {diff.intro && <p set:html={inline(diff.intro)} />}
+  </div>
+  <div class="kit-diff-body">
+    {
+      diff.change && (
+        <div class="kit-diff-change">
+          <p class="kit-diff-label">
+            {diff.change.label ?? 'The change'} <span>{summary(diff.change.files)}</span>
+          </p>
+          {diff.change.files.map((f) => (
+            <Code {...file(f)} />
+          ))}
+        </div>
+      )
+    }
+    <div class="kit-diff-result">
+      <p class="kit-diff-label">{diff.label ?? 'What it changes'}</p>
+      <Tabs>
+        {
+          diff.tabs.map((t) => (
+            <TabItem label={t.label}>
+              <p class="kit-diff-summary">{summary(t.files)}</p>
+              {t.files.map((f) => (
+                <Code {...file(f)} />
+              ))}
+            </TabItem>
+          ))
+        }
+      </Tabs>
+    </div>
+  </div>
+</section>
+
+<style is:global>
+  .kit-landing .kit-diff-head {
+    max-width: 44rem;
+  }
+  .kit-diff-head p {
+    margin: 0;
+    line-height: 1.55;
+    color: var(--sl-color-gray-2);
+  }
+  .kit-diff-body {
+    display: grid;
+    grid-template-columns: minmax(0, 2fr) minmax(0, 3fr);
+    gap: 1.5rem;
+    margin-top: 2rem;
+  }
+  @media (max-width: 60rem) {
+    .kit-diff-body {
+      grid-template-columns: minmax(0, 1fr);
+    }
+  }
+  .kit-diff-change,
+  .kit-diff-result {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    min-width: 0;
+    padding: 1.25rem;
+    border: 1px solid var(--sl-color-hairline-light);
+    border-radius: 1rem;
+    background: var(--sl-color-bg-nav);
+  }
+  .kit-diff-result {
+    border-color: var(--sl-color-accent);
+  }
+  .kit-diff-label {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: space-between;
+    gap: 0.25rem 1rem;
+    margin: 0;
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+    color: var(--sl-color-gray-3);
+  }
+  .kit-diff-label span,
+  .kit-diff-summary {
+    margin: 0;
+    font-family: var(--sl-font-mono);
+    font-size: var(--sl-text-xs);
+    letter-spacing: 0;
+    text-transform: none;
+    color: var(--sl-color-gray-2);
+  }
+  .kit-diff starlight-tabs {
+    display: block;
+  }
+  .kit-diff [role='tabpanel'] {
+    display: flex;
+    flex-direction: column;
+    gap: 1rem;
+    margin-top: 1rem;
+  }
+  .kit-diff [role='tabpanel'][hidden] {
+    display: none;
+  }
+  .kit-diff .expressive-code {
+    margin: 0;
+  }
+</style>