docs(site): land the bilingual Rspress documentation site with GitHub Pages delivery

.changeset/docs-site-readme-link.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Link the package README to the hosted documentation site so `npm` readers can find the full guide, configuration, host, event, notice, and diagnostics references. The pinned Cursor and portable capability tables now record Cursor's `.cursor-plugin/marketplace.json` path and the portable `${PLUGIN_ROOT}`/`${PLUGIN_DATA}` tokens, so the generated host matrix matches what the adapters emit. (#384)

.github/workflows/ci.yml

@@ -22,11 +22,12 @@ concurrency:
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
-  # PR-only docs allowlist: docs/**, agent-patterns/**, .changeset/*.md, and
-  # top-level *.md. Nested markdown elsewhere is code because examples and
-  # packages contain compiled SKILL.md artifacts, and package markdown affects
-  # npm pack audits. Classification fails open so uncertain PRs run every heavy
-  # job; pushes to main never skip any job based on changed paths.
+  # PR-only docs allowlist: docs/**, agent-patterns/**, website/** (the
+  # Rspress site, validated by docs.yml), .changeset/*.md, and top-level *.md.
+  # Nested markdown elsewhere is code because examples and packages contain
+  # compiled SKILL.md artifacts, and package markdown affects npm pack audits.
+  # Classification fails open so uncertain PRs run every heavy job; pushes to
+  # main never skip any job based on changed paths.
   # Path rules and fail-open listing checks live in
   # scripts/classify-docs-only.mjs (unit-tested). This job sparse-checkouts
   # only that script so the vendored Effect subtree never lands on the

.github/workflows/docs.yml

@@ -0,0 +1,98 @@
+name: Docs
+
+# Validates the Rspress documentation site (website/) on every pull request
+# and push to main, and deploys website/doc_build to GitHub Pages from main
+# (on push, or on a manual dispatch of the main branch).
+#
+# No `paths:` filter on purpose: package-source changes can break TypeDoc
+# generation and the generated reference pages without touching website/**,
+# and a path-filtered workflow can never safely become a required check.
+# Website-only PRs skip the heavy jobs in ci.yml (scripts/classify-docs-only.mjs
+# treats website/** as docs-only) because this workflow covers them.
+#
+# One-time prerequisite: repository Settings -> Pages -> Source must be
+# "GitHub Actions" (REST: build_type=workflow), or deploy-pages fails.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# PR pushes cancel the superseded run of the same PR. Every run that can
+# deploy (push or manual dispatch on main) shares one non-cancelling group so
+# build-and-deploy runs execute in order and an older, slower build can never
+# deploy over a newer one (GitHub keeps at most one pending run per group, so
+# a superseded pending build is dropped, never reordered). Dispatches on other
+# refs get SHA-keyed groups.
+concurrency:
+  group: docs-${{ github.ref == 'refs/heads/main' && github.event_name != 'pull_request' && 'main' || github.event.pull_request.number || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    name: Docs site (Node 22.19)
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v7
+      - uses: pnpm/setup@v2
+        with:
+          cache: true
+          install: false
+          runtime: node@22.19.0
+      - run: pnpm install --frozen-lockfile
+      # Website-only PRs skip every ci.yml job that lints, so lint here too.
+      - run: pnpm lint
+      # Typecheck the site config and build it. Rspress's own dead-link,
+      # dead-anchor, dead-image, and language-parity checks fail the build if
+      # TypeDoc or the generated reference pages are missing, since the
+      # authored pages link to them.
+      - run: pnpm docs:site:build
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: website/doc_build
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    # Never cancel an in-flight Pages deployment.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    steps:
+      # Re-running an older main run (or any path that bypasses the queue
+      # above) must not publish a stale site: only deploy when this commit is
+      # still the head of main.
+      - name: Confirm this commit is still the head of main
+        id: head
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          head="$(gh api "repos/${GITHUB_REPOSITORY}/branches/main" --jq .commit.sha)"
+          if [ "$head" = "$GITHUB_SHA" ]; then
+            echo "deploy=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "deploy=false" >> "$GITHUB_OUTPUT"
+            echo "Skipped deploy: main moved to ${head}; this run built ${GITHUB_SHA}." >> "$GITHUB_STEP_SUMMARY"
+          fi
+      - if: steps.head.outputs.deploy == 'true'
+        uses: actions/configure-pages@v6
+      - if: steps.head.outputs.deploy == 'true'
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -14,3 +14,12 @@ packages/*/NOTICE
 
 # Aborted runtime-playground fixture workspaces
 .runtime-playground-*/
+
+website/doc_build/
+website/docs/en/api/**/*.md
+website/docs/zh/api/**/*.md
+# Build-time reference pages rendered from capability tables and docs/diagnostics.md
+website/docs/*/reference/hosts.md
+website/docs/*/reference/events.md
+website/docs/*/reference/notices.md
+website/docs/*/reference/diagnostics.md

AGENTS.md

@@ -15,6 +15,36 @@
 - Never accept or capture a Workbench route while its loading state is still visible.
 - Browser acceptance must cover populated state plus the documented stale-diagnostic and repair flow.
 
+## Documentation site
+
+- `website/` is the public Rspress docsite
+  (<https://scriptedalchemy.github.io/agent-bundle/>), deployed from `main`
+  by `.github/workflows/docs.yml`. It is user-facing product, held to the
+  same accuracy bar as the code it describes.
+- A PR that adds or changes user-facing behavior — a CLI command or flag,
+  config key, public export or entry point, hook event or result rule, host
+  target or artifact, diagnostic code, environment variable, or example —
+  updates the matching page under `website/docs/en/**` **and** its
+  `website/docs/zh/**` translation in the same PR. Ask the same question
+  when writing the changeset: if the summary is user-facing, the docs almost
+  certainly need the same change. Internal refactors, tests, and CI do not.
+- Reference prose must match the source. State what the code does, not what
+  the design intended; when unsure, read the adapter or validator before
+  writing the sentence. Where the generated pages and hand-written pages
+  disagree, the generated pages are right — fix the hand-written one.
+- Never hand-edit generated pages: `website/docs/{en,zh}/api/**` comes from
+  TypeDoc, and the hosts, events, and diagnostics reference pages are
+  rendered at build time from `packages/agent-bundle/src/adapters/capabilities/*.json`
+  and `docs/diagnostics.md`. Change the source, and the site follows.
+- `pnpm docs:site:build` is the gate: typecheck, build, and Rspress's
+  dead-link, dead-anchor, dead-image, and language-parity checks. Parity
+  fails the build if one locale gains a page the other lacks. Run it before
+  pushing anything under `website/`, and after any change to public
+  exports, since TypeDoc compiles `packages/agent-bundle/src` directly.
+- The site is desktop-first, like the Workbench. Wide tables scroll; code
+  samples wrap at roughly 90 columns so they render without horizontal
+  overflow at the default content width.
+
 ## Changesets
 
 - Every PR that changes a publishable package (`packages/agent-bundle`,

README.md

@@ -2,6 +2,8 @@
 
 agent-bundle compiles an agent plugin — skills, hooks, MCP servers, and scripts, described by one typed config — into installable artifacts for Claude Code, Codex, and Cursor, plus a portable layout. You write the plugin once; the compiler emits each host's manifests and wrappers.
 
+Documentation: [scriptedalchemy.github.io/agent-bundle](https://scriptedalchemy.github.io/agent-bundle/) (English and 简体中文; guide, reference, generated type API, host capability matrices).
+
 Requires Node.js 22.19 or later.
 
 ## Install

docs/diagnostics.md

@@ -2,9 +2,12 @@
 
 Every agent-bundle failure or nudge is one structured diagnostic: a stable
 `code` (`AB` + four digits), a `severity` (`error`, `warning`, or `info`), a
-`message`, and usually a `sourcePath` and a `recovery` hint. Commands exit
-nonzero only when an **error** diagnostic is present; warnings and infos never
-gate a build, a validation, or a dev rebuild.
+`message`, and usually a `sourcePath` and a `recovery` hint. The
+diagnostic-gated commands (`build`, `prepack`, `validate`, `doctor`, `install`,
+`dev`) exit nonzero only when an **error** diagnostic is present; warnings and
+infos never gate a build, a validation, or a dev rebuild. `eval` and `inspect`
+additionally exit `1` for a failing or inconclusive trial or an invalid model
+even when no error diagnostic was reported.
 
 ## Code families
 

docs/effect-conventions.md

@@ -11,6 +11,7 @@ docs, or examples' user code. The four-concept newcomer ledger is untouched.
 | --- | --- |
 | npm `effect` | **`4.0.0-rc.112`** (exact). Latest published `rc` dist-tag on 2026-09-01. The Wave 3.5 brief named `4.0.0-rc.113`; that version was not on the registry. Re-pin chores take the next published RC. |
 | Vendored tree | `repos/effect` via `git subtree` from [Effect-TS/effect](https://github.com/Effect-TS/effect.git) `main` (v4). Squash commit tracks `packages/effect` version **4.0.0-rc.112**. |
+| `website` `typescript` | **`6.0.3`**, behind the root's TypeScript 7, because `typedoc@0.28` peers on `<= 6.0.x`. TypeDoc and twoslash compile `packages/agent-bundle/src` with it, so TS7-only syntax in the package breaks `pnpm docs:site:build` first. Re-pin chores check whether a newer `typedoc` lifts the ceiling. |
 
 Application code imports the npm package. Never import from `repos/**`.