@jstn-sdk/rcs 0.1.0

package/docs/reference/ralph-upstream-baseline.md

@@ -0,0 +1,34 @@
+# Ralph Upstream Semantic Baseline
+
+> Archive compatibility reference: this document tracks lower-level Ralph runtime semantics for parity and migration work. It is not a primary creator-workflow guide.
+
+- Historical upstream repository: https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills
+- Pinned branch ref at retrieval: `main`
+- Pinned commit SHA: `165c3688bfde275560c001a0de4c7563cf82ad69`
+- Retrieved at (UTC): `2026-02-22T06:55:19Z`
+- Baseline file: `skills/ralph/SKILL.md`
+- Historical raw URL: `https://raw.githubusercontent.com/Yeachan-Heo/roblox-ai-os-creator-skills/165c3688bfde275560c001a0de4c7563cf82ad69/skills/ralph/SKILL.md`
+- SHA256 (baseline file content): `2a16d9dd55a78ae9edf192fa36ab8370cb5f2dee4958fc458432429a36000917`
+
+## Semantics extracted from baseline
+
+1. **Iteration semantics**
+   - Ralph is an iterative loop with persisted lifecycle state (`iteration`, `max_iterations`, `current_phase`).
+   - Iteration progress is updated on each pass and moves between execute/verify/fix phases.
+
+2. **Retry semantics**
+   - If verification rejects completion, Ralph keeps running and re-enters fix/verify rather than exiting early.
+   - Ralph is explicitly persistence-first (do not stop at partial completion).
+
+3. **Completion semantics**
+   - Completion requires fresh verification evidence and explicit architect approval.
+   - Terminal success sets `active=false`, `current_phase=complete`, and writes `completed_at`.
+
+4. **Cancellation semantics**
+   - Cancellation is treated as lifecycle terminalization, not silent deletion.
+   - Linked cleanup is expected (`ralph` + linked execution mode cleanup via cancel workflow).
+
+## Audit notes
+
+- This baseline is commit-pinned. Any parity update MUST reference a new commit SHA and hash.
+- The parity mapping for each rule is tracked in `docs/reference/ralph-parity-matrix.md`.

package/docs/reference/rcs-config-schema-routing.md

@@ -0,0 +1,264 @@
+# `.rcs-config.json` model/env routing reference
+
+This page documents the `.rcs-config.json` keys that current RCS code recognizes, with extra detail for **model and environment routing**. Feature-owned settings such as notifications and OpenClaw remain documented near those features, but their supported key shapes are summarized here so this page can act as a safe schema map.
+
+This is a runtime/config reference. Keys such as `team`, `autopilot`, and `ralph` below refer to lower-level execution-mode identifiers, not the primary public creator workflow language. Public onboarding should still lead with `$brief`, `$blueprint`, `$forge`, `$crew`, and `$autoforge`.
+
+Do not add or edit keys unless your installed RCS version recognizes them. Unknown keys are not a stable extension point, and malformed JSON or wrong-shaped sections may be ignored or may fail closed for the feature reading them.
+
+## Where the file is read
+
+Most `.rcs-config.json` readers resolve through the active Codex home:
+
+| Setup shape | Config file | Notes |
+| --- | --- | --- |
+| User scope | `${CODEX_HOME:-~/.codex}/.rcs-config.json` | Default setup shape. `CODEX_HOME` wins when set. |
+| Project scope | `./.codex/.rcs-config.json` | Used by RCS launch paths when `./.rcs/setup-scope.json` says `project` and `CODEX_HOME` is not already set. |
+
+Project-scoped setup also writes `./.codex/config.toml`, `./.codex/hooks.json`, and project-local skills/prompts/agents. User-scoped setup writes the corresponding files under `${CODEX_HOME:-~/.codex}`.
+
+The wiki lifecycle reader is a project-root exception because it runs from hook payload `cwd`: it checks `<root>/.rcs-config.json` first, then `${CODEX_HOME:-~/.codex}/.rcs-config.json`, and falls back to built-in wiki defaults if neither file has a valid `wiki` object. The project-scope Codex-home file `./.codex/.rcs-config.json` still applies when `CODEX_HOME` resolves to `./.codex`; it is not an extra wiki-only lookup path.
+
+`rcs setup --scope project` persists the project-scope choice in `./.rcs/setup-scope.json`; `rcs doctor` prints the resolved setup scope and the Codex home/config paths it is checking.
+
+## Supported top-level keys
+
+Current code recognizes these top-level `.rcs-config.json` keys:
+
+| Top-level key | Supported shape | Primary use |
+| --- | --- | --- |
+| `env` | Object of non-empty string values | Fallback environment values for model routing and helper launch paths. Model-related supported keys are listed below. |
+| `models` | Object of non-empty string values | Mode defaults and low-complexity model aliases. Supported model-routing keys are listed below. |
+| `notifications` | Object | Notification transports, profiles, templates, cooldowns, replies, and OpenClaw/custom aliases. See the notification summary below and the OpenClaw guide for full examples. |
+| `stopHookCallbacks` | Legacy object | Backward-compatible legacy session-end notification config for `telegram` and `discord`; prefer `notifications`. |
+| `promptRouting` | `{ "triage": { "enabled": boolean } }` | Enables/disables advisory triage prompt routing. Missing key defaults to enabled; malformed shape fails closed to disabled. |
+| `autoNudge` | Object | Managed-tmux stall nudge settings. Supported keys: `enabled`, `patterns`, `response`, `delaySec`, `stallMs`, `ttlMs`, and legacy `cooldownMs`. |
+| `wiki` | Object | Project wiki lifecycle settings. Supported keys: `enabled`, `autoCapture`, `maxContextLines`, `staleDays`, `maxPageSize`, `feedProjectMemoryOnStart`. |
+
+### Notification-owned keys
+
+`notifications` supports the following current shapes:
+
+- Global fields: `enabled`, `verbosity` (`verbose`, `agent`, `session`, or `minimal`), `defaultProfile`, `profiles`, `events`, `hookTemplates`, `reply`, `dispatchCooldownSeconds`, and `idleCooldownSeconds`.
+- Platform fields: `discord`, `discord-bot`, `telegram`, `slack`, `webhook`.
+- OpenClaw/custom transport fields: `openclaw`, `custom_webhook_command`, and `custom_cli_command`.
+- Event keys under `events`: `session-start`, `session-stop`, `session-end`, `session-idle`, and `ask-user-question`. Each event can set `enabled`, `messageTemplate`, and platform overrides.
+- `hookTemplates` supports `version`, `enabled`, `events`, and `defaultTemplate`; per-event template config supports `enabled`, `template`, and platform template overrides.
+- `reply` supports `enabled`, `authorizedDiscordUserIds`, `pollIntervalMs`, `rateLimitPerMinute`, `maxMessageLength`, and `includePrefix`.
+- `notifications.openclaw` supports `enabled`, `gateways`, and `hooks`. Gateway entries are HTTP (`type`, `url`, `headers`, `method`, `timeout`) or command (`type`, `command`, `timeout`). Hook entries use `gateway`, `instruction`, and `enabled`.
+
+Use [`docs/openclaw-integration.md`](../openclaw-integration.md) for full notification/OpenClaw examples. Keep credentials in environment variables where possible.
+
+## Supported model/env keys
+
+The model-routing reader supports two top-level objects: `env` and `models`.
+
+```json
+{
+  "env": {
+    "RCS_DEFAULT_FRONTIER_MODEL": "gpt-5.5",
+    "RCS_DEFAULT_STANDARD_MODEL": "gpt-5.4-mini",
+    "RCS_DEFAULT_SPARK_MODEL": "gpt-5.3-codex-spark"
+  },
+  "models": {
+    "default": "gpt-5.5",
+    "team": "gpt-5.5",
+    "team_low_complexity": "gpt-5.3-codex-spark"
+  }
+}
+```
+
+### `env`
+
+`env` provides fallback environment values when the real shell environment did not set them. Shell environment variables still win.
+
+Supported model-related keys:
+
+| Key | Purpose |
+| --- | --- |
+| `RCS_DEFAULT_FRONTIER_MODEL` | Main/frontier default used by leaders and frontier-class roles when no stronger config wins. |
+| `RCS_DEFAULT_STANDARD_MODEL` | Optional standard-lane override. If omitted, standard agents inherit the main/frontier default. |
+| `RCS_DEFAULT_SPARK_MODEL` | Spark/fast-lane default for low-cost exploration and low-complexity workers. |
+| `RCS_SPARK_MODEL` | Legacy spark fallback; prefer `RCS_DEFAULT_SPARK_MODEL` for new config. |
+| `RCS_TEAM_CHILD_MODEL` | Default child model for specific team-child paths that read this setting directly. |
+
+`readConfiguredEnvOverrides()` also passes through other non-empty string values from `env` for launch helpers such as `rcs explore` and `rcs sparkshell`. Treat those as advanced environment overrides, not a schema for per-role model routing.
+
+### `models`
+
+`models` maps mode names to explicit model overrides. Values must be non-empty strings.
+
+Supported model-routing keys:
+
+| Key shape | Purpose |
+| --- | --- |
+| `default` | Fallback for `getModelForMode(mode)` when the requested mode has no explicit key. |
+| Any mode key, for example `team`, `autopilot`, `ralph` | Explicit model for that mode when code calls `getModelForMode("mode")`. |
+| `team_low_complexity` | Low-complexity team/spark model override. |
+| `team-low-complexity` | Alias for `team_low_complexity`. |
+| `teamLowComplexity` | Alias for `team_low_complexity`. |
+
+Do not invent per-role maps such as `models.executor`, `models.architect`, or `models.roles` unless your installed version documents that exact key. Current role routing is based on agent definitions and model class, not arbitrary per-role JSON maps.
+
+## Effective model precedence
+
+### Main/frontier default
+
+The main default resolves in this order:
+
+1. Shell `RCS_DEFAULT_FRONTIER_MODEL`
+2. `.rcs-config.json` `env.RCS_DEFAULT_FRONTIER_MODEL`
+3. Active Codex `config.toml` root `model`
+4. Built-in default: `gpt-5.5`
+
+### Mode-specific model lookup
+
+When code asks for `getModelForMode(mode)`, the mode model resolves in this order:
+
+1. `.rcs-config.json` `models[mode]`
+2. `.rcs-config.json` `models.default`
+3. Main/frontier default above
+
+Example: with `models.team = "gpt-5.5"` and `models.default = "gpt-5.4-mini"`, `team` uses `gpt-5.5`; a mode without its own key uses `gpt-5.4-mini`.
+
+### Standard-lane agents
+
+Standard-lane agents resolve in this order:
+
+1. Shell `RCS_DEFAULT_STANDARD_MODEL`
+2. `.rcs-config.json` `env.RCS_DEFAULT_STANDARD_MODEL`
+3. Main/frontier default
+
+This means standard agents inherit the leader/frontier model unless you opt into a standard-lane override.
+
+### Spark/fast-lane agents
+
+Spark/fast defaults resolve in this order:
+
+1. Shell `RCS_DEFAULT_SPARK_MODEL`
+2. Shell legacy `RCS_SPARK_MODEL`
+3. `.rcs-config.json` `env.RCS_DEFAULT_SPARK_MODEL`
+4. `.rcs-config.json` legacy `env.RCS_SPARK_MODEL`
+5. `.rcs-config.json` `models.team_low_complexity`, `models.team-low-complexity`, or `models.teamLowComplexity`
+6. Built-in default: `gpt-5.3-codex-spark`
+
+For team low-complexity helpers, the exact order depends on the call path: `getSparkDefaultModel()` checks spark env/config values before low-complexity aliases, while `getTeamLowComplexityModel()` checks low-complexity aliases before falling back to the spark default.
+
+## Role/category routing examples
+
+Native agent TOML generation and team model-contract logic use agent definitions with `modelClass` and `reasoningEffort` metadata. Native-agent generation has one important frontier-lane precedence detail: for frontier roles and the `executor` special case, it reads the active Codex `config.toml` root `model` first, then falls back to `getMainDefaultModel()` if that root model is absent. Because `getMainDefaultModel()` is only the fallback in this path, `.rcs-config.json` `env.RCS_DEFAULT_FRONTIER_MODEL` does not override an explicit `config.toml` root `model` for generated native-agent TOML.
+
+Examples:
+
+| Role/category | Examples | Model class behavior |
+| --- | --- | --- |
+| Frontier orchestration | `planner`, `architect`, `critic`, `code-reviewer`, `security-reviewer`, `team-executor`, `vision` | Native-agent generation uses active `config.toml` root `model` first, then the main/frontier default fallback. |
+| Standard worker/review | `debugger`, `quality-reviewer`, `api-reviewer`, `performance-reviewer`, `dependency-expert`, `writer`, `researcher` | Uses the standard-lane default, which inherits main/frontier unless `RCS_DEFAULT_STANDARD_MODEL` is set. |
+| Fast/low-complexity | `explore`, `style-reviewer` | Uses the spark/low-complexity default. |
+| Executor special case | `executor` | Native-agent generation uses active `config.toml` root `model` first, then the main/frontier default fallback; team fallback routing keeps it on the frontier lane. |
+
+Team worker launches add another layer:
+
+1. Explicit `--model ...` inside `RCS_TEAM_WORKER_LAUNCH_ARGS` wins.
+2. Inheritable leader launch model args can be passed through to workers.
+3. If no explicit/inherited model is present, the worker role's default model class selects the fallback model.
+4. Fast roles such as `explore` and role names ending in `-low` use the low-complexity/spark fallback.
+
+Use `rcs team status <team-name> --model-inspect` when you need inspect hints for a running team; the regular status path avoids spending model quota on summaries.
+
+## Reasoning effort: supported places only
+
+`.rcs-config.json` is **not** the general place to configure `model_reasoning_effort`. Do not add keys such as `reasoningEffort`, `modelReasoningEffort`, `reasoning`, or per-role reasoning maps to `.rcs-config.json`.
+
+Supported reasoning-effort surfaces are:
+
+- Active Codex `config.toml` root key: `model_reasoning_effort = "medium"`.
+- `rcs reasoning <low|medium|high|xhigh>`, which edits the active Codex `config.toml`.
+- `rcs --high` and `rcs --xhigh`, which pass `-c model_reasoning_effort="high|xhigh"` to Codex launch.
+- Generated native agent TOML files, where RCS writes each role's built-in `reasoningEffort` metadata.
+- Team worker launch args, for example:
+
+```bash
+RCS_TEAM_WORKER_LAUNCH_ARGS='-c model_reasoning_effort="low" --model gpt-5.3-codex-spark' \
+  rcs team 3:explore "map the config surfaces"
+```
+
+Team runtime can also inject role-default reasoning for Codex workers when no explicit reasoning override is present. Explicit launch args win.
+
+## Starter configs
+
+JSON does not allow comments, so copy only the JSON blocks.
+
+### Cost-saving starter
+
+This keeps orchestration on the frontier default, routes standard workers to a cheaper standard model, and uses the spark lane for exploration/low-complexity work.
+
+```json
+{
+  "env": {
+    "RCS_DEFAULT_FRONTIER_MODEL": "gpt-5.5",
+    "RCS_DEFAULT_STANDARD_MODEL": "gpt-5.4-mini",
+    "RCS_DEFAULT_SPARK_MODEL": "gpt-5.3-codex-spark"
+  },
+  "models": {
+    "default": "gpt-5.4-mini",
+    "team": "gpt-5.5",
+    "team_low_complexity": "gpt-5.3-codex-spark"
+  }
+}
+```
+
+### Max-quality starter
+
+This keeps standard agents inheriting the frontier model by omitting `RCS_DEFAULT_STANDARD_MODEL`, while still preserving a fast spark lane for explicit low-complexity routing.
+
+```json
+{
+  "env": {
+    "RCS_DEFAULT_FRONTIER_MODEL": "gpt-5.5",
+    "RCS_DEFAULT_SPARK_MODEL": "gpt-5.3-codex-spark"
+  },
+  "models": {
+    "default": "gpt-5.5",
+    "team": "gpt-5.5",
+    "autopilot": "gpt-5.5",
+    "ralph": "gpt-5.5",
+    "team_low_complexity": "gpt-5.3-codex-spark"
+  }
+}
+```
+
+## Verifying the effective config
+
+After editing `.rcs-config.json` or `config.toml`, run setup/doctor from the same shell and project shape that will launch RCS:
+
+```bash
+rcs setup
+rcs doctor
+```
+
+`rcs doctor` reports the resolved setup scope, Codex home, config path, hook coverage, prompt/skill/agent availability, and selected prompt-routing status. This verifies install wiring and which config tree RCS is checking.
+
+A green `rcs doctor` is not proof that the active Codex profile can authenticate or run the selected model. For that, use the same shell/profile/project and run:
+
+```bash
+codex login status
+rcs exec --skip-git-repo-check -C . "Reply with exactly RCS-EXEC-OK"
+```
+
+If behavior does not match your config, first confirm whether you are in user or project scope and whether `CODEX_HOME` is overriding the expected Codex home.
+
+## Related docs and source surfaces
+
+- Notification and OpenClaw config: [`docs/openclaw-integration.md`](../openclaw-integration.md)
+- Project wiki config: [`docs/reference/project-wiki.md`](./project-wiki.md)
+- Model routing source: `src/config/models.ts`
+- Notification config source: `src/notifications/config.ts`, `src/notifications/types.ts`, `src/notifications/hook-config-types.ts`
+- OpenClaw config source: `src/openclaw/types.ts`, `src/openclaw/config.ts`
+- Prompt-routing config source: `src/hooks/triage-config.ts`
+- Auto-nudge config source: `src/scripts/notify-hook/auto-nudge.ts`
+- Wiki lifecycle config source: `src/wiki/types.ts`, `src/wiki/lifecycle.ts`
+- Agent role definitions: `src/agents/definitions.ts`
+- Native agent TOML generation: `src/agents/native-config.ts`
+- Team model contract: `src/team/model-contract.ts`
+- Scope/Codex home launch resolution: `src/cli/codex-home.ts`

package/docs/reference/roblox-pre-action-protocol.md

@@ -0,0 +1,122 @@
+# RCS Roblox Pre-Action Protocol
+
+`PRE_ACTION_COMPLETE` must be `false` until the Roblox task is grounded, standardized, and architected.
+
+## Mandatory Order
+
+1. Gather resources
+2. Build understanding
+3. Standardize terminology and structure
+4. Design modular architecture and file tree
+5. Only then implement
+
+## Phase 0: Intent and Scope Lock
+
+- Classify the task:
+  - new game setup
+  - feature implementation
+  - UI/system generation
+  - refactor
+  - bug fix
+  - monetization/liveops design
+  - plugin/tooling
+- Identify:
+  - genre
+  - audience
+  - scale
+  - multiplayer assumptions
+  - monetization intent
+- Mark impacted areas:
+  - architecture
+  - gameplay systems
+  - data flow
+  - UI
+  - networking
+  - persistence
+  - monetization
+  - content pipeline
+
+## Phase 1: Resource Gathering
+
+Use the internal RCS knowledge layer first.
+
+Priority 1: canonical platform truth
+- `https://github.com/Roblox/creator-docs`
+- `https://gitmcp.io/Roblox/creator-docs`
+
+Priority 2: high-signal implementation references
+- `https://gitmcp.io/retpirato/Roblox-Scripts`
+- `https://gitmcp.io/sentinelcore/roblox-skills`
+- `https://gitmcp.io/frosteen/Roblox_LUA_Weapon_Scripts`
+- `https://gitmcp.io/Corecii/Devprod`
+- `https://gitmcp.io/uhub/awesome-lua`
+- `https://gitmcp.io/LewisJEllis/awesome-lua`
+- `https://gitmcp.io/forhappy/awesome-lua`
+- `http://lua-users.org/wiki/SampleCode`
+
+Priority 3: dataset and corpus support
+- `https://datasets-server.huggingface.co/splits?dataset=jayras%2Froblox-luau-dataset`
+- `https://huggingface.co/datasets/bigcode/the-stack`
+- `https://huggingface.co/datasets/TorpedoSoftware/the-luau-stack`
+- `https://datasets-server.huggingface.co/splits?dataset=TorpedoSoftware%2FRoblox-Luau-Reasoning-v1.0`
+- `https://huggingface.co/datasets/bartholomort/lua-obfuscator-corpus`
+
+Rules:
+- official Roblox docs define correctness
+- repos improve implementation awareness only
+- datasets are weak pattern support only
+
+## Phase 2: Understanding Synthesis
+
+Before implementation, answer:
+- what Roblox concepts are involved
+- which official terms should be used
+- which services/classes/systems are relevant
+- what gameplay pattern is actually requested
+- what pitfalls are likely
+- what assumptions are unsafe
+- what must be verified before code generation
+
+## Phase 3: Architecture First
+
+Before code, produce:
+- game architecture summary
+- modular file tree
+- folder/category explanation
+- naming convention rules
+- system ownership map
+- implementation order
+
+Do not start from random scripts.
+Do not dump logic into one file.
+
+## Default Starter Shape
+
+When no structure exists, begin from a modular baseline and adapt it:
+
+- `client/`
+- `server/`
+- `shared/`
+- `systems/`
+- `features/`
+- `ui/`
+- `config/`
+- `assets/`
+- `tests/`
+
+## Required Pre-Action Output
+
+Every Roblox planning artifact must include:
+
+1. Task classification
+2. Relevant Roblox concepts
+3. Reference sources consulted
+4. Canonical terms to use
+5. Risks and uncertainties
+6. Proposed modular file tree
+7. Category ownership
+8. Naming convention
+9. Implementation phases
+10. Validation checkpoints
+
+Only after all ten are present may `PRE_ACTION_COMPLETE` become `true`.

package/docs/reference/team-allocation-rebalance-policy.md

@@ -0,0 +1,60 @@
+# Team Allocation and Rebalance Policy Notes
+
+This note documents the current team-mode allocation/rebalance seam and the constraints that the phased allocation/rebalance upgrade must preserve.
+
+## Current baseline
+
+### Startup allocation
+- `buildTeamExecutionPlan()` splits the top-level request, routes each subtask to a role, then assigns owners via `distributeTasksToWorkers()`.
+- Ownership now flows through `allocateTasksToWorkers()` so startup assignment stays lane-aware instead of pure round-robin (`src/cli/team.ts`, `src/team/allocation-policy.ts`).
+- The current heuristic keeps same-role work grouped when possible, prefers explicit worker-role matches, and falls back to load balancing with lighter-lane bias for blocked work.
+- Atomic tasks still fan out into the fixed aspect trio: implement, test, review/document, but each lane now carries an `allocation_reason` for traceability before CLI output strips the internal field.
+
+### Runtime monitoring
+- `monitorTeam()` already gathers the signals needed for rebalance decisions: task inventory, lease expiry, worker liveness, worker status, heartbeat turn counts, and verification evidence gaps (`src/team/runtime.ts:1212-1420`).
+- The runtime currently turns those signals into recommendations such as:
+  - reassign work from dead workers (`src/team/runtime.ts:1288-1294`)
+  - remind non-reporting workers (`src/team/runtime.ts:1297-1300`)
+  - surface missing PASS/FAIL verification evidence (`src/team/runtime.ts:1313-1321`)
+  - note reclaimed expired claims (`src/team/runtime.ts:1343-1345`)
+- `assignTask()` remains the claim + dispatch gateway, including approval checks and post-claim rollback when worker notification fails (`src/team/runtime.ts:1426-1527`).
+
+### Claim-safety invariants
+- `claimTask()` can only move work into `in_progress` after dependency readiness succeeds and no active claim is held by another worker (`src/team/state/tasks.ts:56-113`).
+- `transitionTaskStatus()` requires the active claim token before terminal completion/failure (`src/team/state/tasks.ts:132-200`).
+- `releaseTaskClaim()` and `reclaimExpiredTaskClaim()` are the safe rollback/requeue paths; both clear owner + claim and return the task to `pending` (`src/team/state/tasks.ts:204-265`).
+
+## Recommended policy seam
+
+To keep the upgrade incremental and reversible, separate **signal collection** from **decision policy**:
+
+1. **Allocation policy**
+   - Input: decomposed tasks, routed roles, worker roster, dependency readiness, and current load.
+   - Output: chosen owner, ranked fallbacks, and a short reason string.
+   - Integration point: replace the round-robin-only decision inside `buildTeamExecutionPlan()` without changing task decomposition or role routing.
+
+2. **Rebalance policy**
+   - Input: the runtime snapshot inputs already assembled by `monitorTeam()`.
+   - Output: structured actions (`noop`, `recommend`, `requeue`, `reassign`) plus rationale.
+   - Integration point: let `monitorTeam()` compute richer actions, but keep `assignTask()` as the only real dispatch path.
+
+## Safety rules for v1
+- Do not steal active work that still has a valid claim lease.
+- Only auto-reassign when work is pending, explicitly released, reclaimed after lease expiry, or attached to a dead/non-recoverable worker.
+- Keep tmux layout and scale-up behavior unchanged for the first milestone.
+- Preserve `.rcs/state/team/...` storage and `rcs team api` contracts.
+- Make every allocation/rebalance decision explainable with a reason string suitable for logs, snapshots, and tests.
+
+## Repo-aware DAG handoff seam
+
+The repo-aware RALPLAN -> Team handoff should enter before `startTeam()` and before worker inbox generation. Keep the decomposition gate as a bounded preflight module that returns normalized startup tasks, an effective worker count, and an inspectable metadata/report payload. Runtime dispatch should remain unchanged: workers still receive tasks through inboxes and must claim through the existing lifecycle APIs.
+
+Preflight allocation may use DAG `filePaths`, `domains`, `lane`, and symbolic dependency metadata to improve owner assignment, but only concrete runtime task IDs should reach `blocked_by` / `depends_on`. Rich metadata belongs in a decomposition report or manifest policy block unless the Team task schema intentionally supports it.
+
+See `docs/contracts/repo-aware-team-dag-decomposition.md` for the detailed artifact precedence, worker-count provenance, dependency remap, and worker-inbox UX contract.
+
+## Review notes
+- The code already has good low-level claim primitives; the main gap is decision logic, not transport.
+- The clearest review risk is letting new heuristics bypass `assignTask()`/claim safety. Any rebalance helper should return a decision, not perform ad-hoc mutation.
+- Startup assignment and runtime rebalance should stay small, explicit policy seams so `src/cli/team.ts` and `src/team/runtime.ts` do not absorb another large block of inline heuristics.
+- `allocation_reason` should remain explainable enough for tests, snapshots, and leader review even if the public task payload hides the internal field after planning.

package/docs/release-body-0.9.0.md

@@ -0,0 +1,104 @@
+# roblox-ai-os-creator-skills v0.9.0
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Yeachan-Heo/roblox-ai-os-creator-skills/v0.9.0/docs/shared/rcs-character-spark-initiative.jpg" alt="RCS character sparked for the Spark Initiative" width="720">
+</p>
+
+`0.9.0` is the Spark Initiative release: RCS now has a stronger native fast path for repository discovery, shell-native inspection, and cross-platform native distribution.
+
+## Highlights
+
+### `rcs explore`
+
+- adds a dedicated read-only exploration entrypoint
+- uses a Rust-backed explore harness
+- keeps shell-native exploration constrained, allowlisted, and read-only
+- supports packaged native resolution plus source/repo-local fallback paths
+
+### `rcs sparkshell`
+
+- adds an operator-facing native shell sidecar
+- supports direct command execution
+- summarizes long output into compact sections
+- supports explicit tmux-pane summarization:
+
+```bash
+rcs sparkshell --tmux-pane %12 --tail-lines 400
+```
+
+### Explore ↔ sparkshell integration
+
+- qualifying read-only shell-native `rcs explore` prompts can route through `rcs sparkshell`
+- fallback behavior remains explicit and hardened
+- guidance/docs/tests were aligned around this contract
+
+### Worker follow-through polish
+
+- worker mailbox guidance now asks for concrete progress updates without implying work should stop after replying
+- inbox/mailbox trigger wording now tells workers to continue assigned or next feasible work after reporting status
+- runtime/bootstrap wording and associated tests were aligned around this behavior
+
+### Release pipeline upgrades
+
+- cross-platform native publishing for:
+  - `rcs-explore-harness`
+  - `rcs-sparkshell`
+- native release manifest generation with per-target metadata
+- packed-install smoke verification in the release workflow
+- `build:full` validated as the one-shot release-oriented build path
+
+## Important Spark Initiative notes
+
+- Users can install RCS normally with `npm install -g roblox-ai-os-creator-skills`.
+- The npm tarball intentionally excludes staged cross-platform native binaries.
+- Tagged releases publish verified native archives for `rcs-explore-harness` and `rcs-sparkshell`.
+- Packaged installs hydrate the matching native binary through `native-release-manifest.json`.
+- CI now hardens the Rust path with explicit toolchain setup, `cargo fmt --all --check`, and `cargo clippy --workspace --all-targets -- -D warnings`.
+
+## Upgrade note
+
+If you use project-scoped RCS installs, rerun:
+
+```bash
+rcs setup --force --scope project
+```
+
+after upgrading so managed config/native-agent paths are refreshed.
+
+## Local release verification summary
+
+Validated locally on `dev` before tagging:
+
+- `node scripts/check-version-sync.mjs --tag v0.9.0`
+- `npm run lint`
+- `npx tsc --noEmit`
+- `npm run check:no-unused`
+- `npm test`
+- `npm run build:full`
+- `npm run test:explore`
+- `npm run test:sparkshell`
+- `node bin/rcs.js doctor`
+- `node bin/rcs.js setup --dry-run`
+- `npm pack --dry-run`
+
+## Notable PRs
+
+- [#782](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/782) — explore routes qualifying read-only shell tasks via sparkshell
+- [#784](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/784) — cross-platform native publishing and release-pipeline follow-through
+- [#785](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/785) — team runtime lifecycle and cleanup hardening
+- [#786](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/786) — nested help routing cleanup
+- [#787](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/787) — centralized RCS default model resolution
+- [#788](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/788) — HUD branch/config loading hardening
+- [#789](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/789) — distribute generated aspect tasks across workers
+- [#793](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/793) — Windows Codex command shim probing fix
+- [#794](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/794) — merge `experimental/dev` into `dev`
+- [#805](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/805) — keep workers running after mailbox replies
+
+## Related issues
+
+- [#781](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/781) — sparkshell summary reasoning hardening
+- [#744](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/issues/744) — lifecycle profile persistence
+- [#745](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/issues/745) — cleanup policy hardening
+- [#746](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/issues/746) — governance split follow-through
+- [#741](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/issues/741) — linked Ralph/team runtime follow-up
+- [#732](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/issues/732) — related team lifecycle follow-up

package/docs/release-body-0.9.1.md

@@ -0,0 +1,41 @@
+# roblox-ai-os-creator-skills v0.9.1
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Yeachan-Heo/roblox-ai-os-creator-skills/v0.9.1/docs/shared/rcs-character-spark-initiative.jpg" alt="RCS character sparked for the Spark Initiative" width="720">
+</p>
+
+`0.9.1` is a targeted Spark Initiative hotfix release.
+
+## Why this release exists
+
+- `v0.9.0` remains historically red.
+- The required packed-install smoke hydration fix landed later on `dev` in PR [#806](https://github.com/Yeachan-Heo/roblox-ai-os-creator-skills/pull/806).
+- `v0.9.1` is the clean superseding release cut from `main` with that fix applied.
+
+## Included fix
+
+### Localize smoke hydration assets
+
+The packed-install smoke workflow now copies and resolves hydration assets from the local smoke workspace so release verification matches packaged-install behavior more reliably.
+
+Changed files:
+- `scripts/smoke-packed-install.mjs`
+- `scripts/__tests__/smoke-packed-install.test.mjs`
+
+## Local release verification summary
+
+Planned local release-critical validation for `0.9.1`:
+
+- `node scripts/check-version-sync.mjs --tag v0.9.1`
+- `npm run lint`
+- `npx tsc --noEmit`
+- `npm run check:no-unused`
+- `npm test`
+- `node --test scripts/__tests__/smoke-packed-install.test.mjs`
+- `npm run build:full`
+- `npm run smoke:packed-install`
+- `npm pack --dry-run`
+
+## Historical note
+
+`v0.9.0` remains historically red; `v0.9.1` is the clean superseding release.