sneakoscope 0.5.0 → 0.6.0

package/README.md

@@ -10,11 +10,187 @@ Sneakoscope Codex is a zero-runtime-dependency Node.js harness for running Codex
 npm i -g sneakoscope
 ```
 
-The npm package name is `sneakoscope`; the command is branded as SKS and exposed as lowercase `sks` for shell portability.
-Global installation is the default and recommended setup. For a project-only install, use `npm i -D sneakoscope` and initialize hooks with `npx sks init --install-scope project`; this writes hook commands that call the local `node_modules/sneakoscope` binary instead of global `sks`.
+The npm package name is `sneakoscope`; the command is branded as SKS and exposed as lowercase `sks` for shell portability. The package also exposes a `sneakoscope` command alias, so `sks setup` and `sneakoscope setup` are equivalent.
+Global installation is the default and recommended setup. During `sks setup` or `sks init`, SKS resolves the global binary when possible and writes that absolute path into `.codex/hooks.json`, which avoids PATH issues in GUI or hook execution environments. For a project-only install, use `npm i -D sneakoscope` and initialize hooks with `npx sks setup --install-scope project`; this writes hook commands that call the local `node_modules/sneakoscope` binary.
 
 `@openai/codex` is intentionally not bundled. Install Codex separately, or set `SKS_CODEX_BIN` to the Codex executable you want Sneakoscope Codex to supervise.
 
+## One-Prompt LLM Install
+
+If you are using Codex App, ChatGPT, Claude Code, Cursor, or another coding agent, copy this prompt into the agent from your target project directory:
+
+````text
+You are installing Sneakoscope Codex in the current project. Do the setup end to end without asking follow-up questions unless a command needs user approval.
+
+Repository:
+https://github.com/mandarange/Sneakoscope-Codex.git
+
+Requirements:
+- Node.js must be >=20.11.
+- Codex CLI is installed separately; if missing, report that @openai/codex must be installed or SKS_CODEX_BIN must be set.
+- Prefer safe, local verification. Do not modify application source files unless needed for SKS setup.
+
+Run:
+```bash
+npm i -g git+https://github.com/mandarange/Sneakoscope-Codex.git
+sks setup
+sks doctor --fix
+sks selftest --mock
+sks commands
+```
+
+If the global command is not on PATH, use:
+```bash
+npx -y -p git+https://github.com/mandarange/Sneakoscope-Codex.git sks setup
+npx -y -p git+https://github.com/mandarange/Sneakoscope-Codex.git sks doctor --fix
+```
+
+After setup, explain these outputs to the user:
+- `.sneakoscope/` mission state and policy
+- `.codex/config.toml` Codex App profiles
+- `.codex/hooks.json` SKS hook integration
+- `.codex/skills/` local Codex App skills
+- `.codex/SNEAKOSCOPE.md` Codex App quick reference
+- `AGENTS.md` repository rules
+
+Show the user how to discover commands:
+```bash
+sks help
+sks commands
+sks usage ralph
+sks quickstart
+sks codex-app
+sks dollar-commands
+```
+
+Tell the user they can use these prompt commands inside Codex App:
+```text
+$DF 글자 색 바꿔줘
+$DF 내용을 영어로 바꿔줘
+$SKS show me available workflows
+$Ralph implement this with mandatory clarification
+$Research investigate this idea
+$DB check this migration safely
+```
+````
+
+After SKS is installed, you can print this prompt again from the CLI:
+
+```bash
+sks install-prompt
+sks install-prompt --project
+```
+
+## Repository
+
+```bash
+npm i -g git+https://github.com/mandarange/Sneakoscope-Codex.git
+```
+
+Source repository: <https://github.com/mandarange/Sneakoscope-Codex.git>
+
+Local development checkout:
+
+```bash
+git clone https://github.com/mandarange/Sneakoscope-Codex.git
+cd Sneakoscope-Codex
+npm i
+```
+
+## Installed Commands
+
+Installing the package exposes two equivalent shell commands:
+
+```bash
+sks <command>
+sneakoscope <command>
+```
+
+Use `sks --help` or `sneakoscope --help` to inspect the installed CLI. The user-facing subcommands are listed in [Commands](#commands).
+
+Useful discovery commands:
+
+```bash
+sks commands
+sks usage install
+sks usage ralph
+sks quickstart
+sks install-prompt
+sks codex-app
+sks dollar-commands
+sks df
+sks aliases
+```
+
+## Prompt Pipeline and $ Commands
+
+SKS installs a Codex App `UserPromptSubmit` hook that adds a lightweight prompt-optimization context to every user request. You do not need to type a command for basic routing: SKS will infer the lightest path before work starts.
+
+Use `$` prompt commands inside Codex App or another coding agent when you want to force a route:
+
+```text
+$DF        fast design/content fix
+$SKS       general Sneakoscope workflow/help
+$Ralph     clarification-gated Ralph mission
+$Research  frontier research mission
+$DB        database/Supabase safety check
+$GX        deterministic visual context
+$Help      command and workflow help
+```
+
+`$DF` is intentionally small and fast. Use it for changes like text color, visible copy, labels, spacing, button text, or translation:
+
+```text
+$DF 글자 색 파란색으로 바꿔줘
+$DF 내용을 영어로 바꿔줘
+$DF Change the CTA label to "Start"
+```
+
+DF should not start Ralph, Research, evaluation, or a broad redesign unless you explicitly ask for that.
+
+## Codex App
+
+Sneakoscope Codex can also be used from Codex App when the repository is opened in the app. Run setup once in the project:
+
+```bash
+sks setup
+```
+
+This creates the app-facing control surface:
+
+```text
+.codex/config.toml       Codex App profiles for SKS Ralph, research, and default work
+.codex/hooks.json        Codex App hook entrypoints routed through SKS guards
+.codex/skills/           local project skills for Ralph, DB safety, GX, research, and design work
+.codex/SNEAKOSCOPE.md    quick reference for using SKS inside Codex App
+AGENTS.md                repository rules loaded by Codex agents
+.sneakoscope/            mission state, gates, logs, policy, GX cartridges, and reports
+```
+
+Inside Codex App, you can ask the agent to use the local SKS control surface, for example:
+
+```text
+$DF 글자 색 바꿔줘
+$DF 내용을 영어로 바꿔줘
+Use Sneakoscope Ralph mode to prepare this task.
+Run the latest Ralph mission with the sealed decision contract.
+Use SKS DB safety before touching database or Supabase files.
+Use SKS research mode for this investigation.
+```
+
+If Codex App cannot find `sks` from hooks, run:
+
+```bash
+sks fix-path
+```
+
+For a project-only install, use:
+
+```bash
+npm i -D sneakoscope
+npx sks setup --install-scope project
+```
+
 ## Requirements
 
 - Node.js `>=20.11`
@@ -25,8 +201,7 @@ Global installation is the default and recommended setup. For a project-only ins
 ## Quick Start
 
 ```bash
-sks doctor --fix
-sks init
+sks setup
 sks selftest --mock
 ```
 
@@ -34,8 +209,19 @@ Project-only setup:
 
 ```bash
 npm i -D sneakoscope
-npx sks doctor --fix --install-scope project
-npx sks init --install-scope project
+npx sks setup --install-scope project
+```
+
+If a GUI hook, Codex session, or another project cannot find `sks`, refresh the hook command with the resolved binary path:
+
+```bash
+sks fix-path
+```
+
+If your shell cannot find the global command yet, run through npm without relying on PATH:
+
+```bash
+npx -y -p sneakoscope sks setup
 ```
 
 Create a Ralph mission:
@@ -73,6 +259,8 @@ sks research run latest --max-cycles 3
 - **Sealed decision contract**: `ralph answer` validates answers and writes `decision-contract.json`.
 - **No-question Ralph loop**: after `ralph run` starts, Ralph must resolve ambiguity with the sealed contract instead of asking the user.
 - **Research mode**: `research` runs a frontier-discovery loop for non-obvious hypotheses, falsification, novelty ledgers, and testable experiments.
+- **Prompt pipeline and `$` routes**: user prompts are lightly optimized by default, and Codex App users can force routes such as `$DF`, `$Ralph`, `$Research`, `$DB`, and `$GX`.
+- **Fast DF mode**: `$DF` handles small design/content edits like color, copy, labels, spacing, and translation without unnecessary Ralph, Research, or evaluation loops.
 - **Database guard**: destructive DB operations, production writes, unsafe Supabase MCP configuration, and direct live SQL mutations are blocked or warned on.
 - **H-Proof done gate**: completion requires supported critical claims, reviewed DB safety state, acceptable visual/wiki drift, and required test evidence.
 - **Performance evaluation**: `sks eval` produces deterministic token, accuracy-proxy, recall, support, and runtime metrics for before/after evidence.
@@ -110,7 +298,24 @@ Core invariants:
 
 ## Commands
 
+All examples below use `sks`, but the same commands can be run with the `sneakoscope` alias.
+
 ```bash
+sks help [topic]
+sks commands [--json]
+sks usage [install|setup|ralph|research|db|codex-app|df|dollar|eval|gx]
+sks quickstart
+sks install-prompt [--project]
+sks codex-app
+sks dollar-commands [--json]
+sks df
+sks aliases
+
+sks --help
+sneakoscope --help
+
+sks setup [--install-scope global|project] [--force] [--json]
+sks fix-path [--install-scope global|project] [--json]
 sks doctor [--fix] [--json] [--install-scope global|project]
 sks init [--force] [--install-scope global|project]
 sks selftest [--mock]
@@ -138,6 +343,7 @@ sks eval compare --baseline old.json --candidate new.json [--json]
 sks eval thresholds
 
 sks hproof check [mission-id|latest]
+sks team "task"
 sks gx init [name]
 sks gx render [name] [--format svg|html|all]
 sks gx validate [name]
@@ -146,6 +352,7 @@ sks gx snapshot [name]
 sks profile show
 sks profile set <model>
 sks gc [--dry-run] [--json]
+sks memory [--dry-run] [--json]
 sks stats [--json]
 ```
 
@@ -272,6 +479,8 @@ sks hproof check latest
 .sneakoscope/              mission state, policy, retention, logs, GX cartridges
 .codex/config.toml    Codex profiles used by Sneakoscope Codex
 .codex/hooks.json     hook entrypoints
+.codex/skills/        Codex App local project skills
+.codex/SNEAKOSCOPE.md Codex App quick reference
 .agents/skills/       Sneakoscope Codex helper skills
 AGENTS.md             managed repository rules block
 ```
@@ -279,7 +488,7 @@ AGENTS.md             managed repository rules block
 Install scope controls `.codex/hooks.json`:
 
 ```text
-global  -> sks hook ...
+global  -> /absolute/path/to/sks hook ... when resolvable, otherwise sks hook ...
 project -> node ./node_modules/sneakoscope/bin/sks.mjs hook ...
 ```
 
@@ -362,12 +571,32 @@ The published npm package is allowlisted to `bin`, `src`, `docs`, `README.md`, a
 ## Development
 
 ```bash
+npm run repo-audit
 npm run packcheck
 npm run selftest
 npm run sizecheck
 npm run doctor
 ```
 
+`npm run repo-audit` checks tracked files for risky local paths and high-confidence secret material such as private keys, npm/GitHub/OpenAI-style tokens, local MCP configs, DB dumps, and credential files. It is included in `prepack` and `prepublishOnly`.
+
 `npm run sizecheck` blocks accidental package bloat before `npm pack` or `npm publish`. Defaults: packed tarball `<=96 KiB`, unpacked package `<=320 KiB`, package files `<=40`, and each tracked file `<=256 KiB`. Override only for an intentional release with `SKS_MAX_PACK_BYTES`, `SKS_MAX_UNPACKED_BYTES`, `SKS_MAX_PACK_FILES`, or `SKS_MAX_TRACKED_FILE_BYTES`.
 
 `npm run selftest` uses the mock path and does not call a model. Live Ralph runs require a working Codex CLI installation and authentication.
+
+## Publishing
+
+The npm package is published as public package `sneakoscope`. You must be logged in as an npm owner for that package before publishing.
+
+```bash
+npm whoami
+npm owner ls sneakoscope
+npm run publish:dry
+npm run publish:npm
+```
+
+If `npm whoami` returns `E401 Unauthorized`, run `npm login` with an owner account or ask an existing owner to add your npm username:
+
+```bash
+npm owner add <your-npm-username> sneakoscope
+```

package/docs/PERFORMANCE.md

@@ -1,6 +1,6 @@
 # Sneakoscope Codex performance and leak policy
 
-Sneakoscope Codex v0.5 is designed to keep runtime, package size, RAM, and storage bounded.
+Sneakoscope Codex v0.6 is designed to keep runtime, package size, RAM, and storage bounded.
 
 ## Speed
 

package/package.json

@@ -1,11 +1,16 @@
 {
   "name": "sneakoscope",
   "displayName": "Sneakoscope Codex",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Sneakoscope Codex: database-safe, performance-bounded Codex CLI harness with Ralph no-question loop, H-Proof gates, deterministic GX visual context, and TriWiki compression.",
   "type": "module",
   "bin": {
-    "sks": "bin/sks.mjs"
+    "sks": "bin/sks.mjs",
+    "sneakoscope": "bin/sks.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
   },
   "files": [
     "bin",
@@ -18,12 +23,15 @@
     "node": ">=20.11"
   },
   "scripts": {
+    "repo-audit": "node ./scripts/repo-audit.mjs",
     "selftest": "node ./bin/sks.mjs selftest --mock",
     "doctor": "node ./bin/sks.mjs doctor",
     "packcheck": "find bin src scripts -name '*.mjs' -print0 | xargs -0 -n1 node --check",
     "sizecheck": "node ./scripts/sizecheck.mjs",
-    "prepack": "npm run packcheck && npm run selftest && npm run sizecheck",
-    "prepublishOnly": "npm run packcheck && npm run selftest && npm run sizecheck"
+    "publish:dry": "npm --cache /tmp/sks-npm-cache pack --dry-run",
+    "publish:npm": "npm --cache /tmp/sks-npm-cache publish --access public",
+    "prepack": "npm run repo-audit && npm run packcheck && npm run selftest && npm run sizecheck",
+    "prepublishOnly": "npm run repo-audit && npm run packcheck && npm run selftest && npm run sizecheck"
   },
   "keywords": [
     "sneakoscope",

package/src/cli/main.mjs

@@ -18,6 +18,46 @@ import { buildResearchPrompt, evaluateResearchGate, writeMockResearchResult, wri
 
 const flag = (args, name) => args.includes(name);
 const promptOf = (args) => args.filter((x) => !String(x).startsWith('--')).join(' ').trim();
+const REPOSITORY_URL = 'https://github.com/mandarange/Sneakoscope-Codex.git';
+const USAGE_TOPICS = 'install|setup|ralph|research|db|codex-app|df|dollar|eval|gx';
+
+const DOLLAR_COMMANDS = [
+  { command: '$DF', route: 'fast design/content fix', description: 'Small UI/content edits such as text color, copy, label, spacing, or translation. Avoids heavy loops.' },
+  { command: '$SKS', route: 'general SKS workflow', description: 'General Sneakoscope setup, help, status, and workflow routing.' },
+  { command: '$Ralph', route: 'Ralph mission', description: 'Mandatory clarification and no-question autonomous mission workflow.' },
+  { command: '$Research', route: 'research mission', description: 'Frontier discovery, hypotheses, falsification, and testable predictions.' },
+  { command: '$DB', route: 'database safety', description: 'Database, Supabase, migration, SQL, or MCP safety checks.' },
+  { command: '$GX', route: 'visual context', description: 'Deterministic GX visual context cartridges.' },
+  { command: '$Help', route: 'command help', description: 'Explain installed SKS commands and workflows.' }
+];
+
+const COMMAND_CATALOG = [
+  { name: 'help', usage: 'sks help [topic]', description: 'Show CLI help or focused help for a topic.' },
+  { name: 'commands', usage: 'sks commands [--json]', description: 'List every user-facing command with a short description.' },
+  { name: 'usage', usage: `sks usage [${USAGE_TOPICS}]`, description: 'Print copy-ready workflows for common tasks.' },
+  { name: 'quickstart', usage: 'sks quickstart', description: 'Show the shortest safe setup and verification flow.' },
+  { name: 'install-prompt', usage: 'sks install-prompt [--project]', description: 'Print an LLM-ready prompt that installs and configures SKS automatically.' },
+  { name: 'codex-app', usage: 'sks codex-app', description: 'Show Codex App setup files and example prompts.' },
+  { name: 'dollar-commands', usage: 'sks dollar-commands [--json]', description: 'List Codex App $ commands such as $DF.' },
+  { name: 'df', usage: 'sks df', description: 'Explain $DF fast design/content fix mode.' },
+  { name: 'aliases', usage: 'sks aliases', description: 'Show command aliases and npm binary names.' },
+  { name: 'setup', usage: 'sks setup [--install-scope global|project] [--force] [--json]', description: 'Initialize SKS state, Codex App files, hooks, skills, and rules.' },
+  { name: 'fix-path', usage: 'sks fix-path [--install-scope global|project] [--json]', description: 'Refresh hook commands with the resolved SKS binary path.' },
+  { name: 'doctor', usage: 'sks doctor [--fix] [--json] [--install-scope global|project]', description: 'Check Node, Codex CLI, install scope, hooks, skills, DB guard, and Codex App files.' },
+  { name: 'init', usage: 'sks init [--force] [--install-scope global|project]', description: 'Initialize the local SKS control surface.' },
+  { name: 'selftest', usage: 'sks selftest [--mock]', description: 'Run local smoke tests without calling a model.' },
+  { name: 'ralph', usage: 'sks ralph prepare|answer|run|status ...', description: 'Run mandatory-clarification Ralph missions with a no-question execution loop.' },
+  { name: 'research', usage: 'sks research prepare|run|status ...', description: 'Run frontier-style research missions with novelty and falsification gates.' },
+  { name: 'db', usage: 'sks db policy|scan|mcp-config|classify|check ...', description: 'Inspect and enforce database/Supabase safety policy.' },
+  { name: 'eval', usage: 'sks eval run|compare|thresholds ...', description: 'Run deterministic context-quality and performance evidence checks.' },
+  { name: 'hproof', usage: 'sks hproof check [mission-id|latest]', description: 'Evaluate the H-Proof done gate for a mission.' },
+  { name: 'team', usage: 'sks team "task"', description: 'Create a clarification-gated team mission.' },
+  { name: 'gx', usage: 'sks gx init|render|validate|drift|snapshot [name]', description: 'Create and verify deterministic SVG/HTML visual context cartridges.' },
+  { name: 'profile', usage: 'sks profile show|set <model>', description: 'Inspect or set the current SKS model profile metadata.' },
+  { name: 'gc', usage: 'sks gc [--dry-run] [--json]', description: 'Compact oversized logs and prune stale runtime artifacts.' },
+  { name: 'memory', usage: 'sks memory [--dry-run] [--json]', description: 'Alias for SKS garbage collection and retention handling.' },
+  { name: 'stats', usage: 'sks stats [--json]', description: 'Show package and .sneakoscope storage size.' }
+];
 
 function installScopeFromArgs(args = [], fallback = 'global') {
   if (flag(args, '--project')) return 'project';
@@ -29,7 +69,18 @@ function installScopeFromArgs(args = [], fallback = 'global') {
 export async function main(args) {
   const [cmd, sub, ...rest] = args;
   const tail = sub === undefined ? [] : [sub, ...rest];
-  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') return help();
+  if (!cmd || cmd === '--help' || cmd === '-h') return help();
+  if (cmd === 'help') return help(tail);
+  if (cmd === 'commands') return commands(tail);
+  if (cmd === 'usage') return usage(tail);
+  if (cmd === 'quickstart') return quickstart();
+  if (cmd === 'install-prompt') return installPrompt(tail);
+  if (cmd === 'codex-app') return codexAppHelp();
+  if (cmd === 'dollar-commands' || cmd === 'dollars' || cmd === '$') return dollarCommands(tail);
+  if (String(cmd).toLowerCase() === 'df') return dfHelp();
+  if (cmd === 'aliases') return aliases();
+  if (cmd === 'setup') return setup(tail);
+  if (cmd === 'fix-path') return fixPath(tail);
   if (cmd === 'doctor') return doctor(tail);
   if (cmd === 'init') return init(tail);
   if (cmd === 'selftest') return selftest(tail);
@@ -49,10 +100,23 @@ export async function main(args) {
   process.exitCode = 1;
 }
 
-function help() {
+function help(args = []) {
+  const topic = args[0];
+  if (topic) return usage([topic]);
   console.log(`Sneakoscope Codex
 
 Usage:
+  sks help [topic]
+  sks commands [--json]
+  sks usage [${USAGE_TOPICS}]
+  sks quickstart
+  sks install-prompt [--project]
+  sks codex-app
+  sks dollar-commands [--json]
+  sks df
+  sks aliases
+  sks setup [--install-scope global|project] [--force] [--json]
+  sks fix-path [--install-scope global|project] [--json]
   sks doctor [--fix] [--json] [--install-scope global|project]
   sks init [--install-scope global|project]
   sks selftest [--mock]
@@ -75,17 +139,441 @@ Usage:
   sks gx validate [name]
   sks gx drift [name]
   sks gx snapshot [name]
+  sks profile show
+  sks profile set <model>
   sks gc [--dry-run] [--json]
+  sks memory [--dry-run] [--json]
   sks stats [--json]
+
+Discovery:
+  sks commands       Full command list with descriptions
+  sks usage ralph    Workflow examples for one topic
+  sks install-prompt Copy/paste prompt for an LLM installer
+  sks dollar-commands Codex App $ commands, including $DF
 `);
 }
 
+function commands(args = []) {
+  if (flag(args, '--json')) return console.log(JSON.stringify({ aliases: ['sks', 'sneakoscope'], dollar_commands: DOLLAR_COMMANDS, commands: COMMAND_CATALOG }, null, 2));
+  console.log('Sneakoscope Codex Commands\n');
+  console.log('Aliases: sks, sneakoscope\n');
+  const width = Math.max(...COMMAND_CATALOG.map((c) => c.usage.length));
+  for (const c of COMMAND_CATALOG) console.log(`${c.usage.padEnd(width)}  ${c.description}`);
+}
+
+function dollarCommands(args = []) {
+  if (flag(args, '--json')) return console.log(JSON.stringify({ dollar_commands: DOLLAR_COMMANDS }, null, 2));
+  console.log('Sneakoscope Codex $ Commands\n');
+  console.log('Use these inside Codex App or another agent prompt. Shells treat $ as variable syntax, so these are prompt commands, not terminal commands.\n');
+  const width = Math.max(...DOLLAR_COMMANDS.map((c) => c.command.length));
+  for (const c of DOLLAR_COMMANDS) console.log(`${c.command.padEnd(width)}  ${c.route}: ${c.description}`);
+  console.log('\nDefault pipeline: even without a $ command, SKS optimizes the prompt and infers the lightest route. Simple design/content edits infer $DF.');
+}
+
+function dfHelp() {
+  console.log(`SKS DF Mode
+
+Prompt command:
+  $DF <small design/content request>
+
+Examples:
+  $DF 글자 색 파란색으로 바꿔줘
+  $DF 내용을 영어로 바꿔줘
+  $DF Change the CTA label to "Start"
+
+Purpose:
+  Fast design/content fixes only. DF should prompt-engineer the user's request into the smallest implementation change.
+
+Rules:
+  Do not run Ralph, Research, eval, or broad redesign.
+  Inspect only what is needed, edit only what is requested, and run cheap verification when useful.
+`);
+}
+
+function quickstart() {
+  console.log(`Sneakoscope Codex Quickstart
+
+Install from npm:
+  npm i -g sneakoscope
+
+Install from GitHub:
+  npm i -g git+${REPOSITORY_URL}
+
+Initialize this project for CLI and Codex App:
+  sks setup
+
+Verify:
+  sks doctor --fix
+  sks selftest --mock
+  sks commands
+
+If hooks cannot find the command:
+  sks fix-path
+
+Project-only install:
+  npm i -D sneakoscope
+  npx sks setup --install-scope project
+`);
+}
+
+function installPrompt(args = []) {
+  const projectOnly = flag(args, '--project');
+  const install = projectOnly
+    ? `npm i -D git+${REPOSITORY_URL}\nnpx sks setup --install-scope project`
+    : `npm i -g git+${REPOSITORY_URL}\nsks setup`;
+  console.log(`Copy this prompt into an LLM coding assistant:
+
+You are installing Sneakoscope Codex in the current project. Do the setup end to end without asking follow-up questions unless a command needs user approval.
+
+Repository:
+${REPOSITORY_URL}
+
+Requirements:
+- Node.js must be >=20.11.
+- Codex CLI is installed separately; if missing, report that @openai/codex must be installed or SKS_CODEX_BIN must be set.
+- Prefer safe, local verification. Do not modify application source files unless needed for SKS setup.
+
+Run:
+\`\`\`bash
+${install}
+${projectOnly ? 'npx sks doctor --fix --install-scope project\nnpx sks selftest --mock\nnpx sks commands' : 'sks doctor --fix\nsks selftest --mock\nsks commands'}
+\`\`\`
+
+If the global command is not on PATH, use:
+\`\`\`bash
+npx -y -p git+${REPOSITORY_URL} sks setup
+npx -y -p git+${REPOSITORY_URL} sks doctor --fix
+\`\`\`
+
+After setup, explain these outputs to the user:
+- \`.sneakoscope/\` mission state and policy
+- \`.codex/config.toml\` Codex App profiles
+- \`.codex/hooks.json\` SKS hook integration
+- \`.codex/skills/\` local Codex App skills
+- \`.codex/SNEAKOSCOPE.md\` Codex App quick reference
+- \`AGENTS.md\` repository rules
+
+Show the user how to discover commands:
+\`\`\`bash
+sks help
+sks commands
+sks usage ralph
+sks quickstart
+sks codex-app
+sks dollar-commands
+\`\`\`
+
+Tell the user they can use these prompt commands inside Codex App:
+\`\`\`text
+$DF 글자 색 바꿔줘
+$DF 내용을 영어로 바꿔줘
+$Ralph implement this with mandatory clarification
+$Research investigate this idea
+$DB check this migration safely
+\`\`\`
+`);
+}
+
+function codexAppHelp() {
+  console.log(`Sneakoscope Codex App Usage
+
+Run once in the project:
+  sks setup
+
+Generated app files:
+  .codex/config.toml       profiles for SKS Ralph, research, and default work
+  .codex/hooks.json        hook events routed through SKS guards
+  .codex/skills/           local project skills
+  .codex/SNEAKOSCOPE.md    app quick reference
+  AGENTS.md                repository rules
+
+Useful prompts inside Codex App:
+  $DF 글자 색 바꿔줘
+  $DF 내용을 영어로 바꿔줘
+  Use Sneakoscope Ralph mode to prepare this task.
+  Run the latest Ralph mission with the sealed decision contract.
+  Use SKS DB safety before touching database or Supabase files.
+  Use SKS research mode for this investigation.
+
+Repair hook PATH issues:
+  sks fix-path
+
+Discover usage:
+  sks commands
+  sks usage codex-app
+  sks dollar-commands
+  sks df
+  sks install-prompt
+`);
+}
+
+function aliases() {
+  console.log(`Sneakoscope Codex Aliases
+
+Binary aliases:
+  sks
+  sneakoscope
+
+Command aliases:
+  sks memory    -> sks gc
+  sks --help    -> sks help
+  sks -h        -> sks help
+
+Codex App prompt commands:
+  $DF       fast design/content fix
+  $SKS      general Sneakoscope route
+  $Ralph    Ralph mission route
+  $Research research mission route
+  $DB       database safety route
+  $GX       visual context route
+  $Help     command help route
+
+Examples:
+  sks setup
+  sneakoscope setup
+  sks commands
+  sneakoscope commands
+`);
+}
+
+function usage(args = []) {
+  const topic = String(args[0] || 'overview').toLowerCase();
+  const blocks = {
+    overview: `Sneakoscope Codex Usage
+
+Discovery:
+  sks help
+  sks commands
+  sks quickstart
+  sks install-prompt
+  sks codex-app
+  sks dollar-commands
+
+Common workflows:
+  sks usage install
+  sks usage ralph
+  sks usage research
+  sks usage db
+  sks usage df
+`,
+    install: `Install and Setup
+
+Global install:
+  npm i -g sneakoscope
+  sks setup
+  sks doctor --fix
+  sks selftest --mock
+
+GitHub install:
+  npm i -g git+${REPOSITORY_URL}
+  sks setup
+
+Project-only install:
+  npm i -D sneakoscope
+  npx sks setup --install-scope project
+
+LLM-assisted install:
+  sks install-prompt
+`,
+    setup: `Setup Repair
+
+Initialize:
+  sks setup
+
+Refresh hook command paths:
+  sks fix-path
+
+Inspect readiness:
+  sks doctor
+  sks doctor --fix
+  sks doctor --json
+`,
+    ralph: `Ralph Workflow
+
+Prepare:
+  sks ralph prepare "task"
+
+Answer generated slots:
+  cat .sneakoscope/missions/<MISSION_ID>/questions.md
+  cp .sneakoscope/missions/<MISSION_ID>/required-answers.schema.json answers.json
+  sks ralph answer <MISSION_ID> answers.json
+
+Run:
+  sks ralph run <MISSION_ID> --max-cycles 8
+  sks ralph status latest
+
+Local smoke run:
+  sks ralph run latest --mock
+`,
+    research: `Research Workflow
+
+Prepare:
+  sks research prepare "topic" --depth frontier
+
+Run:
+  sks research run latest --max-cycles 3
+
+Inspect:
+  sks research status latest
+`,
+    db: `Database Safety
+
+Policy:
+  sks db policy
+
+Scan project config:
+  sks db scan --migrations
+
+Generate safe Supabase MCP config:
+  sks db mcp-config --project-ref <ref> --features database,docs
+
+Classify/check operations:
+  sks db classify --sql "DROP TABLE users"
+  sks db check --command "supabase db reset"
+  sks db check --file ./migration.sql
+`,
+    'codex-app': `Codex App
+
+Initialize app files:
+  sks setup
+
+Inspect app guidance:
+  sks codex-app
+  sks dollar-commands
+  cat .codex/SNEAKOSCOPE.md
+
+Use inside Codex App:
+  $DF 글자 색 바꿔줘
+  $DF 내용을 영어로 바꿔줘
+  Use Sneakoscope Ralph mode to prepare this task.
+  Use SKS DB safety before touching database or Supabase files.
+`,
+    df: `DF Fast Design/Content Fix
+
+Use inside Codex App:
+  $DF 글자 색 파란색으로 바꿔줘
+  $DF 내용을 영어로 바꿔줘
+  $DF Change the button label to "Start"
+
+Behavior:
+  Prompt-engineer the request into the smallest design/content edit.
+  Do not start Ralph, Research, eval, or a broad redesign.
+  Inspect only relevant files and run only cheap verification when useful.
+
+CLI help:
+  sks df
+`,
+    dollar: `Dollar Commands
+
+Use inside Codex App or an agent prompt:
+  $DF        fast design/content fix
+  $SKS       general Sneakoscope route
+  $Ralph     Ralph mission route
+  $Research  research mission route
+  $DB        database safety route
+  $GX        visual context route
+  $Help      command help route
+
+Terminal discovery:
+  sks dollar-commands
+  sks dollar-commands --json
+`,
+    eval: `Evaluation
+
+Run benchmark:
+  sks eval run
+  sks eval run --json --out report.json
+
+Compare reports:
+  sks eval compare --baseline old.json --candidate new.json
+
+Show thresholds:
+  sks eval thresholds
+`,
+    gx: `GX Visual Context
+
+Create:
+  sks gx init architecture-atlas
+
+Render and verify:
+  sks gx render architecture-atlas --format all
+  sks gx validate architecture-atlas
+  sks gx drift architecture-atlas
+  sks gx snapshot architecture-atlas
+`
+  };
+  const text = blocks[topic] || blocks.overview;
+  console.log(text);
+}
+
+async function setup(args) {
+  const root = await projectRoot();
+  const installScope = installScopeFromArgs(args);
+  const globalCommand = await globalSksCommand();
+  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand });
+  const install = await installStatus(root, installScope, { globalCommand });
+  const hooksPath = path.join(root, '.codex', 'hooks.json');
+  const result = {
+    root,
+    install,
+    hooks: hooksPath,
+    codex_app: {
+      config: path.join(root, '.codex', 'config.toml'),
+      hooks: hooksPath,
+      skills: path.join(root, '.codex', 'skills'),
+      quick_reference: path.join(root, '.codex', 'SNEAKOSCOPE.md'),
+      agents_rules: path.join(root, 'AGENTS.md')
+    },
+    created: res.created,
+    next: ['sks selftest --mock', 'sks doctor', 'sks commands']
+  };
+  if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+  console.log('Sneakoscope Codex Setup\n');
+  console.log(`Project:   ${root}`);
+  console.log(`Install:   ${install.ok ? 'ok' : 'missing'} ${install.scope} (${install.command_prefix})`);
+  console.log(`Hooks:     ${path.relative(root, hooksPath)}`);
+  console.log(`Codex App: .codex/config.toml, .codex/hooks.json, .codex/skills, .codex/SNEAKOSCOPE.md`);
+  console.log(`Prompt:    default optimization pipeline, $DF fast design/content route`);
+  console.log(`Skills:    .codex/skills, .agents/skills`);
+  console.log(`Next:      sks selftest --mock; sks commands; sks dollar-commands`);
+  if (!install.ok && install.scope === 'global') console.log('\nGlobal command missing. Run: npm i -g sneakoscope');
+  if (!install.ok && install.scope === 'project') console.log('\nProject package missing. Run: npm i -D sneakoscope');
+}
+
+async function fixPath(args) {
+  const root = await projectRoot();
+  const manifest = await readJson(path.join(root, '.sneakoscope', 'manifest.json'), null);
+  const installScope = args.includes('--install-scope') || flag(args, '--project') || flag(args, '--global')
+    ? installScopeFromArgs(args)
+    : normalizeInstallScope(manifest?.installation?.scope || 'global');
+  const globalCommand = await globalSksCommand();
+  await initProject(root, { installScope, globalCommand });
+  const install = await installStatus(root, installScope, { globalCommand });
+  const result = {
+    root,
+    install_scope: installScope,
+    hook_command_prefix: sksCommandPrefix(installScope, { globalCommand }),
+    hooks: path.join(root, '.codex', 'hooks.json'),
+    install
+  };
+  if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+  console.log('SKS hook path refreshed\n');
+  console.log(`Project:   ${root}`);
+  console.log(`Install:   ${install.ok ? 'ok' : 'missing'} ${install.scope} (${install.command_prefix})`);
+  console.log(`Hooks:     .codex/hooks.json`);
+  if (!install.ok && install.scope === 'global') console.log('\nGlobal command missing. Run: npm i -g sneakoscope');
+  if (!install.ok && install.scope === 'project') console.log('\nProject package missing. Run: npm i -D sneakoscope');
+}
+
 async function doctor(args) {
   const root = await projectRoot();
   const requestedScope = args.includes('--install-scope') || flag(args, '--project') || flag(args, '--global')
     ? installScopeFromArgs(args)
     : null;
-  if (flag(args, '--fix')) await initProject(root, { installScope: requestedScope || 'global' });
+  if (flag(args, '--fix')) {
+    const fixScope = requestedScope || 'global';
+    await initProject(root, { installScope: fixScope, globalCommand: await globalSksCommand() });
+  }
   const codex = await getCodexInfo();
   const rust = await rustInfo();
   const nodeOk = Number(process.versions.node.split('.')[0]) >= 20;
@@ -96,16 +584,27 @@ async function doctor(args) {
   const install = await installStatus(root, installScope);
   const dbPolicyExists = await exists(path.join(root, '.sneakoscope', 'db-safety.json'));
   const dbScan = await scanDbSafety(root).catch((err) => ({ ok: false, findings: [{ id: 'db_safety_scan_failed', severity: 'high', reason: err.message }] }));
+  const codexApp = {
+    config: { ok: await exists(path.join(root, '.codex', 'config.toml')) },
+    hooks: { ok: await exists(path.join(root, '.codex', 'hooks.json')) },
+    skills: { ok: await exists(path.join(root, '.codex', 'skills')) },
+    quick_reference: { ok: await exists(path.join(root, '.codex', 'SNEAKOSCOPE.md')) },
+    agents_rules: { ok: await exists(path.join(root, 'AGENTS.md')) }
+  };
   const result = {
     node: { ok: nodeOk, version: process.version }, root, codex, rust,
     install,
     sneakoscope: { ok: await exists(path.join(root, '.sneakoscope')) },
     db_guard: { ok: dbPolicyExists && dbScan.ok, policy: dbPolicyExists ? await loadDbSafetyPolicy(root) : null, scan: dbScan },
     hooks: { ok: await exists(path.join(root, '.codex', 'hooks.json')) },
-    skills: { ok: await exists(path.join(root, '.agents', 'skills')) },
+    skills: { ok: (await exists(path.join(root, '.codex', 'skills'))) && (await exists(path.join(root, '.agents', 'skills'))) },
+    codex_app: {
+      ...codexApp,
+      ok: codexApp.config.ok && codexApp.hooks.ok && codexApp.skills.ok && codexApp.quick_reference.ok && codexApp.agents_rules.ok
+    },
     package: { bytes: pkgBytes, human: formatBytes(pkgBytes) }, storage
   };
-  result.ready = nodeOk && Boolean(codex.bin) && install.ok && result.sneakoscope.ok && result.db_guard.ok;
+  result.ready = nodeOk && Boolean(codex.bin) && install.ok && result.sneakoscope.ok && result.db_guard.ok && result.codex_app.ok;
   if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
   console.log('Sneakoscope Codex Doctor\n');
   console.log(`Node:      ${nodeOk ? 'ok' : 'fail'} ${process.version}`);
@@ -116,7 +615,8 @@ async function doctor(args) {
   console.log(`State:     ${result.sneakoscope.ok ? 'ok' : 'missing .sneakoscope'}`);
   console.log(`DB Guard:  ${result.db_guard.ok ? 'ok' : 'blocked'} ${dbScan.findings?.length || 0} finding(s)`);
   console.log(`Hooks:     ${result.hooks.ok ? 'ok' : 'missing .codex/hooks.json'}`);
-  console.log(`Skills:    ${result.skills.ok ? 'ok' : 'missing .agents/skills'}`);
+  console.log(`Codex App: ${result.codex_app.ok ? 'ok' : 'missing app files'} .codex/config.toml .codex/hooks.json .codex/skills .codex/SNEAKOSCOPE.md`);
+  console.log(`Skills:    ${result.skills.ok ? 'ok' : 'missing .codex/skills or .agents/skills'}`);
   console.log(`Package:   ${result.package.human}`);
   console.log(`Storage:   ${storage.total_human || '0 B'}`);
   console.log(`Ready:     ${result.ready ? 'yes' : 'no'}`);
@@ -129,15 +629,22 @@ async function doctor(args) {
 async function init(args) {
   const root = await projectRoot();
   const installScope = installScopeFromArgs(args);
-  const res = await initProject(root, { force: flag(args, '--force'), installScope });
+  const globalCommand = await globalSksCommand();
+  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand });
   console.log(`Initialized Sneakoscope Codex in ${root}`);
-  console.log(`Install scope: ${installScope} (${sksCommandPrefix(installScope)})`);
+  console.log(`Install scope: ${installScope} (${sksCommandPrefix(installScope, { globalCommand })})`);
   for (const x of res.created) console.log(`- ${x}`);
 }
 
-async function installStatus(root, scope) {
-  const commandPrefix = sksCommandPrefix(scope);
-  const globalBin = await which('sks').catch(() => null);
+async function globalSksCommand() {
+  return process.env.SKS_BIN || await which('sks').catch(() => null) || 'sks';
+}
+
+async function installStatus(root, scope, opts = {}) {
+  const discoveredGlobalBin = await which('sks').catch(() => null);
+  const configuredGlobalBin = process.env.SKS_BIN || (opts.globalCommand && opts.globalCommand !== 'sks' ? opts.globalCommand : null);
+  const globalBin = configuredGlobalBin || discoveredGlobalBin;
+  const commandPrefix = sksCommandPrefix(scope, { globalCommand: globalBin || undefined });
   const projectBin = path.join(root, 'node_modules', 'sneakoscope', 'bin', 'sks.mjs');
   const projectBinExists = await exists(projectBin);
   return {
@@ -386,12 +893,24 @@ async function selftest() {
   await initProject(tmp, {});
   const defaultHooks = await readJson(path.join(tmp, '.codex', 'hooks.json'));
   if (defaultHooks.hooks.PreToolUse[0].hooks[0].command !== 'sks hook pre-tool') throw new Error('selftest failed: global install hook command changed');
+  const absoluteHookTmp = tmpdir();
+  await initProject(absoluteHookTmp, { globalCommand: '/usr/local/bin/sks' });
+  const absoluteHooks = await readJson(path.join(absoluteHookTmp, '.codex', 'hooks.json'));
+  if (absoluteHooks.hooks.PreToolUse[0].hooks[0].command !== '/usr/local/bin/sks hook pre-tool') throw new Error('selftest failed: absolute global hook command missing');
   const projectScopeTmp = tmpdir();
   await initProject(projectScopeTmp, { installScope: 'project' });
   const projectHooks = await readJson(path.join(projectScopeTmp, '.codex', 'hooks.json'));
   if (projectHooks.hooks.PreToolUse[0].hooks[0].command !== 'node ./node_modules/sneakoscope/bin/sks.mjs hook pre-tool') throw new Error('selftest failed: project install hook command missing');
   const researchSkillExists = await exists(path.join(tmp, '.agents', 'skills', 'research-discovery', 'SKILL.md'));
   if (!researchSkillExists) throw new Error('selftest failed: research skill not installed');
+  const codexAppSkillExists = await exists(path.join(tmp, '.codex', 'skills', 'research-discovery', 'SKILL.md'));
+  if (!codexAppSkillExists) throw new Error('selftest failed: Codex App skill not installed');
+  const dfSkillExists = await exists(path.join(tmp, '.codex', 'skills', 'DF', 'SKILL.md'));
+  if (!dfSkillExists) throw new Error('selftest failed: $DF skill not installed');
+  const promptPipelineSkillExists = await exists(path.join(tmp, '.codex', 'skills', 'prompt-pipeline', 'SKILL.md'));
+  if (!promptPipelineSkillExists) throw new Error('selftest failed: prompt pipeline skill not installed');
+  const codexAppQuickRefExists = await exists(path.join(tmp, '.codex', 'SNEAKOSCOPE.md'));
+  if (!codexAppQuickRefExists) throw new Error('selftest failed: Codex App quick reference missing');
   const { id, dir, mission } = await createMission(tmp, { mode: 'ralph', prompt: '로그인 세션 만료 UX 개선 supabase db' });
   const schema = buildQuestionSchema(mission.prompt);
   await writeQuestions(dir, schema);

package/src/core/fsx.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PACKAGE_VERSION = '0.5.0';
+export const PACKAGE_VERSION = '0.6.0';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/hooks-runtime.mjs

@@ -22,10 +22,43 @@ function extractLastMessage(payload) {
   return payload.last_assistant_message || payload.assistant_message || payload.message || payload.response || payload.raw || '';
 }
 
+function extractUserPrompt(payload) {
+  return payload.prompt
+    || payload.user_prompt
+    || payload.userPrompt
+    || payload.message
+    || payload.input?.prompt
+    || payload.input?.message
+    || payload.raw
+    || '';
+}
+
 function extractCommand(payload) {
   return payload.command || payload.tool_input?.command || payload.input?.command || payload.tool?.input?.command || '';
 }
 
+function dollarCommand(prompt) {
+  const match = String(prompt || '').trim().match(/^\$([A-Za-z][A-Za-z0-9_-]*)(?:\s|:|$)/);
+  return match ? match[1].toUpperCase() : null;
+}
+
+function looksLikeFastDesignFix(prompt) {
+  const text = String(prompt || '');
+  const designCue = /(글자|텍스트|문구|내용|색|컬러|폰트|간격|여백|정렬|버튼|라벨|영어|한국어|번역|copy|text|color|font|spacing|padding|margin|align|label|button|translate)/i.test(text);
+  const changeCue = /(바꿔|변경|수정|교체|고쳐|영어로|한국어로|change|replace|update|make|turn|translate|fix)/i.test(text);
+  return designCue && changeCue;
+}
+
+function promptPipelineContext(prompt) {
+  const command = dollarCommand(prompt);
+  const fastDesign = command === 'DF' || looksLikeFastDesignFix(prompt);
+  const route = command ? `$${command}` : (fastDesign ? '$DF inferred' : 'default');
+  const dfLine = fastDesign
+    ? '\nFast design fix: treat this as $DF. Do the smallest relevant edit, avoid Ralph/research loops, avoid broad redesign, and run only cheap verification when useful.'
+    : '';
+  return `SKS prompt pipeline active. Route: ${route}. Optimize the user request before acting: extract intent, target files/surfaces, constraints, acceptance criteria, and the smallest safe execution path. Use explicit $ commands when present: $DF fast design/content edit, $Ralph clarification-gated mission, $Research discovery run, $DB database safety, $GX visual context, $SKS general SKS help. Without a command, infer the lightest matching route and avoid heavy loops unless the task requires them.${dfLine}`;
+}
+
 export async function hookMain(name) {
   const payload = await loadHookPayload();
   const root = await projectRoot(payload.cwd || process.cwd());
@@ -40,7 +73,7 @@ export async function hookMain(name) {
 }
 
 async function hookUserPrompt(root, state, payload, noQuestion) {
-  if (!noQuestion) return { continue: true };
+  if (!noQuestion) return { continue: true, additionalContext: promptPipelineContext(extractUserPrompt(payload)) };
   const id = state.mission_id;
   if (id) await appendJsonl(path.join(missionDir(root, id), 'user_queue.jsonl'), { ts: nowIso(), payload });
   return {

package/src/core/init.mjs

@@ -9,14 +9,14 @@ export function normalizeInstallScope(scope = 'global') {
   throw new Error(`Invalid install scope: ${scope}. Use "global" or "project".`);
 }
 
-export function sksCommandPrefix(scope = 'global') {
+export function sksCommandPrefix(scope = 'global', opts = {}) {
   return normalizeInstallScope(scope) === 'project'
     ? 'node ./node_modules/sneakoscope/bin/sks.mjs'
-    : 'sks';
+    : (opts.globalCommand || 'sks');
 }
 
-function sksHookCommand(scope, hookName) {
-  return `${sksCommandPrefix(scope)} hook ${hookName}`;
+function sksHookCommand(commandPrefix, hookName) {
+  return `${commandPrefix} hook ${hookName}`;
 }
 
 const AGENTS_BLOCK = `
@@ -44,6 +44,18 @@ When the user asks for research, new discoveries, hypothesis generation, frontie
 
 When creating HTML, UI, prototype, deck-like, or visual artifacts, use the local design artifact skill. Gather design context first, build the actual usable experience rather than a marketing placeholder, expose variations when useful, and verify the rendered artifact before handoff.
 
+## Prompt Optimization Pipeline
+
+Every user prompt enters the SKS prompt optimization pipeline even when the user does not type a command. Extract intent, target files or surfaces, constraints, acceptance criteria, risks, and the smallest safe execution path before acting. Choose the lightest matching route: fast edit, normal implementation, Ralph, Research, DB safety, GX, or evaluation. Do not run heavy Ralph/research/evaluation loops for simple direct edits.
+
+## Dollar Commands
+
+Codex App users may invoke local SKS modes with skill-style dollar commands. \`$DF\` is the fast design/content fix route for small changes such as text color, copy edits, label changes, spacing tweaks, or translating visible text. \`$DF\` should avoid broad redesign, avoid unnecessary planning loops, and make the requested change directly with only cheap verification when useful.
+
+## Codex App Usage
+
+When this repository is opened in Codex App, use the local Sneakoscope files as the app control surface. Read \`.codex/SNEAKOSCOPE.md\` for the quick reference, load project skills from \`.codex/skills\` when applicable, and use the generated \`.codex/hooks.json\` hooks for DB safety, no-question Ralph runs, retention, and done-gate enforcement.
+
 ## Source Priority
 
 1. Current code, tests, config
@@ -66,9 +78,10 @@ A task is not done until relevant tests are run or justified, unsupported critic
 export async function initProject(root, opts = {}) {
   const created = [];
   const installScope = normalizeInstallScope(opts.installScope || 'global');
+  const hookCommandPrefix = opts.hookCommandPrefix || sksCommandPrefix(installScope, { globalCommand: opts.globalCommand });
   const sine = path.join(root, '.sneakoscope');
   const dirs = [
-    '.sneakoscope/state', '.sneakoscope/missions', '.sneakoscope/db', '.sneakoscope/bus', '.sneakoscope/hproof', '.sneakoscope/db', '.sneakoscope/memory/q0_raw', '.sneakoscope/memory/q1_evidence', '.sneakoscope/memory/q2_facts', '.sneakoscope/memory/q3_tags', '.sneakoscope/memory/q4_bits', '.sneakoscope/gx/cartridges', '.sneakoscope/model/fingerprints', '.sneakoscope/genome/candidates', '.sneakoscope/trajectories/raw', '.sneakoscope/locks', '.sneakoscope/tmp', '.sneakoscope/arenas', '.sneakoscope/reports', '.codex', '.agents/skills'
+    '.sneakoscope/state', '.sneakoscope/missions', '.sneakoscope/db', '.sneakoscope/bus', '.sneakoscope/hproof', '.sneakoscope/db', '.sneakoscope/memory/q0_raw', '.sneakoscope/memory/q1_evidence', '.sneakoscope/memory/q2_facts', '.sneakoscope/memory/q3_tags', '.sneakoscope/memory/q4_bits', '.sneakoscope/gx/cartridges', '.sneakoscope/model/fingerprints', '.sneakoscope/genome/candidates', '.sneakoscope/trajectories/raw', '.sneakoscope/locks', '.sneakoscope/tmp', '.sneakoscope/arenas', '.sneakoscope/reports', '.codex', '.codex/skills', '.agents/skills'
   ];
   for (const d of dirs) await ensureDir(path.join(root, d));
 
@@ -78,13 +91,27 @@ export async function initProject(root, opts = {}) {
     initialized_at: nowIso(),
     no_external_tools: true,
     codex_required: true,
+    codex_app_supported: true,
     native_runtime_dependencies: 0,
     installation: {
       scope: installScope,
       default_scope: 'global',
-      global_command: 'sks',
+      hook_command_prefix: hookCommandPrefix,
+      global_command: opts.globalCommand || 'sks',
       project_command: 'node ./node_modules/sneakoscope/bin/sks.mjs'
     },
+    codex_app: {
+      config: '.codex/config.toml',
+      hooks: '.codex/hooks.json',
+      skills: '.codex/skills',
+      quick_reference: '.codex/SNEAKOSCOPE.md',
+      agents_rules: 'AGENTS.md'
+    },
+    prompt_pipeline: {
+      default_enabled: true,
+      dollar_commands: ['$DF', '$SKS', '$Ralph', '$Research', '$DB', '$GX', '$Help'],
+      fast_design_command: '$DF'
+    },
     database_safety: 'destructive_db_operations_denied_always',
     gx_renderer: 'deterministic_svg_html'
   });
@@ -98,20 +125,20 @@ export async function initProject(root, opts = {}) {
 
   const policyPath = path.join(sine, 'policy.json');
   if (!(await exists(policyPath)) || opts.force) {
-    await writeJsonAtomic(policyPath, defaultPolicy(installScope));
+    await writeJsonAtomic(policyPath, defaultPolicy(installScope, hookCommandPrefix));
     created.push('.sneakoscope/policy.json');
   } else {
     const policy = await readJson(policyPath, {});
     await writeJsonAtomic(policyPath, {
       ...policy,
-      installation: installPolicy(installScope)
+      installation: installPolicy(installScope, hookCommandPrefix)
     });
   }
 
-  function defaultPolicy(scope) {
+  function defaultPolicy(scope, commandPrefix) {
     return {
       schema_version: 1,
-      installation: installPolicy(scope),
+      installation: installPolicy(scope, commandPrefix),
       retention: DEFAULT_RETENTION_POLICY,
       database_safety: DEFAULT_DB_SAFETY_POLICY,
       performance: {
@@ -140,17 +167,31 @@ export async function initProject(root, opts = {}) {
         renderer: 'deterministic_svg_html',
         source_of_truth: 'vgraph.json',
         external_image_generation: false
+      },
+      codex_app: {
+        supported: true,
+        config: '.codex/config.toml',
+        hooks: '.codex/hooks.json',
+        skills: '.codex/skills',
+        quick_reference: '.codex/SNEAKOSCOPE.md',
+        agents_rules: 'AGENTS.md'
+      },
+      prompt_pipeline: {
+        default_enabled: true,
+        route_without_command: true,
+        dollar_commands: ['$DF', '$SKS', '$Ralph', '$Research', '$DB', '$GX', '$Help'],
+        fast_design_command: '$DF'
       }
     };
   }
 
-  function installPolicy(scope) {
+  function installPolicy(scope, commandPrefix) {
     return {
       scope,
       default_scope: 'global',
-      hook_command_prefix: sksCommandPrefix(scope),
+      hook_command_prefix: commandPrefix,
       global_install: 'npm i -g sneakoscope',
-      project_install: 'npm i -D sneakoscope && npx sks init --install-scope project'
+      project_install: 'npm i -D sneakoscope && npx sks setup --install-scope project'
     };
   }
 
@@ -166,24 +207,106 @@ export async function initProject(root, opts = {}) {
   await writeTextAtomic(path.join(root, '.codex', 'config.toml'), `[features]\ncodex_hooks = true\n\n[profiles.sks-ralph]\nmodel = "gpt-5.5"\napproval_policy = "never"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "high"\n\n[profiles.sks-research]\nmodel = "gpt-5.5"\napproval_policy = "never"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "xhigh"\n\n[profiles.sks-default]\nmodel = "gpt-5.5"\napproval_policy = "on-request"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "medium"\n`);
   created.push('.codex/config.toml');
 
+  await writeTextAtomic(path.join(root, '.codex', 'SNEAKOSCOPE.md'), codexAppQuickReference(installScope, hookCommandPrefix));
+  created.push('.codex/SNEAKOSCOPE.md');
+
   await writeJsonAtomic(path.join(root, '.codex', 'hooks.json'), {
     hooks: {
-      UserPromptSubmit: [{ hooks: [{ type: 'command', command: sksHookCommand(installScope, 'user-prompt-submit') }] }],
-      PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: sksHookCommand(installScope, 'pre-tool') }] }],
-      PostToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: sksHookCommand(installScope, 'post-tool') }] }],
-      PermissionRequest: [{ matcher: '*', hooks: [{ type: 'command', command: sksHookCommand(installScope, 'permission-request') }] }],
-      Stop: [{ hooks: [{ type: 'command', command: sksHookCommand(installScope, 'stop') }] }]
+      UserPromptSubmit: [{ hooks: [{ type: 'command', command: sksHookCommand(hookCommandPrefix, 'user-prompt-submit') }] }],
+      PreToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: sksHookCommand(hookCommandPrefix, 'pre-tool') }] }],
+      PostToolUse: [{ matcher: '*', hooks: [{ type: 'command', command: sksHookCommand(hookCommandPrefix, 'post-tool') }] }],
+      PermissionRequest: [{ matcher: '*', hooks: [{ type: 'command', command: sksHookCommand(hookCommandPrefix, 'permission-request') }] }],
+      Stop: [{ hooks: [{ type: 'command', command: sksHookCommand(hookCommandPrefix, 'stop') }] }]
     }
   });
   created.push(`.codex/hooks.json (${installScope})`);
 
   await installSkills(root);
+  created.push('.codex/skills/*');
   created.push('.agents/skills/*');
   return { created };
 }
 
+function codexAppQuickReference(scope, commandPrefix) {
+  return `# Sneakoscope Codex for Codex App
+
+This project has been initialized for both the SKS CLI and Codex App.
+
+## App Control Surface
+
+- Rules: \`AGENTS.md\`
+- Hooks: \`.codex/hooks.json\`
+- Profiles: \`.codex/config.toml\`
+- App skills: \`.codex/skills/\`
+- Mission state: \`.sneakoscope/missions/\`
+- Current state: \`.sneakoscope/state/current.json\`
+
+## Installed Command
+
+\`\`\`bash
+${commandPrefix} <command>
+\`\`\`
+
+Install scope: \`${scope}\`
+
+## Discovery Commands
+
+\`\`\`bash
+${commandPrefix} help
+${commandPrefix} commands
+${commandPrefix} usage ralph
+${commandPrefix} quickstart
+${commandPrefix} install-prompt
+${commandPrefix} codex-app
+\`\`\`
+
+## Dollar Commands
+
+- \`$DF\`: fast design/content fix. Use for color, copy, label, spacing, translation, or small UI edits.
+- \`$SKS\`: general Sneakoscope workflow/help route.
+- \`$Ralph\`: clarification-gated autonomous mission route.
+- \`$Research\`: frontier research route.
+- \`$DB\`: database/Supabase safety route.
+- \`$GX\`: deterministic visual context route.
+- \`$Help\`: explain installed commands and workflows.
+
+The prompt optimization pipeline also runs without a dollar command and infers the lightest route automatically.
+
+## Common App Prompts
+
+- "Use Sneakoscope Ralph mode to prepare this task."
+- "$DF change the button text to English."
+- "Run the latest Ralph mission with the sealed decision contract."
+- "Use SKS DB safety before touching database or Supabase files."
+- "Use SKS research mode for this investigation."
+
+## CLI Bridge
+
+Codex App can call the same project-local control surface through terminal commands:
+
+\`\`\`bash
+${commandPrefix} setup
+${commandPrefix} doctor
+${commandPrefix} ralph prepare "task"
+${commandPrefix} ralph status latest
+${commandPrefix} research prepare "topic"
+${commandPrefix} db scan --migrations
+\`\`\`
+
+The hooks file routes Codex App tool events through SKS guards for no-question mode, DB safety, permission requests, and done-gate checks.
+`;
+}
+
 async function installSkills(root) {
   const skills = {
+    'DF': `---\nname: DF\ndescription: Fast design/content fix mode for $DF requests and inferred simple edits such as text color, copy, labels, spacing, or translation.\n---\n\nYou are running SKS DF mode.\n\nPurpose:\n- Quickly convert a small design/content request into the exact implementation change.\n- Use for requests like 글자 색 바꿔줘, 내용을 영어로 바꿔줘, button label 수정, spacing 조정, copy replacement, simple style tweaks.\n\nRules:\n- Do not start Ralph, Research, eval, or broad redesign unless the user explicitly asks.\n- Do not ask for more requirements when the target can be inferred from local context.\n- Inspect only the files needed to locate the target.\n- Make the smallest scoped edit that satisfies the request.\n- Preserve the existing design system and component patterns.\n- Run only cheap verification when useful, such as syntax check, focused test, or local render check for visual risk.\n- Final response should be short: what changed and any verification.\n`,
+    'SKS': `---\nname: SKS\ndescription: General Sneakoscope Codex command route for $SKS usage, setup, status, and workflow help.\n---\n\nUse the local SKS control surface. Prefer these discovery commands when the user asks what is available: sks commands, sks usage <topic>, sks quickstart, sks codex-app, sks install-prompt. If implementation is requested, route to the lightest matching SKS path.\n`,
+    'Ralph': `---\nname: Ralph\ndescription: Dollar-command route for SKS Ralph mandatory clarification and no-question mission workflows.\n---\n\nUse when the user invokes $Ralph or requests a clarification-gated autonomous implementation mission. Prepare with sks ralph prepare, answer/seal required slots when answers are provided, then run only after decision-contract.json exists.\n`,
+    'Research': `---\nname: Research\ndescription: Dollar-command route for SKS Research frontier discovery workflows.\n---\n\nUse when the user invokes $Research or asks for research, hypotheses, new mechanisms, falsification, or testable predictions. Prefer sks research prepare and sks research run. Do not use for ordinary code edits.\n`,
+    'DB': `---\nname: DB\ndescription: Dollar-command route for database and Supabase safety checks.\n---\n\nUse when the user invokes $DB or the task touches SQL, Supabase, Postgres, migrations, Prisma, Drizzle, Knex, MCP database tools, or production data. Run or follow sks db policy, sks db scan, sks db classify, and sks db check. Destructive database operations remain forbidden.\n`,
+    'GX': `---\nname: GX\ndescription: Dollar-command route for deterministic GX visual context cartridges.\n---\n\nUse when the user invokes $GX or asks for architecture/context visualization through SKS. Prefer sks gx init, render, validate, drift, and snapshot. vgraph.json remains the source of truth.\n`,
+    'Help': `---\nname: Help\ndescription: Dollar-command route for explaining installed SKS commands and workflows.\n---\n\nUse when the user invokes $Help or asks what commands exist. Prefer concise output from sks commands, sks usage <topic>, sks quickstart, sks aliases, and sks codex-app.\n`,
+    'prompt-pipeline': `---\nname: prompt-pipeline\ndescription: Default SKS prompt optimization pipeline that runs even without an explicit command.\n---\n\nFor every user request, silently extract intent, target surface, constraints, acceptance criteria, risk level, and the smallest safe route. Infer $DF for simple design/content edits. Use Ralph only for work that needs clarification gates, Research only for discovery work, DB only for database-risk work, GX only for visual context artifacts, and eval only when performance or context-quality claims need evidence.\n`,
     'ralph-supervisor': `---\nname: ralph-supervisor\ndescription: Run the Ralph no-question loop after a decision contract is sealed.\n---\n\nYou are the Ralph Supervisor.\n\nRules:\n- Never ask the user during Ralph run.\n- Use decision-contract.json and the decision ladder.\n- Continue until done-gate.json passes or safe scope is completed with explicit limitation.\n- Keep outputs bounded. Write raw logs to files and summarize only tails.\n- Database destructive operations are never allowed.\n- Write progress to .sneakoscope mission files.\n`,
     'ralph-resolver': `---\nname: ralph-resolver\ndescription: Resolve newly discovered ambiguity during Ralph using the sealed decision ladder, without asking the user.\n---\n\nResolve ambiguity in this order: seed contract, explicit answers, approved defaults, AGENTS.md, current code/tests, smallest reversible change, defer optional scope. Never ask the user. If database risk is involved, prefer read-only, no-op, local-only migration file, or safe limitation; never run destructive SQL.\n`,
     'hproof-claim-ledger': `---\nname: hproof-claim-ledger\ndescription: Extract atomic claims and classify support status.\n---\n\nEvery factual statement must become an atomic claim. Unsupported critical claims cannot be used for implementation or final answer. Database claims require DB safety evidence.\n`,
@@ -198,8 +321,10 @@ async function installSkills(root) {
     'design-artifact-expert': `---\nname: design-artifact-expert\ndescription: Create or revise high-fidelity HTML, UI, prototype, deck-like, or visual design artifacts using project design context, variations, and rendered verification.\n---\n\nUse when the user asks for design, UI, prototype, HTML artifact, landing page, deck-like visual work, interaction design, or visual refinement.\n\nWorkflow:\n1. Understand the artifact, audience, constraints, fidelity, variants, and existing brand/design system.\n2. Inspect local code, assets, screenshots, or design-system docs before inventing visuals. If context exists, follow its visual vocabulary.\n3. Build the actual usable screen or artifact first; avoid empty landing-page framing unless the task is explicitly marketing.\n4. Use descriptive HTML filenames. Keep large artifacts split into small support files when needed.\n5. For screens/slides, add data-screen-label attributes for comment context. Slide labels are 1-indexed.\n6. Preserve state for decks, videos, or multi-step prototypes with localStorage when refresh continuity matters.\n7. Expose a small Tweaks surface for useful variants such as layout, density, color, copy, or interaction options.\n8. Verify the artifact renders cleanly in a browser or preview. For design tasks, set done-gate.json design_verification_required/present fields and cite evidence.\n\nQuality bar:\n- Root design decisions in available assets and components.\n- Use restrained, domain-appropriate layout and typography.\n- Avoid text overlap, unreadable controls, decorative clutter, one-note palettes, and placeholder-only deliverables.\n- Prefer icons and familiar controls for tool actions, and make repeated UI dimensions stable.\n`
   };
   for (const [name, content] of Object.entries(skills)) {
-    const dir = path.join(root, '.agents', 'skills', name);
-    await ensureDir(dir);
-    await writeTextAtomic(path.join(dir, 'SKILL.md'), `${content.trim()}\n`);
+    for (const base of ['.codex/skills', '.agents/skills']) {
+      const dir = path.join(root, base, name);
+      await ensureDir(dir);
+      await writeTextAtomic(path.join(dir, 'SKILL.md'), `${content.trim()}\n`);
+    }
   }
 }