@jstn-sdk/rcs 0.1.0

package/docs/readme/README.ja.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.ko.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.md

@@ -0,0 +1,53 @@
+---
+title: README translations
+description: Index and maintenance guidance for localized Roblox Creator Skills README files
+author: JustineDevs
+ms.date: 2026-04-04
+ms.topic: reference
+keywords:
+  - readme
+  - translations
+  - localization
+  - documentation
+estimated_reading_time: 2
+---
+
+## Purpose
+
+This folder holds the localized README files for Roblox Creator Skills.
+
+The repository root keeps only the canonical `README.md` so the top level stays focused on the primary entry point, package metadata, and project-wide documents.
+
+## Available translations
+
+| Language            | File              |
+|---------------------|-------------------|
+| Deutsch             | [README.de.md](./README.de.md)       |
+| English             | [../../README.md](../../README.md)   |
+| Español             | [README.es.md](./README.es.md)       |
+| Français            | [README.fr.md](./README.fr.md)       |
+| Italiano            | [README.it.md](./README.it.md)       |
+| Polski              | [README.pl.md](./README.pl.md)       |
+| Português           | [README.pt.md](./README.pt.md)       |
+| Русский             | [README.ru.md](./README.ru.md)       |
+| Türkçe              | [README.tr.md](./README.tr.md)       |
+| Tiếng Việt          | [README.vi.md](./README.vi.md)       |
+| Ελληνικά            | [README.el.md](./README.el.md)       |
+| 日本語              | [README.ja.md](./README.ja.md)       |
+| 한국어              | [README.ko.md](./README.ko.md)       |
+| 简体中文            | [README.zh.md](./README.zh.md)       |
+| Українська          | [README.uk.md](./README.uk.md)       |
+| 繁體中文            | [README.zh-TW.md](./README.zh-TW.md) |
+
+## Maintenance rules
+
+* Treat `../../README.md` as the canonical source.
+* Add new README translations in this folder, not at the repository root.
+* Keep the language list synchronized between the canonical README and each localized variant.
+* Keep relative links valid from `docs/readme/`.
+* Prefer updating existing translations instead of introducing duplicate files or alternate naming schemes.
+
+## Related docs
+
+* Localized OpenClaw guides live one level up in `../`.
+* The canonical project entry point remains `../../README.md`.

package/docs/readme/README.pl.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.pt.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.ru.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.tr.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.uk.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.vi.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.zh-TW.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/readme/README.zh.md

@@ -0,0 +1,27 @@
+# Roblox Creator Skills (RCS)
+
+This localized README is intentionally condensed for the strict v0.1.0 ship pass.
+Use the canonical checked-in docs below for the current product surface.
+
+- Package: `@jstn-sdk/rcs`
+- Repository: `https://github.com/JustineDevs/roblox-ai-os`
+- Getting started: [../getting-started.html](../getting-started.html)
+- Skills reference: [../skills.html](../skills.html)
+- Integrations: [../integrations.html](../integrations.html)
+- Canonical README: [../../README.md](../../README.md)
+
+## Canonical Creator Workflow
+
+`$brief` -> `$blueprint` -> `$forge` / `$crew` -> `$autoforge`
+
+For Roblox implementation work, the mandatory pre-action gate applies before any code generation:
+- gather references
+- build understanding
+- standardize terms
+- design modular file tree architecture
+- only then implement
+
+See:
+- [../../README.md](../../README.md)
+- [../skills.html](../skills.html)
+- [../reference/roblox-pre-action-protocol.md](../reference/roblox-pre-action-protocol.md)

package/docs/reference/player-psychology-command-surfaces.md

@@ -0,0 +1,30 @@
+# RCS Psychology Command Surfaces
+
+## Briefing
+
+- `$brief:audience` -> Player Motivation Profile
+- `$brief:motivation` -> Motivation Matrix
+
+## Blueprinting
+
+- `$blueprint:psych` -> Player Psychology Blueprint
+- `$blueprint:loop` -> Core Loop Map
+- `$blueprint:retention` -> Retention Design Sheet + Weekly LiveOps Plan
+- `$blueprint:social` -> Social Retention Spec
+
+## Forging
+
+- `$forge:reward-loop` -> Reward Loop Spec
+- `$forge:daily-loop` -> Daily Loop Spec
+- `$forge:event-loop` -> Event / FOMO Plan
+- `$forge:progression` -> Progression Ladder
+- `$forge:status` -> Prestige / Status Spec
+- `$forge:fomo` -> Fair Urgency Review
+- `$forge:mastery` -> Mastery Depth Spec
+- `$forge:community` -> Community Stickiness Spec
+
+Each command should produce:
+- a creator-usable artifact,
+- explicit Roblox-fit notes,
+- fairness and burnout guardrails where relevant,
+- concrete mechanic/UI/economy guidance instead of motivational prose.

package/docs/reference/player-psychology-framework.md

@@ -0,0 +1,64 @@
+# RCS Player Psychology Framework
+
+RCS designs Roblox experiences from **player desire backward**. Start with the dominant desire, then shape loops, rewards, UX feedback, social structure, economy pressure, and LiveOps cadence around that desire.
+
+## Driver Map
+
+### 1. Progression
+- Player desire: visible growth, more power, more reach, more unlocked possibility.
+- In-game mechanic patterns: XP bars, level ladders, unlock tracks, rebirth/prestige loops, evolving tools, widening territory.
+- UI and feedback patterns: progress bars, claim moments, milestone unlock toasts, tier previews, next-goal surfaces.
+- Economy implications: acceleration items, catch-up multipliers, long-term sinks, inflation pressure if rewards scale too fast.
+- Retention implications: strong D1/D7 pull when next-step goals are obvious and achievable.
+- Monetization implications: boosts, storage, queue speed, automation, cosmetic milestone packs.
+- Abuse and risk notes: fake progress, dead levels, impossible grind walls, power compression.
+- Roblox-fit notes: players switch experiences fast, so the first upgrade payoff must arrive early.
+
+### 2. Status
+- Player desire: social proof, flex, recognition, identity, rarity.
+- In-game mechanic patterns: titles, rare cosmetics, leaderboard placement, profile badges, visible pets, housing/trophy showcases.
+- UI and feedback patterns: podiums, inspection panels, showcase slots, rarity color systems, visible titles in-world.
+- Economy implications: prestige sinks, trade-value volatility, cosmetic inflation if rare rewards become common.
+- Retention implications: stronger return when status stays socially visible and meaningfully scarce.
+- Monetization implications: cosmetics, display slots, premium profile surfaces, event exclusives.
+- Abuse and risk notes: whale-only flex, unreadable rarity ladders, invisible status that players cannot actually show off.
+- Roblox-fit notes: status works best when other players can see it quickly in hubs, parties, or match lobbies.
+
+### 3. FOMO
+- Player desire: urgency, novelty, being present for the thing that matters now.
+- In-game mechanic patterns: timed events, rotating shops, featured quests, comeback rewards, seasonal ladders.
+- UI and feedback patterns: countdowns, event tabs, re-entry reminders, clearly stated end times, progress-before-expiry.
+- Economy implications: demand spikes, hoarding, speculative pricing, burnout if cadence is relentless.
+- Retention implications: strong short-term spikes, weaker long-term trust if players feel punished for missing days.
+- Monetization implications: event passes, limited cosmetics, time-boxed bundles, convenience accelerators.
+- Abuse and risk notes: manipulative timers, impossible completion windows, unfair exclusivity, loss aversion overload.
+- Roblox-fit notes: keep urgency legible and fair because many players arrive in short bursts and bounce quickly.
+
+### 4. Mastery
+- Player desire: skill expression, optimization, discovery, competence, outplay moments.
+- In-game mechanic patterns: combo systems, build paths, routing optimization, combat tech, efficiency puzzles, boss patterns.
+- UI and feedback patterns: damage readouts, timing ratings, replayable challenge goals, analytics screens, transparent depth.
+- Economy implications: high-skill farms can outpace sinks; mastery loops need reward caps or prestige resets.
+- Retention implications: strong for long-tail retention when depth keeps opening rather than collapsing into solved grind.
+- Monetization implications: loadout slots, training utilities, cosmetics for proven skill, not raw pay-to-win power.
+- Abuse and risk notes: hidden math, unreadable systems, low-skill players hard-walled by complexity.
+- Roblox-fit notes: fast-to-fun onboarding matters; start with a simple loop, then layer depth.
+
+### 5. Community
+- Player desire: belonging, co-presence, teamwork, shared identity, shared goals.
+- In-game mechanic patterns: parties, guilds, trading, co-op raids, shared housing, clan goals, visit loops, invite rewards.
+- UI and feedback patterns: party presence, clan chat, “friends online” cues, group progress boards, visible social prompts.
+- Economy implications: player-to-player value exchange, gifting risk, anti-abuse trade controls, social sink opportunities.
+- Retention implications: often the strongest sticky layer because players return for people, not only systems.
+- Monetization implications: group cosmetics, guild upgrades, social spaces, shared event tracks, gifting.
+- Abuse and risk notes: spam invites, shallow social chores, exploit-prone trading, guild deadweight loops.
+- Roblox-fit notes: Roblox is socially native; social mechanics should reduce friction to playing together fast.
+
+## Healthy Design Rules
+
+- Fast to fun beats front-loaded tutorial weight.
+- Reward clarity beats feature count.
+- Social presence should reduce friction, not create spam.
+- FOMO should create relevance, not punishment.
+- Monetization should amplify desire-aligned systems, not replace them.
+- Every loop needs a fail state, recovery path, and burnout guardrail.

package/docs/reference/project-wiki.md

@@ -0,0 +1,79 @@
+# Project wiki (RCS-native backport)
+
+This note captures the approved RCS-native shape for the project wiki backport.
+It is intentionally **not** a literal OMC port.
+
+## Core shape
+
+- Keep the reusable wiki domain under `src/wiki/*`.
+- Expose wiki operations from a dedicated MCP server at `src/mcp/wiki-server.ts`.
+- Register the server as `rcs_wiki`.
+- Keep wiki storage under `.rcs/wiki/`.
+- Do **not** add vector embeddings; query stays keyword/tag based.
+
+## Config + generator contract
+
+`rcs setup` / the config generator should own the dedicated wiki MCP block:
+
+```toml
+[mcp_servers.rcs_wiki]
+command = "node"
+args = ["<repo>/dist/mcp/wiki-server.js"]
+enabled = true
+```
+
+The bootstrap/config path should treat `rcs_wiki` as a first-party RCS server
+alongside the existing built-ins, while keeping the diff small and idempotent.
+
+## Storage contract
+
+Wiki state is project-local and should live under:
+
+- `.rcs/wiki/*.md` — content pages
+- `.rcs/wiki/index.md` — generated catalog
+- `.rcs/wiki/log.md` — append-only operation log
+
+Guardrails that must stay true:
+
+- reserved-file guard for `index.md` and `log.md`
+- Unicode-safe slugging
+- CRLF-safe frontmatter parsing
+- single-pass unescape for escaped newlines
+- punctuation filtering during tokenization
+- CJK + accented-Latin tokenization support
+
+The docs and code should never regress back to `.omc/wiki/`.
+
+## Lifecycle + hook contract
+
+- `SessionStart` stays **native** and **bounded**.
+  - It may read `.rcs/wiki/` and surface brief context when the wiki already exists.
+  - It should stay read-mostly and must not block startup on heavy writes.
+- `SessionEnd` stays **runtime-fallback** and **non-blocking**.
+  - Best-effort capture is okay.
+  - Missing wiki state should degrade to a no-op.
+- Literal `PreCompact` parity is **deferred in v1** unless an RCS-native seam is proven clean.
+
+## Routing contract
+
+Wiki access should be explicit:
+
+- prefer `$wiki`
+- allow clear task verbs such as `wiki query`, `wiki add`, `wiki read`, `wiki delete`, `wiki ingest`, and `wiki lint`
+- avoid implicit bare `wiki` noun activation in prompt routing
+
+This keeps the routing surface specific enough to avoid false positives from ordinary prose.
+
+## MCP tool surface
+
+The dedicated `rcs_wiki` server should expose the seven stabilized wiki tools:
+
+- `wiki_ingest`
+- `wiki_query`
+- `wiki_lint`
+- `wiki_add`
+- `wiki_list`
+- `wiki_read`
+- `wiki_delete`
+
+These tools should operate only on `.rcs/wiki/` and keep lifecycle behavior bounded.

package/docs/reference/psychology-example-mastery-combat.md

@@ -0,0 +1,7 @@
+# Example: Mastery-Driven Combat / Strategy
+
+- Use `$brief:motivation` to rank mastery first, then status and community.
+- Use `$blueprint:psych` to map player desire to outplay, build optimization, and ranked recognition.
+- Use `$forge:mastery` for move tech, counters, build branches, and challenge ladders.
+- Use `$forge:status` for visible ranked emblems, seasonal titles, and replay highlights.
+- Use `$forge:community` for duos, guild scrims, shared training, and spectating presence.

package/docs/reference/psychology-example-simulator-farming.md

@@ -0,0 +1,7 @@
+# Example: Simulator / Farming
+
+- Use `$brief:audience` to target relaxed collectors who want visible farm growth in 5-15 minute sessions.
+- Use `$blueprint:loop` to define plant -> harvest -> upgrade -> expand -> rebirth -> return.
+- Use `$forge:progression` to build seeds, tool tiers, multipliers, and prestige resets.
+- Use `$forge:daily-loop` for rotating crops, weather boosts, and comeback fertiliser packs.
+- Use `$forge:community` for neighbour bonuses, shared markets, and co-op harvest events.

package/docs/reference/psychology-example-social-roleplay.md

@@ -0,0 +1,7 @@
+# Example: Social Roleplay / Community
+
+- Use `$brief:motivation` to rank community + status above mastery.
+- Use `$blueprint:social` to define parties, friend-presence loops, houses, clubs, jobs, and gifting.
+- Use `$forge:status` for titles, cosmetics, room showcases, and visible club ranks.
+- Use `$forge:event-loop` for themed weekends, town festivals, and comeback-exclusive decor.
+- Use `$forge:fomo` to keep urgency fair with previews, reruns, and non-punitive catch-up.

package/docs/reference/psychology-rubric-healthy-retention.md

@@ -0,0 +1,13 @@
+# Rubric: Healthy vs Manipulative Retention
+
+Pass when:
+- return motive is clear without forced daily punishment
+- comeback hooks help absent players recover
+- timers are legible and fair
+- monetization does not gate basic dignity or understanding
+
+Fail when:
+- streak loss is the main motivator
+- completion windows are unrealistic
+- players are punished for short sessions
+- monetization turns frustration into the intended funnel

package/docs/reference/psychology-rubric-mastery-depth.md

@@ -0,0 +1,11 @@
+# Rubric: Mastery Depth
+
+Pass when:
+- the skill ceiling rises over time
+- players can learn, optimize, and express preference
+- analytics or feedback help skilled play feel legible
+
+Fail when:
+- the system is solved immediately
+- depth is hidden behind unreadable math
+- only grind, not learning, drives outcomes

package/docs/reference/psychology-rubric-progression-clarity.md

@@ -0,0 +1,12 @@
+# Rubric: Progression Clarity
+
+Pass when:
+- next milestone is visible
+- upgrade payoffs arrive early
+- grind length matches Roblox session reality
+- resets/prestige loops create fresh aspiration
+
+Fail when:
+- the first reward takes too long
+- level ups do not change play
+- progression is numerically larger but experientially flat

package/docs/reference/psychology-rubric-social-value-vs-spam.md

@@ -0,0 +1,11 @@
+# Rubric: Social Value vs Spam Loops
+
+Pass when:
+- social systems help players find, join, and stay with others quickly
+- group play creates real strategic or emotional value
+- invites and reminders are bounded and useful
+
+Fail when:
+- invites are noisy or compulsory
+- “social” systems are just reward chores
+- guilds/parties exist with no meaningful shared loop

package/docs/reference/psychology-rubric-status-visibility.md

@@ -0,0 +1,11 @@
+# Rubric: Status Visibility
+
+Pass when:
+- prestige is visible to other players in natural social spaces
+- rarity/readability are clear
+- status rewards feel earned or aspirational
+
+Fail when:
+- flex is invisible
+- status only signals spending
+- rare items flood so fast that prestige collapses

package/docs/reference/ralph-parity-matrix.md

@@ -0,0 +1,25 @@
+# Ralph Upstream → RCS Parity Matrix
+
+> Archive compatibility reference: this matrix documents lower-level Ralph runtime parity work. The canonical public creator workflow remains `$brief -> $blueprint -> $forge / $crew -> $autoforge`.
+
+Baseline source: `docs/reference/ralph-upstream-baseline.md` (`165c3688bfde275560c001a0de4c7563cf82ad69`)
+
+| Rule ID | Upstream semantic rule | RCS implementation point(s) | Status | Verification reference |
+|---|---|---|---|---|
+| R1 | Ralph iterations are persisted (`iteration`, `max_iterations`, phase progression). | `src/mcp/state-server.ts` (`state_write`), `src/cli/__tests__/session-scoped-runtime.test.ts` | adopted | V1, V4 |
+| R2 | Legacy phase labels must be normalized to canonical Ralph phases. | `src/mcp/state-server.ts` (Ralph phase normalizer), `src/mcp/__tests__/state-server-ralph-phase.test.ts` | adapted | V4 |
+| R3 | Completion is terminal (`active=false`, terminal phase, `completed_at`). | `src/cli/index.ts` (`cancelModes` terminalization), notify/team sync path in `scripts/notify-hook.js` | adopted | V5, V7 |
+| R4 | Cancellation propagates to linked mode state (Ralph ↔ Ultrawork/Ecomode/Team). | `src/cli/index.ts` linked cancel handling, `scripts/notify-hook.js` team→ralph terminal sync | adapted | V6, V7 |
+| R5 | Current session scope is authoritative when active session exists; same-Codex-session continuation may migrate a single active Ralph only into an otherwise empty current session scope. Existing current-scope Ralph files are not auto-replaced. Root is compatibility fallback. | `src/mcp/state-paths.ts`, `src/hud/state.ts`, `src/cli/index.ts`, `scripts/notify-hook.js` | adapted | V1, V2, V8 |
+| R6 | Legacy PRD/progress artifacts need deterministic one-way migration into canonical files. | `src/ralph/persistence.ts`, `src/ralph/__tests__/persistence.test.ts` | adapted | V3 |
+| R7 | Release is blocked if contract scenarios are not covered by tests/docs gate. | `docs/qa/ralph-persistence-gate.md`, `src/verification/__tests__/ralph-persistence-gate.test.ts` | adopted | V10 |
+| R8 | Upstream internal agent-tier policy text should remain informational only. | docs and skills text only; no runtime behavior coupling | out-of-scope | N/A |
+
+## Status legend
+
+- **adopted**: behavior implemented directly in RCS runtime.
+- **adapted**: behavior implemented with RCS-specific contract/scope adjustments.
+- **out-of-scope**: documented but intentionally not implemented as runtime behavior.
+
+
+References: `docs/contracts/ralph-state-contract.md`, `docs/contracts/ralph-cancel-contract.md`, `docs/qa/ralph-persistence-gate.md`