@jstn-sdk/rcs 0.1.0

package/docs/troubleshooting.md

@@ -0,0 +1,120 @@
+# Troubleshooting execution readiness
+
+Use this page when RCS appears installed but real Codex execution still fails.
+
+## Install success vs real execution success
+
+`rcs setup` and `rcs doctor` validate RCS's local install surface: prompts, skills, AGENTS scaffolding, config files, hooks, and runtime prerequisites. They do not guarantee that the active Codex profile can authenticate and complete a model request.
+
+After `rcs doctor`, run a real smoke test from the same shell, HOME, and project directory you will use for RCS:
+
+```bash
+codex login status
+rcs exec --skip-git-repo-check -C . "Reply with exactly RCS-EXEC-OK"
+```
+
+Treat the boundary this way:
+
+- Codex plugin install/discovery may cache `roblox-ai-os-creator-skills` under `${CODEX_HOME:-~/.codex}/plugins/cache/$MARKETPLACE_NAME/roblox-ai-os-creator-skills/$VERSION/` (with `local` possible as a version identifier for local installs). That confirms a marketplace/plugin artifact; the packaged plugin includes plugin-scoped companion metadata for MCP servers and apps, while native/runtime hooks remain setup-owned, so it is still not the full RCS runtime setup.
+- Plugin install/discovery is not a replacement for `npm install -g roblox-ai-os-creator-skills` plus `rcs setup`; legacy setup mode installs native agents and prompts, while plugin setup mode relies on plugin discovery for bundled skills and archives/removes legacy RCS-managed prompts/native-agent TOMLs so stale role files cannot shadow plugin behavior.
+- `rcs doctor` green: install and local runtime wiring look sane.
+- `codex login status` green: the active Codex profile can see login state.
+- `rcs exec ...` returns `RCS-EXEC-OK`: real execution, auth, provider routing, and current working-directory assumptions are working together.
+
+## Green doctor, but `rcs exec` fails with auth errors
+
+Common failure strings include `401 Unauthorized`, `Missing bearer or basic authentication in header`, or `Incorrect API key provided`.
+
+Check the active runtime profile, not only your normal login shell:
+
+1. Print `HOME` and `CODEX_HOME` in the shell that launches RCS.
+2. Confirm that the active `~/.codex` or `CODEX_HOME` contains the expected auth and `config.toml`.
+3. Re-run `codex login status` from that same shell.
+
+Custom HOME, container, profile, CI, and service-user environments often have a different `~/.codex` from the machine's main user. A working Codex setup in one home does not automatically make another home ready.
+
+## Local proxy or `openai_base_url` mismatch
+
+If your setup depends on an OpenAI-compatible local proxy or gateway, verify that the active runtime config contains the matching base URL:
+
+```toml
+openai_base_url = "http://localhost:8317/v1"
+```
+
+Use your actual proxy URL. If the profile-local `~/.codex/config.toml` is missing `openai_base_url`, Codex may send the proxy-issued key to the default endpoint. That can make setup and doctor look fine while real execution fails with 401-style auth errors.
+
+## Stale `doctor --team` or dead tmux session state
+
+`rcs doctor --team`, `rcs team resume`, or startup diagnostics can fail when a previous team state references a tmux session that no longer exists. The state may mention `resume_blocker`, or the dead session may be recorded under `.rcs/state/team/<team-name>/config.json` or `manifest.v2.json`.
+
+If the team is intentionally abandoned and no live tmux session remains, clean it up with:
+
+```bash
+rcs team shutdown <team-name> --force --confirm-issues
+rcs cancel
+rcs doctor --team
+```
+
+Do not force-shutdown a team that may still have useful live panes or worker state. Prefer `rcs team status <team-name>` and `tmux ls` first when unsure.
+
+## Shift+Enter submits instead of inserting a newline in tmux-backed RCS sessions
+
+This is usually **not** a net-new RCS feature gap.
+
+RCS already carries the tmux-side preservation work from issue `#1271` / PR `#1273` (`4405f582`, “Preserve Shift+Enter inside tmux-backed RCS launches”), and current `dev` still enables tmux `extended-keys=always` around RCS-owned Codex launch paths:
+
+- in-tmux launches wrap Codex with `withTmuxExtendedKeys(...)` in `src/cli/index.ts`
+- detached tmux launches acquire the same protection through the detached leader bootstrap/cleanup path in `src/cli/index.ts`
+- regression tests still cover the enable/restore/lease behavior in `src/cli/__tests__/index.test.ts`
+
+So if `Shift+Enter` still behaves like plain `Enter`, the narrowest likely causes are:
+
+1. **tmux is not actually forwarding extended keys for the reporter's terminal path**
+   - tmux only forwards the richer key event when the attached terminal is detected as supporting extended keys
+   - `tmux show -gv extended-keys` can say `always`, but forwarding can still fail if the terminal capability is missing or not detected
+2. **the reporter is not in the RCS-owned tmux launch path**
+   - for example, reproducing in a different pane/session than the one RCS launched or after attaching through a different client path
+3. **terminal-specific capability mismatch**
+   - some terminals need an explicit tmux `terminal-features` hint for `extkeys`
+
+### Operator checks
+
+Run these from the same tmux client/session where the failure happens:
+
+```bash
+tmux show -gv extended-keys
+tmux info | grep extkeys
+tmux show -gv terminal-features
+printf '%s\n' "$TERM" "$TERM_PROGRAM"
+```
+
+Expected first check: `always` while RCS is actively running Codex in that tmux-managed path.
+
+If `extended-keys` is **not** `always` during the failing session, that points to an RCS launch-path bug/regression.
+
+If `extended-keys` **is** `always`, but `Shift+Enter` still submits, the likely problem is terminal capability discovery or upstream Codex terminal-input interpretation rather than RCS submission logic.
+
+### Typical environment fix
+
+If your terminal supports extended keys but tmux does not detect it automatically, add an `extkeys` feature hint in `~/.tmux.conf` and restart tmux:
+
+```tmux
+set -as terminal-features ',xterm-256color:extkeys'
+```
+
+Adjust the terminal pattern if your client advertises a different terminfo name.
+
+### Maintainer triage guidance
+
+- **Open a code fix** only if you can show current `dev` fails to set `extended-keys=always` on the live RCS-owned tmux launch path.
+- **Close as environment limitation** if current `dev` sets the tmux option correctly but the reporter's terminal path still does not forward the richer key event.
+- **Prefer a docs follow-up** when the root problem is discoverability/operator guidance rather than a broken RCS codepath.
+
+## `rcs explore` fallback boundaries
+
+`rcs explore` has two intentionally bounded fallback paths:
+
+- **Sparkshell backend fallback**: qualifying shell-native prompts (for example `git log --oneline`) try `rcs sparkshell` first. If that backend is unavailable or incompatible, stderr reports `sparkshell backend unavailable ... Falling back to the explore harness` before the harness runs.
+- **Model fallback inside the explore harness**: the harness tries the configured spark model first and then the configured fallback/standard model only if spark fails. This changes the cost/behavior boundary, so stderr emits structured attempt metadata such as `fallback-attempt=model from=... to=... reason=spark_attempt_failed exit=...`. The stdout notice `## RCS Explore fallback` is emitted only after successful fallback output.
+
+A harness limitation is different from fallback. If the harness cannot answer safely (unsupported platform, missing native binary for a packaged install, missing Rust toolchain in a checkout, or a non-shell-only task), it should report the limitation and stop or ask the caller to use the richer normal path; it should not silently broaden tools or model behavior.

package/docs/wiki-feature.md

@@ -0,0 +1,35 @@
+# RCS Wiki
+
+RCS Wiki is a compiled markdown knowledge layer for agents.
+
+## What it is
+
+- local project knowledge stored under `.rcs/wiki/`
+- markdown-first and search-first
+- designed for agentic retrieval workflows, not vector-first RAG
+
+## Core user surfaces
+
+- `rcs wiki add`
+- `rcs wiki query`
+- `rcs wiki lint`
+- `rcs wiki refresh`
+- `rcs wiki list`
+- `rcs wiki read`
+- `rcs wiki delete`
+
+## Retrieval model
+
+- Wiki pages are queried first when useful
+- `rcs explore` can inject wiki-first context before broader repository search
+- repository search remains the fallback when wiki evidence is weak or missing
+
+## Lifecycle model
+
+- SessionStart can inject compact wiki context through the native hook path
+- SessionEnd can capture session-log pages through the runtime cleanup path
+
+## Constraints
+
+- no vector embeddings required
+- wiki is local project state, not source-controlled product code

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "@jstn-sdk/rcs",
+  "version": "0.1.0",
+  "description": "Roblox Creator Skills runtime and workflow layer for Codex CLI",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "rcs": "dist/cli/rcs.js"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/cli/rcs.js', 0o755)\"",
+    "build:explore": "cargo build -p rcs-explore-harness",
+    "build:full": "npm run build && npm run build:explore:release && npm run build:sparkshell",
+    "build:explore:release": "node dist/scripts/build-explore-harness.js",
+    "check:no-unused": "tsc -p tsconfig.no-unused.json",
+    "clean:native-package-assets": "node dist/scripts/cleanup-explore-harness.js",
+    "dev": "tsc --watch",
+    "lint": "biome lint src",
+    "prepack": "npm run build && npm run verify:native-agents && npm run sync:plugin && npm run verify:plugin-bundle && npm run clean:native-package-assets",
+    "postinstall": "node src/scripts/postinstall-bootstrap.js",
+    "setup": "node dist/cli/rcs.js setup",
+    "doctor": "node dist/cli/rcs.js doctor",
+    "ask:claude": "./src/scripts/ask-claude.sh",
+    "ask:gemini": "./src/scripts/ask-gemini.sh",
+    "test:explore": "cargo test -p rcs-explore-harness && node --test dist/cli/__tests__/explore.test.js dist/hooks/__tests__/explore-routing.test.js dist/hooks/__tests__/explore-sparkshell-guidance-contract.test.js",
+    "test:team:cross-rebase-smoke": "npm run build && node --test dist/team/__tests__/cross-rebase-smoke.test.js",
+    "test:team:cross-rebase-smoke:compiled": "node --test dist/team/__tests__/cross-rebase-smoke.test.js",
+    "test:team:worker-runtime-identity": "npm run build && npm run test:team:worker-runtime-identity:compiled",
+    "test:team:worker-runtime-identity:compiled": "node --test dist/team/__tests__/worker-runtime-identity.test.js",
+    "test:recent-bug-regressions": "npm run build && npm run test:recent-bug-regressions:compiled",
+    "test:recent-bug-regressions:compiled": "node --test dist/hooks/__tests__/keyword-detector.test.js dist/scripts/__tests__/codex-native-hook.test.js dist/cli/__tests__/launch-fallback.test.js dist/team/__tests__/runtime.test.js dist/team/__tests__/hardening-e2e.test.js",
+    "test:plugin-boundaries:compiled": "node --test dist/cli/__tests__/codex-plugin-layout.test.js dist/cli/__tests__/package-bin-contract.test.js dist/cli/__tests__/setup-hooks-shared-ownership.test.js dist/catalog/__tests__/plugin-bundle-ssot.test.js",
+    "test:node": "node dist/scripts/run-test-files.js dist",
+    "test:node:cross-platform": "npm run test:node",
+    "test": "npm run build && npm run verify:native-agents && npm run verify:plugin-bundle && npm run test:node && node dist/scripts/generate-catalog-docs.js --check",
+    "test:ci:compiled": "npm run verify:native-agents && npm run verify:plugin-bundle && npm run test:node && node dist/scripts/generate-catalog-docs.js --check",
+    "coverage:team-critical": "npm run build && c8 --all --src dist/team --src dist/state --include 'dist/team/**/*.js' --include 'dist/state/**/*.js' --exclude '**/__tests__/**' --reporter=text-summary --reporter=lcov --reporter=json-summary --report-dir coverage/team --check-coverage --lines=78 --functions=90 --branches=70 --statements=78 node dist/scripts/run-test-files.js dist/team/__tests__ dist/state/__tests__",
+    "coverage:team-critical:compiled": "c8 --all --src dist/team --src dist/state --include 'dist/team/**/*.js' --include 'dist/state/**/*.js' --exclude '**/__tests__/**' --reporter=text-summary --reporter=lcov --reporter=json-summary --report-dir coverage/team --check-coverage --lines=78 --functions=90 --branches=70 --statements=78 node dist/scripts/run-test-files.js dist/team/__tests__ dist/state/__tests__",
+    "coverage:team-critical:cross-platform": "npm run build && c8 --all --src dist/team --src dist/state --include 'dist/team/**/*.js' --include 'dist/state/**/*.js' --exclude '**/__tests__/**' --reporter=text-summary --reporter=lcov --reporter=json-summary --report-dir coverage/team --check-coverage --lines=78 --functions=90 --branches=70 --statements=78 node dist/scripts/run-test-files.js dist/team/__tests__ dist/state/__tests__",
+    "coverage:ts:full": "npm run build && c8 --all --src dist --exclude '**/__tests__/**' --exclude 'dist/bin/**' --exclude 'dist/**/*.d.ts' --reporter=text-summary --reporter=lcov --reporter=json-summary --report-dir coverage/ts-full node dist/scripts/run-test-files.js dist",
+    "coverage:ts:full:compiled": "c8 --all --src dist --exclude '**/__tests__/**' --exclude 'dist/bin/**' --exclude 'dist/**/*.d.ts' --reporter=text-summary --reporter=lcov --reporter=json-summary --report-dir coverage/ts-full node dist/scripts/run-test-files.js dist",
+    "coverage:ts:full:cross-platform": "npm run build && c8 --all --src dist --exclude '**/__tests__/**' --exclude 'dist/bin/**' --exclude 'dist/**/*.d.ts' --reporter=text-summary --reporter=lcov --reporter=json-summary --report-dir coverage/ts-full node dist/scripts/run-test-files.js dist",
+    "test:ralph-persistence:compiled": "node --test dist/cli/__tests__/session-scoped-runtime.test.js dist/mcp/__tests__/trace-server.test.js dist/hud/__tests__/state.test.js dist/mcp/__tests__/state-server-ralph-phase.test.js dist/ralph/__tests__/persistence.test.js dist/verification/__tests__/ralph-persistence-gate.test.js",
+    "test:explicit-terminal-contract:compiled": "node --test dist/runtime/__tests__/run-outcome.test.js dist/mcp/__tests__/state-server.test.js dist/hooks/__tests__/notify-fallback-watcher.test.js dist/hooks/__tests__/notify-hook-ralph-resume.test.js dist/scripts/__tests__/codex-native-hook.test.js",
+    "test:compat:node": "npm run build && node dist/scripts/run-test-files.js dist/compat/__tests__",
+    "test:compat:node:cross-platform": "npm run build && node dist/scripts/run-test-files.js dist/compat/__tests__",
+    "test:compat:rust": "cargo build && RCS_COMPAT_TARGET=./target/debug/rcs npm run test:compat:node",
+    "build:sparkshell": "node dist/scripts/build-sparkshell.js",
+    "smoke:packed-install": "node dist/scripts/smoke-packed-install.js",
+    "test:sparkshell": "node dist/scripts/test-sparkshell.js",
+    "test:reply-listener:live": "node dist/scripts/test-reply-listener-live.js",
+    "postpack": "npm run clean:native-package-assets",
+    "sync:plugin": "node dist/scripts/sync-plugin-mirror.js",
+    "sync:plugin:check": "node dist/scripts/sync-plugin-mirror.js --check",
+    "verify:plugin-bundle": "node dist/scripts/sync-plugin-mirror.js --check",
+    "verify:native-agents": "node dist/scripts/verify-native-agents.js",
+    "prompt:inventory": "node dist/scripts/prompt-inventory.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "Cargo.toml",
+    "Cargo.lock",
+    "dist/",
+    "crates/",
+    "docs/",
+    "skills/",
+    "prompts/",
+    "templates/",
+    "src/scripts/",
+    "plugins/",
+    ".agents/plugins/marketplace.json"
+  ],
+  "keywords": [
+    "codex",
+    "openai",
+    "cli",
+    "agents",
+    "orchestration",
+    "multi-agent"
+  ],
+  "author": "JustineDevs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JustineDevs/roblox-ai-os.git"
+  },
+  "homepage": "https://github.com/JustineDevs/roblox-ai-os",
+  "bugs": {
+    "url": "https://github.com/JustineDevs/roblox-ai-os/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/node": "^25.5.0",
+    "c8": "^11.0.0",
+    "typescript": "^6.0.3"
+  },
+  "overrides": {
+    "ajv": ">=8.18.0",
+    "hono": ">=4.11.10"
+  }
+}

package/plugins/roblox-ai-os-creator-skills/.app.json

@@ -0,0 +1,3 @@
+{
+  "apps": {}
+}

package/plugins/roblox-ai-os-creator-skills/.codex-plugin/plugin.json

@@ -0,0 +1,30 @@
+{
+  "name": "roblox-ai-os-creator-skills",
+  "version": "0.1.0",
+  "description": "Roblox Creator Skills workflow and runtime bundle for Codex CLI",
+  "author": {
+    "name": "JustineDevs",
+    "url": "https://github.com/JustineDevs"
+  },
+  "homepage": "https://github.com/JustineDevs/roblox-ai-os",
+  "repository": "https://github.com/JustineDevs/roblox-ai-os.git",
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "openai",
+    "cli",
+    "agents",
+    "orchestration",
+    "multi-agent"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "RCS",
+    "shortDescription": "Roblox Creator Skills workflow bundle for Codex CLI.",
+    "longDescription": "Plugin delivery covers RCS skill discovery plus plugin-scoped MCP and app metadata. Runtime wiring, hooks, AGENTS scaffolding, HUD, and canonical .rcs state remain setup-owned so creators can run briefing, blueprinting, forging, crew orchestration, and psychology-aware design workflows from one package.",
+    "developerName": "JustineDevs",
+    "category": "Developer Tools"
+  }
+}

package/plugins/roblox-ai-os-creator-skills/.mcp.json

@@ -0,0 +1,44 @@
+{
+  "mcpServers": {
+    "rcs_state": {
+      "command": "rcs",
+      "args": [
+        "mcp-serve",
+        "state"
+      ],
+      "enabled": true
+    },
+    "rcs_memory": {
+      "command": "rcs",
+      "args": [
+        "mcp-serve",
+        "memory"
+      ],
+      "enabled": true
+    },
+    "rcs_code_intel": {
+      "command": "rcs",
+      "args": [
+        "mcp-serve",
+        "code-intel"
+      ],
+      "enabled": true
+    },
+    "rcs_trace": {
+      "command": "rcs",
+      "args": [
+        "mcp-serve",
+        "trace"
+      ],
+      "enabled": true
+    },
+    "rcs_wiki": {
+      "command": "rcs",
+      "args": [
+        "mcp-serve",
+        "wiki"
+      ],
+      "enabled": true
+    }
+  }
+}

package/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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/plugins/roblox-ai-os-creator-skills/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