feat(context): add the Rstack context engine

.agents/skills/debug-dev-cycle/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: debug-dev-cycle
+description: Diagnose current Rstack lint or test failures from stored evidence, with an optional user-approved one-shot capture. Use this skill when debugging one current Rslint or Rstest result; use review-context-change to compare two snapshots.
+---
+
+# Debug an Rstack development cycle
+
+1. Call `project_status` first. Treat freshness separately for each producer; a fresh build does
+   not make lint or test evidence fresh.
+2. Match the requested package and producer to `project_status.context.packageRoot` and keep its
+   `contextId`. Deduplicate repeated runs by `contextId`; ask the user to choose only when multiple
+   distinct lint or test contexts match. If none exists, report that there is no stored evidence
+   and continue to the capture choice in step 5.
+3. Prefer existing evidence. When a context exists, use `snapshot_list` with that `contextId` to
+   select a completed `rslint` or `rstest` snapshot, then query `diagnostics_list` or `test_results`.
+4. Report freshness as `fresh`, `stale`, `partial`, or `unknown`, including changed paths when
+   reported. Report completeness separately as `complete` or `partial`, including any reported
+   coverage bounds.
+5. Ask before running `lint_snapshot` or `test_snapshot`. These are explicit executions, not
+   passive queries. For a monorepo package, pass its checkout-relative `packageRoot`; pass
+   `configPath` only to select a nonstandard checkout-relative Rstack config. Without
+   `packageRoot`, capture defaults to the checkout root, and without `configPath`, it uses the
+   ordinary `rstack.config.ts|js|mts|mjs` in the selected package. Never start watch mode.
+6. Surface the first actionable failure with its project, path, test name or rule, and recorded
+   message. Then summarize remaining failures briefly.
+7. When aggregate execution or cross-producer diagnostics would help explain one file, call
+   `code_evidence` with its exact checkout-relative path and the selected `testSnapshotId` or
+   `lintSnapshotId`. Treat each returned axis and its freshness or completeness independently.
+   Check `diagnostics.truncated`; when true, report the returned and total counts before the first
+   actionable items.
+8. When the user asks to select related tests, recommend
+   `rs test list --related <files> --json`; related selection is not an MCP tool.
+
+Use `lint_fix_preview` only when the lint snapshot recorded a preview. Do not apply it. Recommend
+an explicit `rs lint --fix <path>` only when the user wants to make that change.

.agents/skills/release-rstack/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: release-rstack
-description: Create a coordinated release pull request for the `rstack` and `create-rstack` npm packages. Use when asked to prepare, create, or open an rstack package release PR.
+description: Create a coordinated release pull request for the `rstack`, `@rstackjs/context`, and `create-rstack` npm packages. Use when asked to prepare, create, or open an rstack package release PR.
 ---
 
 # Release Rstack
@@ -13,7 +13,8 @@ If the version is missing, ask for it before making changes.
 
 ## Version rules
 
-- Read both package versions before editing. Require the rstack target to be a valid, increasing SemVer version.
+- Read all three package versions before editing. Require the rstack target to be a valid, increasing SemVer version.
+- Keep `@rstackjs/context` on exactly the same version as `rstack`.
 - Keep the package version lines independent. Apply the rstack bump type to the current `create-rstack` version:
   - Patch: increment the patch version.
   - Minor: increment the minor version and reset patch to `0`.
@@ -29,13 +30,13 @@ If the version is missing, ask for it before making changes.
 
 3. Create and switch to `release/v<version>` from the clean default-branch HEAD.
 
-4. Update the `version` field in `packages/rstack/package.json` to `<version>` and the `version` field in `packages/create-rstack/package.json` to the derived `create-rstack` version.
+4. Update the `version` fields in `packages/rstack/package.json` and `packages/context/package.json` to `<version>`. Update the `version` field in `packages/create-rstack/package.json` to the derived `create-rstack` version.
 
 5. In every `packages/create-rstack/template-*/package.json`, set the `rstack` dependency to `^<version>`. Update only that dependency entry and verify every template package manifest uses the same target version.
 
 6. Run `pnpm --filter rstack build:native` to regenerate `packages/rstack/binding.cjs` and `packages/rstack/binding.d.cts` for the new version. Do not edit generated binding files manually.
 
-7. Review the diff and confirm it contains only both package version changes, the template `rstack` dependency updates, and the regenerated binding files above. Verify the two package version changes use the intended matching bump type and no template retains an older rstack version.
+7. Review the diff and confirm it contains only the three package version changes, the template `rstack` dependency updates, and the regenerated binding files above. Verify `rstack` and `@rstackjs/context` have the same target version, `create-rstack` uses the intended matching bump type, and no template retains an older rstack version.
 
 8. Create a commit with this exact message: `release: v<version>`.
 

.agents/skills/review-context-change/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: review-context-change
+description: Review changes between two compatible Rstack lint or test snapshots, including freshness and stored lint fix previews. Use this skill when comparing before-and-after diagnostics or tests; use debug-dev-cycle for one current result.
+---
+
+# Review an Rstack context change
+
+1. Call `project_status` first. Match the requested package to `project_status.context.packageRoot`,
+   deduplicating repeated runs by `contextId` and asking the user to choose only when multiple distinct contexts match. Use
+   `snapshot_list` with that `contextId` and require two compatible completed snapshots for the same
+   producer, context, package root, selected Rstack config, and capture selection. The list is
+   newest-first: pass the older snapshot as `leftSnapshotId` and the newer snapshot as
+   `rightSnapshotId`.
+2. When no compatible pair exists, state which explicit capture supplies each missing snapshot:
+   `lint_snapshot` for an Rslint comparison or `test_snapshot` for an Rstest comparison. Include the
+   checkout-relative `packageRoot` and any nonstandard `configPath`. Ask before running each capture.
+3. Call `snapshot_diff` with `diagnostics` for Rslint or `tests` for Rstest. If it reports
+   incompatibility, explain the listed reasons and stop the comparison.
+4. Report the independent freshness of both snapshots before interpreting the delta. Never imply
+   that partial or unknown evidence covers unobserved source files.
+5. Summarize added, removed, and changed items. Lead with new failures or errors, then resolved
+   items, then lower-severity or timing-only changes.
+6. When aggregate execution or exact-path diagnostics would clarify one changed file, call
+   `code_evidence` with its exact checkout-relative path and the relevant explicit snapshot ID.
+   Keep that point-in-time evidence separate from the snapshot delta.
+   Check `diagnostics.truncated`; when true, report the returned and total counts instead of treating
+   the diagnostic items as exhaustive.
+7. For a changed lint file, call `lint_fix_preview` only when the preview would materially help the
+   review. If the snapshot did not capture one, report that it is unavailable. Treat returned text
+   as review material and never apply it.
+8. Recommend explicit verification appropriate to the change, such as `rs lint <path>`,
+   `rs test <file>`, or `rs test list --related <files> --json`.
+
+Do not run a capture unless the user asks for fresh execution. When they do, reuse the
+checkout-relative `packageRoot` and optional `configPath` for the context under review. Never
+start watch mode.

.superpowers/sdd/2026-08-12-context-branch-simplification/task-3-report.md

@@ -0,0 +1,35 @@
+# Task 3 Report
+
+Status: DONE
+
+## Changes
+
+- Stopped workspace discovery after processing the nearest `.git` root.
+- Canonicalized an existing loaded Rsbuild or Rslib config path once before observer creation.
+- Removed unused stats timings and replaced unbounded metadata intermediates with one-pass bounded
+  asset, chunk, and chunk-file collectors while preserving `BuildMetadataFacet` output.
+- Added high-cardinality valid/invalid metadata, ancestor-workspace, and symlinked-config fixtures.
+
+## TDD evidence
+
+- RED: `pnpm --filter rstack test run tests/context/build.test.ts` failed because `toJson`
+  received `timings: true` in the existing lifecycle and new high-cardinality tests.
+- RED: `pnpm --filter rstack test run tests/context/workspace.test.ts` failed because discovery
+  returned the unrelated ancestor workspace instead of the nearest checkout root.
+- RED: `pnpm --filter rstack test run tests/context/injection.test.ts -t 'canonicalizes a
+symlinked loaded config path'` failed for both app and lib because no context run was captured.
+- GREEN: full build, workspace, and injection test files passed (24 passed).
+
+## Verification
+
+- `pnpm check`: passed with 0 lint errors, 0 type errors, 0 warnings, and no formatting issues.
+- Full assigned-file run: 24 of 24 tests passed after removing the obsolete path/identifier-defense
+  and snapshot-size-cap fixtures from the branch's deleted security scope.
+
+## Commit
+
+`perf(rstack): bound passive build extraction`
+
+## Concerns
+
+None.

.superpowers/sdd/2026-08-12-context-branch-simplification/task-5-brief.md

@@ -0,0 +1,41 @@
+### Task 5: simplify report lookup and align documentation
+
+**Files:**
+
+- Modify: `packages/rstack/src/context/rsdoctor.ts`
+- Modify: `packages/rstack/src/context/report.ts`
+- Modify: `packages/rstack/tests/context/report.test.ts`
+- Modify: `website/docs/en/guide/cli/mcp.mdx`
+- Modify: `website/docs/zh/guide/cli/mcp.mdx`
+- Modify: `docs/rfcs/0001-rstack-context-engine.md`
+- Modify: `docs/superpowers/plans/2026-08-12-rsdoctor-context.md`
+- Modify: `docs/superpowers/plans/2026-08-12-context-branch-simplification.md`
+
+**Interfaces:**
+
+- Report lookup returns a discriminated `missing | file` result instead of requiring callers to
+  inspect exception messages.
+- Report links use ordinary resolved file URIs; no server or command is started.
+
+- [x] **Step 1: write typed-outcome report tests and verify RED**
+
+Cover missing conventional report, one valid sibling, ambiguous siblings, and manifest fallback.
+Assert no control flow depends on an exception message.
+
+- [x] **Step 2: implement the typed boundary**
+
+Use ordinary resolved paths and `stat` to return discriminated outcomes. The report resolver owns
+file lookup directly and consumes typed outcomes.
+
+- [x] **Step 3: align English, Chinese, and RFC status**
+
+Document the exact three-tool Phase 1 surface, direct Rsdoctor JSON contract, optional GUI links, and
+deferred retention. Update both branch planning documents to match the implemented functional
+contract, rewriting only the minimum surrounding sentences needed to keep them readable as
+implementation history.
+
+- [x] **Step 4: run full verification and commit**
+
+Run `pnpm check`, `pnpm check:spell`, `pnpm build`,
+`pnpm --filter rstack build:native`, and `pnpm test`; commit as
+`docs: align the lean context foundation`.

.superpowers/sdd/2026-08-12-context-branch-simplification/task-5-report.md

@@ -0,0 +1,29 @@
+# Task 5 report
+
+## Result
+
+- Report-file lookup now returns a typed `missing | file` outcome from ordinary resolved paths and
+  `stat`, so report selection no longer branches on exception text.
+- Rsdoctor artifact validation now returns the normalized data-file path directly; the previous
+  closure-bearing report helper is gone.
+- Report selection still prefers the conventional sibling HTML report, then one unambiguous sibling
+  HTML file, then the workspace manifest, and otherwise returns the structured analysis next action.
+- English, Chinese, the RFC, and both implementation plans now describe the exact three-tool Phase 1
+  surface, direct Rsdoctor JSON results, optional GUI links, and deferred destructive retention.
+
+## TDD evidence
+
+- RED: `pnpm --filter rstack test -- tests/context/report.test.ts` failed at the new typed-missing
+  assertion because `resolveReportFile` did not exist.
+- GREEN: the same focused command passed after the typed lookup was implemented: 313 passed and 1
+  skipped across 314 Rstack tests.
+
+## Verification
+
+Repository-required sequence:
+
+- `pnpm check` — passed with 0 lint errors, 0 type errors, and 0 warnings.
+- `pnpm check:spell` — passed with 0 spelling issues and no heading-case issues.
+- `pnpm build` — passed for `rstack` and `create-rstack`.
+- `pnpm --filter rstack build:native` — passed.
+- `pnpm test` — passed: Rstack 313 passed and 1 skipped; create-rstack 28 passed.