From e32176d5395cc0891f9089650985fca2d72ff028 Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 5 Aug 2026 16:30:02 +0800 Subject: [PATCH 1/8] docs(skills): read bundled Rstack docs --- .../skills/rstack-cli-best-practices/SKILL.md | 113 ++++++------------ 1 file changed, 37 insertions(+), 76 deletions(-) diff --git a/.agents/skills/rstack-cli-best-practices/SKILL.md b/.agents/skills/rstack-cli-best-practices/SKILL.md index 11b6ac4..954586b 100644 --- a/.agents/skills/rstack-cli-best-practices/SKILL.md +++ b/.agents/skills/rstack-cli-best-practices/SKILL.md @@ -1,92 +1,53 @@ --- name: rstack-cli-best-practices -description: Guidance on using Rstack CLI, including `rs` commands, the `rstack.config.ts` file, and import paths from the `rstack` package. Use for Rstack CLI-related tasks. +description: Guidance for Rstack CLI tasks. Use when running `rs` commands, editing `rstack.config.*`, using `rstack` package imports, or working with Rstack-powered apps, libraries, docs, tests, linting, formatting, Git hooks, staged files, and monorepos. Requires reading the version-matched documentation shipped in the installed `rstack` package before making changes. --- # Rstack CLI Best Practices -Rstack CLI is the `rstack` package, exposed through the `rs` binaries. It provides one CLI, one config file, and a consistent workflow for the Rstack JavaScript toolchain. +## Rstack: ALWAYS read installed docs before working -It covers web app, library, docs, test, lint, formatting, Git hook, and staged-file workflows. +Before any Rstack work, find and read the relevant Markdown documentation shipped with the +installed `rstack` package. Model knowledge and summaries in this skill can be outdated; the +installed documentation is the source of truth for the project's Rstack version. -## Commands +1. Resolve the documentation root from the project or workspace directory: -Use `rs -h` for top-level help, and `rs -h` for command help where supported. + ```sh + node -p "require('node:path').join(require('node:path').dirname(require.resolve('rstack/package.json')), 'dist/docs')" + ``` -| Command | Purpose | Underlying tool | Config | -| ------------ | -------------------------------- | --------------- | --------------- | -| `rs dev` | Run the app dev server | Rsbuild | `define.app` | -| `rs build` | Build the app for production | Rsbuild | `define.app` | -| `rs preview` | Preview the app production build | Rsbuild | `define.app` | -| `rs lib` | Build a library | Rslib | `define.lib` | -| `rs doc` | Serve or build docs | Rspress | `define.doc` | -| `rs test` | Run tests | Rstest | `define.test` | -| `rs lint` | Lint code | Rslint | `define.lint` | -| `rs fmt` | Format code | Prettier | `define.fmt` | -| `rs setup` | Install project-local Git hooks | None | None | -| `rs staged` | Run tasks on staged Git files | lint-staged | `define.staged` | + The usual location is `node_modules/rstack/dist/docs`. -Key behavior: +2. Read only the pages relevant to the task before proposing or making changes. If the correct + page is unclear, start with the documentation index and search the documentation root with + `rg -n "" `. -- Unless `define.test` already sets `extends`, `rs test` extends `define.app` through `@rstest/adapter-rsbuild` or falls back to `define.lib` through `@rstest/adapter-rslib`. The app config takes precedence when both are defined. -- `rs doc` requires the optional `@rspress/core` dependency. +3. For exact CLI flags and behavior, also run `rs -h` or `rs -h` when supported. -## rstack.config.ts +If the package or bundled documentation cannot be resolved, verify that `rstack` is installed, +report the installed version, and use CLI help plus the online Rstack documentation as a fallback. +Do not guess from model memory. -Rstack CLI loads `rstack.config.{ts,js,mts,mjs}` by default. +## Documentation map -Register config with `define.*`: +These links target the usual project-local skill installation. If a link does not resolve, open +the same relative path under the resolved documentation root. -```ts -import { define } from 'rstack'; - -define.app({ - // Rsbuild config for `rs dev`, `rs build`, and `rs preview` -}); - -define.test({ - // Rstest config for `rs test` -}); -``` - -- `define.app(config)`: Rsbuild config for `rs dev`, `rs build`, and `rs preview`. Docs: https://rsbuild.rs/config/ -- `define.lib(config)`: Rslib config for `rs lib`; Docs: https://rslib.rs/config/ -- `define.doc(config)`: Rspress config for `rs doc`; Docs: https://rspress.rs/api/config/config-basic -- `define.test(config)`: Rstest config for `rs test`; Docs: https://rstest.rs/config/ -- `define.lint(config)`: Rslint config for `rs lint`; Docs: https://rslint.rs/config/ -- `define.fmt(config)`: Formatting options for `rs fmt`. -- `define.staged(config)`: lint-staged config for `rs staged`; accepts `Record`. - -### Lazy Configuration - -Prefer async functions with dynamic imports for dependencies. Avoid top-level sync imports of heavy dependencies in `rstack.config.ts`. - -```ts -import { define } from 'rstack'; - -define.app(async () => { - const { pluginReact } = await import('@rsbuild/plugin-react'); - return { - plugins: [pluginReact()], - }; -}); -``` - -## Import Paths - -Prefer Rstack-exported paths: - -| Instead of | Prefer | -| ------------------------- | ------------------------ | -| `@rsbuild/core` | `rstack/app` | -| `@rslib/core` | `rstack/lib` | -| `@rstest/core` | `rstack/test` | -| `@rslint/core` | `rstack/lint` | -| `@rsbuild/core/types` | `rstack/types` | -| `@rslib/core/types` | `rstack/types` | -| `@rstest/core/globals` | `rstack/test/globals` | -| `@rstest/core/importMeta` | `rstack/test/importMeta` | - -## Git Hooks - -Use [`rs setup`](https://rstack.rs/guide/cli/setup) for project-local Git hooks, commonly with `rs staged` in a `pre-commit` hook. +- [Overview](../../../node_modules/rstack/dist/docs/index.md) +- [Quick start and command overview](../../../node_modules/rstack/dist/docs/guide/quick-start.md) +- [Configuration](../../../node_modules/rstack/dist/docs/guide/configuration.md) +- [API and import paths](../../../node_modules/rstack/dist/docs/guide/api-reference.md) +- [Monorepos](../../../node_modules/rstack/dist/docs/guide/monorepo.md) +- [Testing](../../../node_modules/rstack/dist/docs/guide/testing.md) +- [Formatting](../../../node_modules/rstack/dist/docs/guide/formatting.md) +- CLI commands: [dev](../../../node_modules/rstack/dist/docs/guide/cli/dev.md), + [build](../../../node_modules/rstack/dist/docs/guide/cli/build.md), + [preview](../../../node_modules/rstack/dist/docs/guide/cli/preview.md), + [lib](../../../node_modules/rstack/dist/docs/guide/cli/lib.md), + [doc](../../../node_modules/rstack/dist/docs/guide/cli/doc.md), + [test](../../../node_modules/rstack/dist/docs/guide/cli/test.md), + [lint](../../../node_modules/rstack/dist/docs/guide/cli/lint.md), + [fmt](../../../node_modules/rstack/dist/docs/guide/cli/fmt.md), + [setup](../../../node_modules/rstack/dist/docs/guide/cli/setup.md), and + [staged](../../../node_modules/rstack/dist/docs/guide/cli/staged.md) From 93dd9eaab65c1ed4a4e19f2b4f2eb96ea11c94ae Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 5 Aug 2026 16:33:07 +0800 Subject: [PATCH 2/8] docs(skills): shorten Rstack skill description --- .agents/skills/rstack-cli-best-practices/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/rstack-cli-best-practices/SKILL.md b/.agents/skills/rstack-cli-best-practices/SKILL.md index 954586b..1d67ed6 100644 --- a/.agents/skills/rstack-cli-best-practices/SKILL.md +++ b/.agents/skills/rstack-cli-best-practices/SKILL.md @@ -1,6 +1,6 @@ --- name: rstack-cli-best-practices -description: Guidance for Rstack CLI tasks. Use when running `rs` commands, editing `rstack.config.*`, using `rstack` package imports, or working with Rstack-powered apps, libraries, docs, tests, linting, formatting, Git hooks, staged files, and monorepos. Requires reading the version-matched documentation shipped in the installed `rstack` package before making changes. +description: Guidance for Rstack CLI work involving `rs` commands, `rstack.config.*`, package APIs, or Rstack-based projects and tooling. Requires reading the version-matched docs bundled with the installed `rstack` package first. --- # Rstack CLI Best Practices From c82b29c33089cb9b8bc69b4c478ce99dd30a5e3c Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 5 Aug 2026 16:37:29 +0800 Subject: [PATCH 3/8] docs(skills): simplify Rstack skill description --- .agents/skills/rstack-cli-best-practices/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/rstack-cli-best-practices/SKILL.md b/.agents/skills/rstack-cli-best-practices/SKILL.md index 1d67ed6..5f7ca8f 100644 --- a/.agents/skills/rstack-cli-best-practices/SKILL.md +++ b/.agents/skills/rstack-cli-best-practices/SKILL.md @@ -1,6 +1,6 @@ --- name: rstack-cli-best-practices -description: Guidance for Rstack CLI work involving `rs` commands, `rstack.config.*`, package APIs, or Rstack-based projects and tooling. Requires reading the version-matched docs bundled with the installed `rstack` package first. +description: Guidance for Rstack CLI work involving `rs` commands, `rstack.config.*`, package APIs, or Rstack-based projects and tooling. --- # Rstack CLI Best Practices From e2a1e064735979408c8172852073d87682e0b09c Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 5 Aug 2026 16:40:24 +0800 Subject: [PATCH 4/8] docs(skills): simplify bundled docs lookup --- .../skills/rstack-cli-best-practices/SKILL.md | 20 +++++++------------ 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/.agents/skills/rstack-cli-best-practices/SKILL.md b/.agents/skills/rstack-cli-best-practices/SKILL.md index 5f7ca8f..1378bda 100644 --- a/.agents/skills/rstack-cli-best-practices/SKILL.md +++ b/.agents/skills/rstack-cli-best-practices/SKILL.md @@ -11,23 +11,17 @@ Before any Rstack work, find and read the relevant Markdown documentation shippe installed `rstack` package. Model knowledge and summaries in this skill can be outdated; the installed documentation is the source of truth for the project's Rstack version. -1. Resolve the documentation root from the project or workspace directory: +1. Read only the pages relevant to the task under `node_modules/rstack/dist/docs` before proposing + or making changes. - ```sh - node -p "require('node:path').join(require('node:path').dirname(require.resolve('rstack/package.json')), 'dist/docs')" - ``` - - The usual location is `node_modules/rstack/dist/docs`. - -2. Read only the pages relevant to the task before proposing or making changes. If the correct - page is unclear, start with the documentation index and search the documentation root with - `rg -n "" `. +2. If the correct page is unclear, start with the documentation index and search the documentation + root with `rg -n "" `. 3. For exact CLI flags and behavior, also run `rs -h` or `rs -h` when supported. -If the package or bundled documentation cannot be resolved, verify that `rstack` is installed, -report the installed version, and use CLI help plus the online Rstack documentation as a fallback. -Do not guess from model memory. +If the bundled docs are not available at that path, locate the installed `rstack` package. If they +are still unavailable, verify that `rstack` is installed, report the installed version, and use CLI +help plus the online Rstack documentation as a fallback. Do not guess from model memory. ## Documentation map From 7e4e64c0b494dea48f9fcfec5afc01b8a02517a5 Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 5 Aug 2026 16:48:58 +0800 Subject: [PATCH 5/8] docs(skills): use bundled llms index --- .../skills/rstack-cli-best-practices/SKILL.md | 31 +++---------------- scripts/prepare-release.js | 10 ++++-- 2 files changed, 12 insertions(+), 29 deletions(-) diff --git a/.agents/skills/rstack-cli-best-practices/SKILL.md b/.agents/skills/rstack-cli-best-practices/SKILL.md index 1378bda..a7a49a5 100644 --- a/.agents/skills/rstack-cli-best-practices/SKILL.md +++ b/.agents/skills/rstack-cli-best-practices/SKILL.md @@ -11,37 +11,14 @@ Before any Rstack work, find and read the relevant Markdown documentation shippe installed `rstack` package. Model knowledge and summaries in this skill can be outdated; the installed documentation is the source of truth for the project's Rstack version. -1. Read only the pages relevant to the task under `node_modules/rstack/dist/docs` before proposing - or making changes. +1. Start with `node_modules/rstack/dist/docs/llms.txt`, then read only the linked pages relevant to + the task before proposing or making changes. -2. If the correct page is unclear, start with the documentation index and search the documentation - root with `rg -n "" `. +2. If `llms.txt` is unavailable, start with `node_modules/rstack/dist/docs/index.md` and search the + documentation directory with `rg -n "" node_modules/rstack/dist/docs`. 3. For exact CLI flags and behavior, also run `rs -h` or `rs -h` when supported. If the bundled docs are not available at that path, locate the installed `rstack` package. If they are still unavailable, verify that `rstack` is installed, report the installed version, and use CLI help plus the online Rstack documentation as a fallback. Do not guess from model memory. - -## Documentation map - -These links target the usual project-local skill installation. If a link does not resolve, open -the same relative path under the resolved documentation root. - -- [Overview](../../../node_modules/rstack/dist/docs/index.md) -- [Quick start and command overview](../../../node_modules/rstack/dist/docs/guide/quick-start.md) -- [Configuration](../../../node_modules/rstack/dist/docs/guide/configuration.md) -- [API and import paths](../../../node_modules/rstack/dist/docs/guide/api-reference.md) -- [Monorepos](../../../node_modules/rstack/dist/docs/guide/monorepo.md) -- [Testing](../../../node_modules/rstack/dist/docs/guide/testing.md) -- [Formatting](../../../node_modules/rstack/dist/docs/guide/formatting.md) -- CLI commands: [dev](../../../node_modules/rstack/dist/docs/guide/cli/dev.md), - [build](../../../node_modules/rstack/dist/docs/guide/cli/build.md), - [preview](../../../node_modules/rstack/dist/docs/guide/cli/preview.md), - [lib](../../../node_modules/rstack/dist/docs/guide/cli/lib.md), - [doc](../../../node_modules/rstack/dist/docs/guide/cli/doc.md), - [test](../../../node_modules/rstack/dist/docs/guide/cli/test.md), - [lint](../../../node_modules/rstack/dist/docs/guide/cli/lint.md), - [fmt](../../../node_modules/rstack/dist/docs/guide/cli/fmt.md), - [setup](../../../node_modules/rstack/dist/docs/guide/cli/setup.md), and - [staged](../../../node_modules/rstack/dist/docs/guide/cli/staged.md) diff --git a/scripts/prepare-release.js b/scripts/prepare-release.js index 3038f11..0cdec3b 100644 --- a/scripts/prepare-release.js +++ b/scripts/prepare-release.js @@ -1,6 +1,6 @@ #!/usr/bin/env node import { spawn } from 'node:child_process'; -import { copyFile, mkdir, readdir, rm } from 'node:fs/promises'; +import { copyFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'; import path from 'node:path'; const rootDir = path.resolve(import.meta.dirname, '..'); @@ -71,4 +71,10 @@ for (const relativePath of markdownFiles) { await copyFile(path.join(websiteDistDir, relativePath), destination); } -console.log(`Copied ${markdownFiles.length} English Markdown files to ${packageDocsDir}.`); +const llmsTxt = await readFile(path.join(websiteDistDir, 'llms.txt'), 'utf8'); +const packageLlmsTxt = llmsTxt.replace(/\]\(\/(?!\/)/g, '](./'); +await writeFile(path.join(packageDocsDir, 'llms.txt'), packageLlmsTxt); + +console.log( + `Copied ${markdownFiles.length} English Markdown files and llms.txt to ${packageDocsDir}.`, +); From 69fda6b78559bd390dd96eab974e44372e339918 Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 5 Aug 2026 16:50:39 +0800 Subject: [PATCH 6/8] docs(skills): require bundled llms index --- .agents/skills/rstack-cli-best-practices/SKILL.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.agents/skills/rstack-cli-best-practices/SKILL.md b/.agents/skills/rstack-cli-best-practices/SKILL.md index a7a49a5..f9e87c6 100644 --- a/.agents/skills/rstack-cli-best-practices/SKILL.md +++ b/.agents/skills/rstack-cli-best-practices/SKILL.md @@ -14,10 +14,7 @@ installed documentation is the source of truth for the project's Rstack version. 1. Start with `node_modules/rstack/dist/docs/llms.txt`, then read only the linked pages relevant to the task before proposing or making changes. -2. If `llms.txt` is unavailable, start with `node_modules/rstack/dist/docs/index.md` and search the - documentation directory with `rg -n "" node_modules/rstack/dist/docs`. - -3. For exact CLI flags and behavior, also run `rs -h` or `rs -h` when supported. +2. For exact CLI flags and behavior, also run `rs -h` or `rs -h` when supported. If the bundled docs are not available at that path, locate the installed `rstack` package. If they are still unavailable, verify that `rstack` is installed, report the installed version, and use CLI From 84e085bce665d2b33bdb11a60fba7caed20f1079 Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 5 Aug 2026 16:51:29 +0800 Subject: [PATCH 7/8] docs(skills): retain Rstack CLI overview --- .agents/skills/rstack-cli-best-practices/SKILL.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.agents/skills/rstack-cli-best-practices/SKILL.md b/.agents/skills/rstack-cli-best-practices/SKILL.md index f9e87c6..d45977f 100644 --- a/.agents/skills/rstack-cli-best-practices/SKILL.md +++ b/.agents/skills/rstack-cli-best-practices/SKILL.md @@ -5,6 +5,11 @@ description: Guidance for Rstack CLI work involving `rs` commands, `rstack.confi # Rstack CLI Best Practices +Rstack CLI is the `rstack` package, exposed through the `rs` binaries. It provides one CLI, one +config file, and a consistent workflow for the Rstack JavaScript toolchain. + +It covers web app, library, docs, test, lint, formatting, Git hook, and staged-file workflows. + ## Rstack: ALWAYS read installed docs before working Before any Rstack work, find and read the relevant Markdown documentation shipped with the From c3102af74b497acffcb42871c3788a89fb517657 Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 5 Aug 2026 16:57:49 +0800 Subject: [PATCH 8/8] docs(skills): refine bundled docs guidance --- .../skills/rstack-cli-best-practices/SKILL.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/.agents/skills/rstack-cli-best-practices/SKILL.md b/.agents/skills/rstack-cli-best-practices/SKILL.md index d45977f..21940ca 100644 --- a/.agents/skills/rstack-cli-best-practices/SKILL.md +++ b/.agents/skills/rstack-cli-best-practices/SKILL.md @@ -10,17 +10,16 @@ config file, and a consistent workflow for the Rstack JavaScript toolchain. It covers web app, library, docs, test, lint, formatting, Git hook, and staged-file workflows. -## Rstack: ALWAYS read installed docs before working +## ALWAYS read installed docs before working -Before any Rstack work, find and read the relevant Markdown documentation shipped with the -installed `rstack` package. Model knowledge and summaries in this skill can be outdated; the -installed documentation is the source of truth for the project's Rstack version. +Before any Rstack work, find and read the relevant Markdown documentation shipped with the installed `rstack` package. -1. Start with `node_modules/rstack/dist/docs/llms.txt`, then read only the linked pages relevant to - the task before proposing or making changes. +Model knowledge can be outdated; the installed documentation is the source of truth for the project's Rstack version. + +1. Start with `node_modules/rstack/dist/docs/llms.txt`, then read only the linked pages relevant to the task before proposing or making changes. 2. For exact CLI flags and behavior, also run `rs -h` or `rs -h` when supported. -If the bundled docs are not available at that path, locate the installed `rstack` package. If they -are still unavailable, verify that `rstack` is installed, report the installed version, and use CLI -help plus the online Rstack documentation as a fallback. Do not guess from model memory. +If the bundled docs are not available at that path, locate the installed `rstack` package. + +If they are still unavailable, verify that `rstack` is installed, and use CLI help plus the online [Rstack documentation](https://rstack.rs/) as a fallback.