@rvry/mcp 1.3.0 → 1.4.0

package/README.md

@@ -18,12 +18,44 @@ The wizard will:
 2. Auto-detect supported clients on your machine
 3. Configure them automatically
 
-Supported clients: **Claude Code**, **Claude Desktop**
+Supported clients: **Claude Code**, **Claude Desktop / Co-Work**, **Codex**
 
 Restart any running clients after setup, and RVRY is ready.
 
+### Codex
+
+To configure only Codex, run:
+
+```bash
+npx --yes --package @rvry/mcp@latest rvry-mcp setup --client codex
+```
+
+The installer registers the `rvry` MCP server through the Codex CLI and installs seven namespaced skills under `~/.agents/skills/`:
+
+| Skill                 | Tool            | What it does                                                                  |
+|-----------------------|-----------------|-------------------------------------------------------------------------------|
+| `$rvry`               | `rvry`          | Reflective answering: observation first, then an answer under its commitments |
+| `$rvry-think`         | `think`         | Quick structured analysis of a question                                       |
+| `$rvry-think-model`   | `think_model`   | Apply one of the 18 named mental models                                       |
+| `$rvry-deepthink`     | `deepthink`     | Deep multi-round analysis of a hard question                                  |
+| `$rvry-problem-solve` | `problem_solve` | Structured decision-making before commitment                                  |
+| `$rvry-challenge`     | `challenge`     | Adversarial stress-testing with a GO / NO GO verdict                          |
+| `$rvry-meta`          | `meta`          | Metacognitive observation on a topic                                          |
+
+For example: `$rvry-deepthink Should we split the billing service?`
+
+The installer does not add a Codex lifecycle hook, and none is required. The MCP registration and skill files contain the integration. After installing or updating RVRY, restart existing Codex sessions or reload skills so they discover the new files.
+
 ### Manual Configuration
 
+For Codex, register the MCP server with its CLI:
+
+```bash
+codex mcp add rvry --env RVRY_TOKEN=rvry_your_token -- npx --yes --package @rvry/mcp@latest rvry-mcp
+```
+
+This manual command creates or overwrites the `rvry` registration, but it registers the tool server only. Use the setup command above to install the seven Codex skills as well. Do not print the registration as a verification step: current Codex CLI output includes the literal `RVRY_TOKEN`.
+
 For any MCP client that supports **stdio transport**, add this to your MCP config:
 
 ```json
@@ -42,28 +74,28 @@ Get your token at [rvry.ai/dashboard](https://rvry.ai/dashboard) after signing u
 
 ## Tools
 
-| Tool | What it does | Plan |
-|------|-------------|------|
-| **`think`** | Structured analysis for questions that need structure, not a saga. 1–3 analytical rounds; simple questions complete in one. | Free+ |
-| **`deepthink`** | Extended multi-round analysis for high-stakes questions. Catches assumptions, tests them, and doesn't let your AI wrap up until it's dealt with what it found. | Free+ |
-| **`rvry`** | Reflective answering. A protected observation round surfaces the commitments the answer must honor, then the answer is produced under them — with a ledger showing the fate of every commitment. | Free+ |
-| **`think_model`** | Applies one named mental model — 18 available, from Five Whys to Red Team — as a structured session with model-specific stages and synthesis. | Free+ |
-| **`problem_solve`** | Structured decision-making: orient, anticipate, generate, evaluate, commit. Includes a six-bias audit and written reversal conditions before the recommendation is final. | Pro+ |
-| **`challenge`** | Adversarial stress-testing. Finds weaknesses, tests assumptions, surfaces edge cases, and closes with a GO / CONDITIONAL GO / NO GO verdict. | Pro+ |
-| **`meta`** | Sustained metacognitive observation. Examines how your AI is thinking, not just what it's thinking. | Max |
+| Tool                | What it does                                                                                                                                                                                     | Plan  |
+|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------|
+| **`think`**         | Structured analysis for questions that need structure, not a saga. 1–3 analytical rounds; simple questions complete in one.                                                                      | Free+ |
+| **`deepthink`**     | Extended multi-round analysis for high-stakes questions. Catches assumptions, tests them, and doesn't let your AI wrap up until it's dealt with what it found.                                   | Free+ |
+| **`rvry`**          | Reflective answering. A protected observation round surfaces the commitments the answer must honor, then the answer is produced under them — with a ledger showing the fate of every commitment. | Free+ |
+| **`think_model`**   | Applies one named mental model — 18 available, from Five Whys to Red Team — as a structured session with model-specific stages and synthesis.                                                    | Free+ |
+| **`problem_solve`** | Structured decision-making: orient, anticipate, generate, evaluate, commit. Includes a six-bias audit and written reversal conditions before the recommendation is final.                        | Pro+  |
+| **`challenge`**     | Adversarial stress-testing. Finds weaknesses, tests assumptions, surfaces edge cases, and closes with a GO / CONDITIONAL GO / NO GO verdict.                                                     | Pro+  |
+| **`meta`**          | Sustained metacognitive observation. Examines how your AI is thinking, not just what it's thinking.                                                                                              | Max   |
 
 ## The 18 Mental Models
 
-`think_model` (and `/think-model` in Claude Code) runs exactly one model as an engine-enforced session — fixed stages, model-specific output structure, no early exits.
+`think_model` (`/think-model` in Claude Code, `$rvry-think-model` in Codex) runs exactly one model as an engine-enforced session — fixed stages, model-specific output structure, no early exits.
 
-| | | |
-|---|---|---|
-| `five-whys` | `rubber-duck` | `assumption-surfacing` |
-| `fermi-estimation` | `abstraction-laddering` | `decomposition` |
-| `constraint-relaxation` | `first-principles` | `steelmanning` |
-| `opportunity-cost` | `trade-off-matrix` | `time-horizon-shifting` |
-| `reversibility` | `pre-mortem` | `inversion` |
-| `second-order-effects` | `red-team` | `impact-effort-grid` |
+|                         |                         |                         |
+|-------------------------|-------------------------|-------------------------|
+| `five-whys`             | `rubber-duck`           | `assumption-surfacing`  |
+| `fermi-estimation`      | `abstraction-laddering` | `decomposition`         |
+| `constraint-relaxation` | `first-principles`      | `steelmanning`          |
+| `opportunity-cost`      | `trade-off-matrix`      | `time-horizon-shifting` |
+| `reversibility`         | `pre-mortem`            | `inversion`             |
+| `second-order-effects`  | `red-team`              | `impact-effort-grid`    |
 
 ```
 /think-model pre-mortem we're migrating the billing system to event sourcing next quarter
@@ -77,15 +109,15 @@ A Five Whys session ends with a verified causal chain and a root-cause fix. A Pr
 
 When you run setup and select Claude Code, the wizard installs these commands:
 
-| Command | Tool | What it does |
-|---------|------|-------------|
-| `/think` | think | Quick structured analysis of a question |
-| `/deepthink` | deepthink | Deep multi-round analysis of a hard question |
-| `/rvry` | rvry | Reflective answering — self-observation first, then the answer |
-| `/think-model` | think_model | Apply one named mental model to a problem |
-| `/problem-solve` | problem_solve | Structured decision-making, stress-tested before commitment |
-| `/challenge` | challenge | Adversarial stress-test with a GO / NO GO verdict |
-| `/meta` | meta | Metacognitive observation on a topic |
+| Command          | Tool          | What it does                                                   |
+|------------------|---------------|----------------------------------------------------------------|
+| `/think`         | think         | Quick structured analysis of a question                        |
+| `/deepthink`     | deepthink     | Deep multi-round analysis of a hard question                   |
+| `/rvry`          | rvry          | Reflective answering — self-observation first, then the answer |
+| `/think-model`   | think_model   | Apply one named mental model to a problem                      |
+| `/problem-solve` | problem_solve | Structured decision-making, stress-tested before commitment    |
+| `/challenge`     | challenge     | Adversarial stress-test with a GO / NO GO verdict              |
+| `/meta`          | meta          | Metacognitive observation on a topic                           |
 
 Usage: type `/deepthink [your question]` in Claude Code. Each command routes to the corresponding RVRY tool and includes rendering instructions so analysis appears as visible markdown rather than hidden in tool calls.
 
@@ -95,23 +127,39 @@ Usage: type `/deepthink [your question]` in Claude Code. Each command routes to
 
 Commands are installed to `~/.claude/commands/`.
 
+## Codex Skills
+
+When you run setup with `--client codex`, the installer writes the seven skills listed above to `~/.agents/skills/`. Each skill includes Codex metadata declaring the `rvry` MCP dependency and disabling implicit invocation, so RVRY runs only when you explicitly select a namespaced skill. The skills preserve the same multi-round continuation, visible observation/reflection, harvest, and optional recording behavior as the Claude Code workflows.
+
+The metadata identifies the already configured stdio dependency; it cannot carry the package arguments or `RVRY_TOKEN` needed to install RVRY by itself. Use the setup command above as the complete install and repair path.
+
+Invoke a skill by name followed by the question, for example:
+
+```text
+$rvry-think-model pre-mortem we're migrating billing to event sourcing next quarter
+```
+
+Re-run setup to refresh RVRY-owned skill files and metadata after a package update. Changed RVRY-owned files are backed up beside the original with a `.bak` suffix. New Codex sessions discover them automatically; restart an existing session or reload skills after installation. No Codex lifecycle hook is installed or required.
+
 ## Parameters
 
 All tools accept:
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `input` | string | Yes | Your question (new session) or analysis findings (continuation). |
-| `sessionId` | string | No | Session ID for continuing an existing session. |
-| `skipScoping` | boolean | No | Skip the scoping questions phase and begin analysis immediately. |
-| `userConstraints` | string[] | No | User-stated directives or requirements to track across rounds. |
-| `requiresCurrentData` | boolean | No | Set to `true` when the question depends on facts, policies, prices, or events that may have changed. Seeds a verification constraint that persists across all rounds. |
-| `record` | boolean | No | When `true` on every call, the local client archives each round's body to `.rvry/<op>/<timestamp>-<slug>/round-N-<label>.md`. Passed from slash commands via the `--record` flag. |
-| `harvest` | object | No | Final-call-only. The client includes its synthesis (`title`, `summary`, `keyFindings`, `shimmer`, `openQuestions`, `followUps`, plus operation-specific fields) so it can be persisted to the local session file. |
-| `rounds` | array | No | Final-call-only, present only when `--record` was set. Array of `{round, mode, body}` for each analytical round. |
+| Parameter             | Type     | Required | Description                                                                                                                                                                                                       |
+|-----------------------|----------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `input`               | string   | Yes      | Your question (new session) or analysis findings (continuation).                                                                                                                                                  |
+| `sessionId`           | string   | No       | Session ID for continuing an existing session.                                                                                                                                                                    |
+| `skipScoping`         | boolean  | No       | Skip the scoping questions phase and begin analysis immediately.                                                                                                                                                  |
+| `userConstraints`     | string[] | No       | User-stated directives or requirements to track across rounds.                                                                                                                                                    |
+| `requiresCurrentData` | boolean  | No       | Set to `true` when the question depends on facts, policies, prices, or events that may have changed. Seeds a verification constraint that persists across all rounds.                                             |
+| `record`              | boolean  | No       | When `true` on every call, the local client archives each round's body to `.rvry/<op>/<timestamp>-<slug>/round-N-<label>.md`. Passed from slash commands via the `--record` flag.                                 |
+| `harvest`             | object   | No       | Final-call-only. The client includes its synthesis (`title`, `summary`, `keyFindings`, `shimmer`, `openQuestions`, `followUps`, plus operation-specific fields) so it can be persisted to the local session file. |
+| `rounds`              | array    | No       | Final-call-only, present only when `--record` was set. Array of `{round, mode, body}` for each analytical round.                                                                                                  |
 
 `think_model` additionally requires `modelName` (one of the 18 model ids) on the first call.
 
+**Required user-input pauses:** A `scoping` response includes `scopingQuestions`; ask the user and resume with the same `sessionId`. During analysis, the client exposes `mustAskUser: true` when the engine requires an answer before it can continue. `blockingUnknowns` is included only under that exact gate and is withheld otherwise. Ask the user, stop the current turn, then continue the same session with an evidence-bearing `RESOLVE Cn:` constraint update for the user's answer; a raw answer alone does not resolve the engine constraint.
+
 **When to use `requiresCurrentData`:** Any question about regulations, pricing, legal rulings, market conditions, API specifications, or current events. The engine will require the model to explicitly classify every cited fact as either verified-current or training-data-dependent before concluding.
 
 **SHIMMER display:** Most sessions open with a self-observation round. The model displays `RVRY SHIMMER` with the revery definition before its observation — this is the priming phase, where the model observes its own processing before structured analysis begins. The observation is preserved verbatim in the final harvest.
@@ -128,18 +176,18 @@ The model keeps working not because it was told to think harder, but because it
 
 ## Pricing
 
-| Plan | Sessions | Tools | Price |
-|------|----------|-------|-------|
-| Free | 5/month | `think`, `deepthink`, `rvry`, `think_model` | $0 |
-| Pro | 21/month | Free tools + `problem_solve`, `challenge` | $20/mo |
-| Max | Unlimited | All tools, including `meta` | $99/mo |
+| Plan | Sessions  | Tools                                       | Price  |
+|------|-----------|---------------------------------------------|--------|
+| Free | 5/month   | `think`, `deepthink`, `rvry`, `think_model` | $0     |
+| Pro  | 21/month  | Free tools + `problem_solve`, `challenge`   | $20/mo |
+| Max  | Unlimited | All tools, including `meta`                 | $99/mo |
 
 Sign up at [rvry.ai](https://rvry.ai).
 
 ## Requirements
 
 - Node.js ≥ 18
-- An MCP client with stdio transport support (Claude Code, Claude Desktop, and most others)
+- An MCP client with stdio transport support (Claude Code, Claude Desktop, Codex, and most others)
 
 ## License
 

package/dist/client.d.ts

@@ -18,6 +18,10 @@ export interface ThinkResponse {
     prompt: string;
     instruction: string;
     scopingQuestions?: ScopingQuestion[];
+    /** True when active blocking unknowns require user input before continuing. */
+    mustAskUser?: boolean;
+    /** User-facing descriptions of the blocking unknowns that must be resolved. */
+    blockingUnknowns?: string[];
     usage?: {
         used: number;
         limit: number;

package/dist/codex-adapter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Codex-native installation helpers for @rvry/mcp.
+ *
+ * This module deliberately uses argv arrays for every Codex invocation. Tokens
+ * are never interpolated into a shell command or written to captured output.
+ */
+declare const SKILL_NAME_BY_SOURCE_FILE: {
+    readonly 'rvry.md': "rvry";
+    readonly 'think.md': "rvry-think";
+    readonly 'think-model.md': "rvry-think-model";
+    readonly 'deepthink.md': "rvry-deepthink";
+    readonly 'problem-solve.md': "rvry-problem-solve";
+    readonly 'challenge.md': "rvry-challenge";
+    readonly 'meta.md': "rvry-meta";
+};
+type CodexSkillName = (typeof SKILL_NAME_BY_SOURCE_FILE)[keyof typeof SKILL_NAME_BY_SOURCE_FILE];
+export type CodexCommandRunner = (command: string, args: readonly string[]) => string;
+export interface CodexSkillSource {
+    file: string;
+    content: string;
+    description: string;
+    label: string;
+    argumentHint: string;
+}
+export interface CodexSkillInstallResult {
+    name: CodexSkillName;
+    status: 'ok' | 'updated' | 'unchanged' | 'error';
+    path: string;
+    metadataPath?: string;
+    backupPath?: string;
+    metadataBackupPath?: string;
+    error?: string;
+}
+/** Detect whether a usable Codex CLI executable is available. */
+export declare function isCodexCliAvailable(runner?: CodexCommandRunner): boolean;
+/**
+ * Register RVRY as a global Codex MCP server and verify the resulting config.
+ *
+ * The named entry is always re-applied through `codex mcp add`. Current Codex
+ * omits placement fields such as `environment_id` from `mcp get --json`, so a
+ * projected exact match cannot prove the server will execute locally. The add
+ * operation clears hidden overrides; unrelated inspection failures fail closed.
+ */
+export declare function configureCodexMcp(token: string, runner?: CodexCommandRunner): 'ok' | 'updated' | 'unchanged' | 'error';
+/** Convert one Claude slash-command definition into a Codex-native SKILL.md. */
+export declare function buildCodexSkill(source: CodexSkillSource): string;
+/** Build Codex product metadata for one explicitly invoked RVRY skill. */
+export declare function buildCodexSkillMetadata(source: Pick<CodexSkillSource, 'file'>): string;
+/** Install the seven namespaced RVRY skills below an injected global skill root. */
+export declare function installCodexSkills(skillsRoot: string, sources: readonly CodexSkillSource[]): CodexSkillInstallResult[];
+export {};

package/dist/codex-adapter.js

@@ -0,0 +1,346 @@
+/**
+ * Codex-native installation helpers for @rvry/mcp.
+ *
+ * This module deliberately uses argv arrays for every Codex invocation. Tokens
+ * are never interpolated into a shell command or written to captured output.
+ */
+import { execFileSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { basename, join } from 'path';
+const CODEX_SERVER_NAME = 'rvry';
+const RVRY_NPX_ARGS = ['--yes', '--package', '@rvry/mcp@latest', 'rvry-mcp'];
+const SKILL_NAME_BY_SOURCE_FILE = {
+    'rvry.md': 'rvry',
+    'think.md': 'rvry-think',
+    'think-model.md': 'rvry-think-model',
+    'deepthink.md': 'rvry-deepthink',
+    'problem-solve.md': 'rvry-problem-solve',
+    'challenge.md': 'rvry-challenge',
+    'meta.md': 'rvry-meta',
+};
+const SKILL_METADATA = {
+    rvry: {
+        displayName: 'RVRY',
+        shortDescription: 'Metacognitive constraint-guided reasoning',
+        defaultPrompt: 'Use $rvry to reason through this request with RVRY.',
+    },
+    'rvry-think': {
+        displayName: 'RVRY Think',
+        shortDescription: 'Structured multi-round reasoning',
+        defaultPrompt: 'Use $rvry-think to analyze this question systematically.',
+    },
+    'rvry-think-model': {
+        displayName: 'RVRY Think Model',
+        shortDescription: 'Reason with a named mental model',
+        defaultPrompt: 'Use $rvry-think-model to apply a named mental model to this problem.',
+    },
+    'rvry-deepthink': {
+        displayName: 'RVRY Deepthink',
+        shortDescription: 'Adaptive pre-mortem failure analysis',
+        defaultPrompt: 'Use $rvry-deepthink to deeply analyze this difficult question.',
+    },
+    'rvry-problem-solve': {
+        displayName: 'RVRY Problem Solve',
+        shortDescription: 'Convergent five-step decision pipeline',
+        defaultPrompt: 'Use $rvry-problem-solve to reach a stress-tested decision.',
+    },
+    'rvry-challenge': {
+        displayName: 'RVRY Challenge',
+        shortDescription: 'Adversarial proposal stress testing',
+        defaultPrompt: 'Use $rvry-challenge to stress-test this proposal before commitment.',
+    },
+    'rvry-meta': {
+        displayName: 'RVRY Meta',
+        shortDescription: 'Sustained metacognitive observation',
+        defaultPrompt: 'Use $rvry-meta to observe the reasoning process around this topic.',
+    },
+};
+const defaultCommandRunner = (command, args) => execFileSync(command, [...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+});
+function errorText(error) {
+    if (!(error instanceof Error)) {
+        return String(error);
+    }
+    const processError = error;
+    const render = (value) => {
+        if (typeof value === 'string')
+            return value;
+        if (value instanceof Uint8Array)
+            return Buffer.from(value).toString('utf8');
+        return '';
+    };
+    return [error.message, render(processError.stdout), render(processError.stderr)]
+        .filter(Boolean)
+        .join('\n');
+}
+function isMissingServerError(error) {
+    return /No MCP server named\s+['"]?rvry['"]?\s+found/i.test(errorText(error));
+}
+function parseMcpConfig(output) {
+    try {
+        const parsed = JSON.parse(output);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function stringRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const entries = Object.entries(value);
+    if (entries.some(([, item]) => typeof item !== 'string'))
+        return null;
+    return Object.fromEntries(entries);
+}
+function isExpectedMcpConfig(config, token) {
+    const transport = config.transport;
+    const args = transport?.args;
+    const env = stringRecord(transport?.env);
+    return (config.name === CODEX_SERVER_NAME &&
+        config.enabled === true &&
+        transport?.type === 'stdio' &&
+        transport.command === 'npx' &&
+        Array.isArray(args) &&
+        args.length === RVRY_NPX_ARGS.length &&
+        args.every((arg, index) => arg === RVRY_NPX_ARGS[index]) &&
+        env?.RVRY_TOKEN === token &&
+        Object.keys(env).length === 1 &&
+        Array.isArray(transport.env_vars) &&
+        transport.env_vars.length === 0 &&
+        transport.cwd == null &&
+        config.enabled_tools == null &&
+        config.disabled_tools == null &&
+        config.startup_timeout_sec == null &&
+        config.tool_timeout_sec == null);
+}
+function readCodexMcpConfig(runner) {
+    const output = runner('codex', ['mcp', 'get', CODEX_SERVER_NAME, '--json']);
+    const config = parseMcpConfig(output);
+    if (!config) {
+        throw new Error('Codex returned invalid MCP configuration JSON.');
+    }
+    return config;
+}
+/** Detect whether a usable Codex CLI executable is available. */
+export function isCodexCliAvailable(runner = defaultCommandRunner) {
+    try {
+        runner('codex', ['--version']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Register RVRY as a global Codex MCP server and verify the resulting config.
+ *
+ * The named entry is always re-applied through `codex mcp add`. Current Codex
+ * omits placement fields such as `environment_id` from `mcp get --json`, so a
+ * projected exact match cannot prove the server will execute locally. The add
+ * operation clears hidden overrides; unrelated inspection failures fail closed.
+ */
+export function configureCodexMcp(token, runner = defaultCommandRunner) {
+    let existing = null;
+    let existed = false;
+    try {
+        existing = readCodexMcpConfig(runner);
+        existed = true;
+    }
+    catch (error) {
+        if (!isMissingServerError(error))
+            return 'error';
+    }
+    const projectedConfigWasExpected = existing
+        ? isExpectedMcpConfig(existing, token)
+        : false;
+    try {
+        runner('codex', [
+            'mcp',
+            'add',
+            CODEX_SERVER_NAME,
+            '--env',
+            `RVRY_TOKEN=${token}`,
+            '--',
+            'npx',
+            ...RVRY_NPX_ARGS,
+        ]);
+        const verified = readCodexMcpConfig(runner);
+        if (!verified || !isExpectedMcpConfig(verified, token)) {
+            return 'error';
+        }
+        if (!existed)
+            return 'ok';
+        return projectedConfigWasExpected ? 'unchanged' : 'updated';
+    }
+    catch {
+        return 'error';
+    }
+}
+function resolveSkillName(sourceFile) {
+    const name = SKILL_NAME_BY_SOURCE_FILE[basename(sourceFile)];
+    if (!name) {
+        throw new Error(`Unsupported RVRY Codex skill source: ${sourceFile}`);
+    }
+    return name;
+}
+function replaceSlashReferences(content) {
+    const replacements = [
+        ['/problem-solve', '$rvry-problem-solve'],
+        ['/think-model', '$rvry-think-model'],
+        ['/deepthink', '$rvry-deepthink'],
+        ['/challenge', '$rvry-challenge'],
+        ['/think', '$rvry-think'],
+        ['/meta', '$rvry-meta'],
+        ['/rvry', '$rvry'],
+    ];
+    let result = content;
+    for (const [slashName, skillName] of replacements) {
+        const escaped = slashName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const pattern = new RegExp(`(^|[^A-Za-z0-9:/])${escaped}(?=$|[^A-Za-z0-9_-])`, 'gm');
+        result = result.replace(pattern, (_match, prefix) => `${prefix}${skillName}`);
+    }
+    return result;
+}
+function replaceClaudeQuestionSchema(content) {
+    return content.replace(/(^3\. For each BLOCKING uncertainty not answered in the proposal, )ask via AskUserQuestion:\r?\n(?: {3}-[^\r\n]*(?:\r?\n|$)){4}/m, '$1ask the user one concise blocking question in plain text, end the turn, and wait for the answer before continuing.\n');
+}
+function adaptSkillBody(content) {
+    return replaceSlashReferences(replaceClaudeQuestionSchema(content))
+        .replaceAll('$ARGUMENTS', 'SKILL_INPUT')
+        .replaceAll('ask via AskUserQuestion:', 'ask the user directly in one concise plain-text question, then end the turn and wait:')
+        .replaceAll('AskUserQuestion', 'a concise plain-text question');
+}
+function codexPreamble(skillName, argumentHint) {
+    const challengeScopingNote = skillName === 'rvry-challenge'
+        ? '- For the first `challenge` call, pass `skipScoping: true` after completing Phase 0.5 or when `--auto` skips that scan. Phase 0.5 already handles scoping, so do not ask the engine to repeat it.\n'
+        : '';
+    return `# Codex RVRY adapter contract
+
+Invoke this workflow as \`$${skillName} ${argumentHint}\`. SKILL_INPUT is the user's request associated with \`$${skillName}\`. Remove the skill mention itself before treating the remainder as the operation input.
+
+- This workflow requires the MCP server named \`rvry\`. Call the requested tool from that server. If the server or tool is unavailable, stop and tell the user to run RVRY setup; never imitate or replace the RVRY workflow yourself.
+- When the request depends on current facts, policies, prices, regulations, software behavior, or events, pass \`requiresCurrentData: true\` on the first call and every continuation call.
+- Preserve the returned \`sessionId\` and use that same session for every continuation. Never start a replacement session to avoid an unresolved round.
+- If a response has status \`scoping\` and includes \`scopingQuestions\`, ask the user those questions, end the turn, and wait. Resume the same \`sessionId\` after the user answers.
+- If a response has \`mustAskUser: true\` or non-empty \`blockingUnknowns\`, record each matching active \`BLOCKING_UNKNOWN\` constraint ID from the returned prompt, ask the blocking question in plain text, end the turn, and wait.
+- After the user answers a blocking unknown, do not send the raw answer as a continuation. Resume the same \`sessionId\` with an analytical input containing \`Constraint Updates\`, then \`RESOLVE Cn: The user confirmed that <blocking unknown text>: <user answer>.\`, then \`End Constraint Updates\`. Use the actual matching constraint ID, unknown text, and answer; resolve only answered unknowns and never invent evidence.
+${challengeScopingNote}- Continue the tool loop for \`shimmer\`, \`orient\`, and \`active\` responses. A turn may exit the workflow only after the tool returns status \`complete\`, except for a required user-input pause or a surfaced setup/error condition.
+`;
+}
+/** Convert one Claude slash-command definition into a Codex-native SKILL.md. */
+export function buildCodexSkill(source) {
+    const skillName = resolveSkillName(source.file);
+    const taskTrigger = source.description.replace(/\s+/g, ' ').trim().replace(/[.!?]+$/, '');
+    const normalizedTrigger = `${taskTrigger.charAt(0).toLowerCase()}${taskTrigger.slice(1)}`;
+    const description = `Run RVRY's ${normalizedTrigger} workflow. Invoke explicitly as $${skillName}.`;
+    const body = adaptSkillBody(source.content).trim();
+    return [
+        '---',
+        `name: ${skillName}`,
+        `description: ${JSON.stringify(description)}`,
+        '---',
+        '',
+        codexPreamble(skillName, source.argumentHint).trim(),
+        '',
+        '## RVRY operation workflow',
+        '',
+        body,
+        '',
+    ].join('\n');
+}
+/** Build Codex product metadata for one explicitly invoked RVRY skill. */
+export function buildCodexSkillMetadata(source) {
+    const skillName = resolveSkillName(source.file);
+    const metadata = SKILL_METADATA[skillName];
+    return [
+        'interface:',
+        `  display_name: ${JSON.stringify(metadata.displayName)}`,
+        `  short_description: ${JSON.stringify(metadata.shortDescription)}`,
+        `  default_prompt: ${JSON.stringify(metadata.defaultPrompt)}`,
+        'dependencies:',
+        '  tools:',
+        '    - type: "mcp"',
+        '      value: "rvry"',
+        '      description: "RVRY reasoning session server"',
+        '      transport: "stdio"',
+        '      command: "npx"',
+        'policy:',
+        '  allow_implicit_invocation: false',
+        '',
+    ].join('\n');
+}
+/** Install the seven namespaced RVRY skills below an injected global skill root. */
+export function installCodexSkills(skillsRoot, sources) {
+    return sources.map((source) => {
+        let name;
+        try {
+            name = resolveSkillName(source.file);
+        }
+        catch (error) {
+            return {
+                name: 'rvry',
+                status: 'error',
+                path: skillsRoot,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        const directory = join(skillsRoot, name);
+        const path = join(directory, 'SKILL.md');
+        const backupPath = `${path}.bak`;
+        const metadataDirectory = join(directory, 'agents');
+        const metadataPath = join(metadataDirectory, 'openai.yaml');
+        const metadataBackupPath = `${metadataPath}.bak`;
+        try {
+            const content = buildCodexSkill(source);
+            const metadata = buildCodexSkillMetadata(source);
+            mkdirSync(directory, { recursive: true });
+            mkdirSync(metadataDirectory, { recursive: true });
+            const skillExists = existsSync(path);
+            const metadataExists = existsSync(metadataPath);
+            const previous = skillExists ? readFileSync(path, 'utf8') : undefined;
+            const previousMetadata = metadataExists ? readFileSync(metadataPath, 'utf8') : undefined;
+            const skillChanged = previous !== content;
+            const metadataChanged = previousMetadata !== metadata;
+            if (!skillChanged && !metadataChanged) {
+                return { name, status: 'unchanged', path, metadataPath };
+            }
+            let writtenBackupPath;
+            let writtenMetadataBackupPath;
+            if (skillChanged) {
+                if (previous !== undefined) {
+                    writeFileSync(backupPath, previous, 'utf8');
+                    writtenBackupPath = backupPath;
+                }
+                writeFileSync(path, content, 'utf8');
+            }
+            if (metadataChanged) {
+                if (previousMetadata !== undefined) {
+                    writeFileSync(metadataBackupPath, previousMetadata, 'utf8');
+                    writtenMetadataBackupPath = metadataBackupPath;
+                }
+                writeFileSync(metadataPath, metadata, 'utf8');
+            }
+            const status = !skillExists && !metadataExists ? 'ok' : 'updated';
+            return {
+                name,
+                status,
+                path,
+                metadataPath,
+                backupPath: writtenBackupPath,
+                metadataBackupPath: writtenMetadataBackupPath,
+            };
+        }
+        catch (error) {
+            return {
+                name,
+                status: 'error',
+                path,
+                metadataPath,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    });
+}

package/dist/index.d.ts

@@ -8,7 +8,8 @@
  * Exposes 7 tools (think, think_model, rvry, deepthink, problem_solve,
  * challenge, meta) + RVRY_* backward-compat aliases + MCP Prompts.
  *
- * Also supports `npx --yes --package @rvry/mcp@latest rvry-mcp setup` to install Claude Code commands.
+ * Also supports `npx --yes --package @rvry/mcp@latest rvry-mcp setup` to
+ * configure supported clients and install Claude Code commands or Codex skills.
  */
 import { type Tool } from '@modelcontextprotocol/sdk/types.js';
 import { type RvryTool, type ThinkResponse } from './client.js';

package/dist/index.js

@@ -8,7 +8,8 @@
  * Exposes 7 tools (think, think_model, rvry, deepthink, problem_solve,
  * challenge, meta) + RVRY_* backward-compat aliases + MCP Prompts.
  *
- * Also supports `npx --yes --package @rvry/mcp@latest rvry-mcp setup` to install Claude Code commands.
+ * Also supports `npx --yes --package @rvry/mcp@latest rvry-mcp setup` to
+ * configure supported clients and install Claude Code commands or Codex skills.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -673,12 +674,18 @@ const TOOL_DEFS = [
  * Strip response fields based on status for context-efficient MCP responses.
  *
  * `toolName` is the public MCP tool name of the call in scope. The 'shimmer'
- * status (an engine wire value) passthrough applies to the tools whose
- * observation round is a visible product surface — rvry, deepthink, and
- * problem_solve. The remaining ops keep dropping prompt/instruction on their
- * priming round.
+ * status (an engine wire value) passthrough applies to every public workflow
+ * that executes the engine's observation task. Meta starts directly in its own
+ * active observation pass and therefore never reaches this status.
  */
-const SHIMMER_VISIBLE_TOOLS = new Set(['rvry', 'deepthink', 'problem_solve']);
+const SHIMMER_WORKFLOW_TOOLS = new Set([
+    'rvry',
+    'deepthink',
+    'problem_solve',
+    'think',
+    'challenge',
+    'think_model',
+]);
 function stripResponse(result, question, toolName) {
     const stripped = {
         sessionId: result.sessionId,
@@ -693,13 +700,21 @@ function stripResponse(result, question, toolName) {
         stripped.prompt = result.prompt;
         stripped.instruction = result.instruction;
     }
-    if (result.status === 'shimmer' && toolName !== undefined && SHIMMER_VISIBLE_TOOLS.has(toolName)) {
+    if (result.status === 'shimmer' && toolName !== undefined && SHIMMER_WORKFLOW_TOOLS.has(toolName)) {
         stripped.prompt = result.prompt;
         stripped.instruction = result.instruction;
     }
     if (result.status === 'orient') {
         stripped.instruction = result.instruction;
     }
+    // Blocking-unknown signals are safe, user-facing protocol fields. Only
+    // expose the unknowns when the engine explicitly requires user input.
+    if (result.mustAskUser === true) {
+        stripped.mustAskUser = true;
+        if (result.blockingUnknowns !== undefined) {
+            stripped.blockingUnknowns = result.blockingUnknowns;
+        }
+    }
     if (result.status === 'complete' && result.harvest) {
         const { constraintTrace, ...harvestSafe } = result.harvest;
         stripped.harvest = harvestSafe;

package/dist/setup.d.ts

@@ -2,26 +2,42 @@
  * @rvry/mcp setup wizard
  *
  * Interactive setup: device auth flow (browser-based) or manual token paste.
- * Auto-detects Claude Code CLI and Claude Desktop, configures both.
+ * Auto-detects Claude Code, Claude Desktop, and Codex, then configures the
+ * selected clients without touching unrelated client state.
  *
  * Usage: npx --yes --package @rvry/mcp@latest rvry-mcp setup
  *        npx --yes --package @rvry/mcp@latest rvry-mcp setup --token <value>
  *        npx --yes --package @rvry/mcp@latest rvry-mcp setup --client code      (Claude Code only)
  *        npx --yes --package @rvry/mcp@latest rvry-mcp setup --client desktop    (Claude Desktop only)
+ *        npx --yes --package @rvry/mcp@latest rvry-mcp setup --client codex      (Codex only)
  */
+import { type CodexSkillSource } from './codex-adapter.js';
+interface ClientDef {
+    /** Display name shown in picker */
+    name: string;
+    /** Short id for --client flag */
+    id: string;
+    /** Pre-select when detected? Defaults to true. */
+    defaultSelected?: boolean;
+    /** Detect if the client is installed */
+    detect: () => boolean;
+    /** Configure the client. Returns a status string for the summary. */
+    configure: (token: string) => 'ok' | 'updated' | 'unchanged' | 'error';
+    /** Shown when the client is not installed */
+    notInstalledHint: string;
+}
+/** All supported clients. Add new clients here. */
+declare const CLIENT_REGISTRY: ClientDef[];
+declare function isSupportedClientId(value: unknown): value is string;
+/** Return every detected client index for an explicit --client selection. */
+declare function selectDetectedClientIndices(availability: readonly boolean[]): number[];
 /** The /think-model shim: one named mental model per session. */
 declare const THINK_MODEL_SHIM_CONTENT: string;
 /** The /think shim. Carries the Difficulty Gate + mode routing. */
 declare const THINK_SHIM_CONTENT: string;
 /** The /rvry shim: 3-round reflective answering with client-owned harvest. */
-declare const RVRY_SHIM_CONTENT = "Call the rvry MCP tool with your question to start a reflective answering session.\n\nQuestion: $ARGUMENTS\n\nARGUMENT PARSING:\n1. If $ARGUMENTS contains the literal flag `--record`, remove it from the question text and REMEMBER that record mode is ON for this session.\n\nROUND 1 \u2014 OBSERVATION (status \"shimmer\"):\n1. The response's prompt field is your observation task. Work through it.\n2. Show the user your FULL observation prose, beginning with the header \"## RVRY | Observation\" and the revery definition, exactly as the instruction field describes. Do NOT show a brief status line.\n3. The commitments that surfaced (FORWARD:/FORBIDDEN:/QUESTION: lines, or the single line NOTHING) are machine-readable bookkeeping: append them to the end of the observation text you send back to the tool, but do NOT show them in the visible display.\n4. REMEMBER your observation text verbatim \u2014 you will pass it as harvest.shimmer on the final call, and you will re-display its prose in the final output.\n5. Call the rvry tool again with your observation text (prose + commitment lines) as input and the sessionId.\n\nROUNDS 2-3 \u2014 ANSWER AND RESOLUTION (status \"active\"):\n1. Read the prompt field \u2014 this is your task. DO NOT display it to the user.\n2. Round 2 is the answer itself, working under the commitments you surfaced. Round 3 (if it occurs) resolves what the answer left unaddressed \u2014 engage each remaining commitment specifically or defer it with a reason.\n3. Show the user your answer as concise formatted markdown.\n4. Call the tool again with your full text as the input parameter, including the sessionId.\n   - If record mode is ON, set `record: true` on every call and REMEMBER your round body as {round, mode, body} for the final call.\n\nFINAL CALL (the call whose response will have status \"complete\"):\nWhen you make the call that completes the session, also construct a `harvest` object on that SAME call:\n- title: a 1-4 word title capturing the topic\n- summary: 3-6 sentences of synthesis, leading with substance\n- keyFindings: 3-7 substantive bullet findings\n- shimmer: the full round-1 observation text you remembered, verbatim\n- constraintLedger: one line per surfaced commitment with its fate \u2014 addressed (and how), deferred (and why), or still open\n- openQuestions: [optional] remaining uncertainties\n- followUps: genuine next-question leads; omit the section if there are none\n\nIf record mode was ON, also include `rounds: [{round, mode, body}, ...]` on that final call with the bodies you remembered per round.\n\nFINAL VISIBLE OUTPUT:\nWhen you present the completed answer to the user, end your visible output with the header \"## RVRY | Reflection\" followed by the round-1 observation prose you remembered (without the machine-readable commitment lines). The reflection is part of the product \u2014 the user sees the answer AND the observation that shaped it.\n\nDO NOT display: the prompt text you received (the round-1 observation prose IS shown in full \u2014 at observation time and again in the final output), the FORWARD/FORBIDDEN/QUESTION commitment lines, constraint tables, quality scores, internal tracking data, or round numbers to the user.";
-declare const SLASH_COMMANDS: {
-    file: string;
-    content: string;
-    label: string;
-    description: string;
-    argumentHint: string;
-}[];
+declare const RVRY_SHIM_CONTENT = "Call the rvry MCP tool with your question to start a reflective answering session.\n\nQuestion: $ARGUMENTS\n\nARGUMENT PARSING:\n1. If $ARGUMENTS contains the literal flag `--record`, remove it from the question text and REMEMBER that record mode is ON for this session.\n\nROUND 1 \u2014 OBSERVATION (status \"shimmer\"):\n1. The response's prompt field is your observation task. Work through it.\n2. Show the user your FULL observation prose, beginning with the header \"## RVRY | Observation\" and the revery definition, exactly as the instruction field describes. Do NOT show a brief status line.\n3. The commitments that surfaced (FORWARD:/FORBIDDEN:/QUESTION: lines, or the single line NOTHING) are machine-readable bookkeeping: append them to the end of the observation text you send back to the tool, but do NOT show them in the visible display.\n4. REMEMBER your observation text verbatim \u2014 you will pass it as harvest.shimmer on the final call, and you will re-display its prose in the final output.\n5. Call the rvry tool again with your observation text (prose + commitment lines) as input and the sessionId.\n\nROUNDS 2-3 \u2014 ANSWER AND RESOLUTION (status \"active\"):\n1. Read the prompt field \u2014 this is your task. DO NOT display it to the user.\n2. Round 2 is the answer itself, working under the commitments you surfaced. Round 3 (if it occurs) resolves what the answer left unaddressed \u2014 engage each remaining commitment specifically or defer it with a reason.\n3. Show the user your answer as concise formatted markdown.\n4. Call the tool again with your full text as the input parameter, including the sessionId.\n   - If record mode is ON, set `record: true` on every call and REMEMBER your round body as {round, mode, body} for the final call.\n\nFINAL CALL (the call whose response will have status \"complete\"):\nWhen you make the call that completes the session, also construct a `harvest` object on that SAME call:\n- title: a 1-4 word title capturing the topic\n- summary: 3-6 sentences of synthesis, leading with substance\n- keyFindings: 3-7 substantive bullet findings\n- shimmer: the full round-1 observation text you remembered, verbatim\n- constraintLedger: one line per surfaced commitment with its fate \u2014 addressed (and how), deferred (and why), or still open\n- openQuestions: [optional] remaining uncertainties\n- followUps: genuine next-question leads; omit the section if there are none\n\nIf record mode was ON, also include `rounds: [{round, mode, body}, ...]` on that final call with the bodies you remembered per round.\n\nFINAL VISIBLE OUTPUT:\nWhen you present the completed answer to the user, begin your visible output with the header \"## RVRY | Reflection\" followed by the round-1 observation prose you remembered (without the machine-readable commitment lines), then present the answer. The reflection is part of the product \u2014 the user sees the observation that shaped the answer first, then the answer itself.\n\nDO NOT display: the prompt text you received (the round-1 observation prose IS shown in full \u2014 at observation time and again in the final output), the FORWARD/FORBIDDEN/QUESTION commitment lines, constraint tables, quality scores, internal tracking data, or round numbers to the user.";
+declare const SLASH_COMMANDS: CodexSkillSource[];
 /**
  * Install RVRY slash commands into the given directory.
  * Only called when Claude Code is the selected client.
@@ -35,5 +51,6 @@ declare const SLASH_COMMANDS: {
  *   touch the real directory.
  */
 declare function installSlashCommands(commandsDir: string): string[];
-export { SLASH_COMMANDS, installSlashCommands, THINK_SHIM_CONTENT, RVRY_SHIM_CONTENT, THINK_MODEL_SHIM_CONTENT };
+export { CLIENT_REGISTRY, SLASH_COMMANDS, installSlashCommands, THINK_SHIM_CONTENT, RVRY_SHIM_CONTENT, THINK_MODEL_SHIM_CONTENT, };
 export declare function runSetup(): Promise<void>;
+export { isSupportedClientId, selectDetectedClientIndices };

package/dist/setup.js

@@ -2,12 +2,14 @@
  * @rvry/mcp setup wizard
  *
  * Interactive setup: device auth flow (browser-based) or manual token paste.
- * Auto-detects Claude Code CLI and Claude Desktop, configures both.
+ * Auto-detects Claude Code, Claude Desktop, and Codex, then configures the
+ * selected clients without touching unrelated client state.
  *
  * Usage: npx --yes --package @rvry/mcp@latest rvry-mcp setup
  *        npx --yes --package @rvry/mcp@latest rvry-mcp setup --token <value>
  *        npx --yes --package @rvry/mcp@latest rvry-mcp setup --client code      (Claude Code only)
  *        npx --yes --package @rvry/mcp@latest rvry-mcp setup --client desktop    (Claude Desktop only)
+ *        npx --yes --package @rvry/mcp@latest rvry-mcp setup --client codex      (Codex only)
  */
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
@@ -17,6 +19,7 @@ import { execSync } from 'child_process';
 import { platform } from 'os';
 import { createRequire } from 'module';
 import { fetch } from './fetch.js';
+import { configureCodexMcp, installCodexSkills, isCodexCliAvailable, } from './codex-adapter.js';
 const require = createRequire(import.meta.url);
 const PKG_VERSION = require('../package.json').version;
 const ENGINE_URL = 'https://engine.rvry.ai';
@@ -234,7 +237,21 @@ const CLIENT_REGISTRY = [
         configure: (token) => configureDesktop(token),
         notInstalledHint: 'Not installed',
     },
+    {
+        name: 'Codex',
+        id: 'codex',
+        detect: isCodexCliAvailable,
+        configure: configureCodexMcp,
+        notInstalledHint: 'CLI not found (https://developers.openai.com/codex/cli)',
+    },
 ];
+function isSupportedClientId(value) {
+    return typeof value === 'string' && CLIENT_REGISTRY.some((client) => client.id === value);
+}
+/** Return every detected client index for an explicit --client selection. */
+function selectDetectedClientIndices(availability) {
+    return availability.flatMap((available, index) => available ? [index] : []);
+}
 /**
  * Interactive multi-select picker with arrow keys + space + enter.
  * Returns indices of selected items.
@@ -576,7 +593,7 @@ If record mode was ON, also include \`rounds: [{round, mode, body}, ...]\` on th
 STATUS BEHAVIOR:
 When status is "shimmer": This round is a visible product surface. Show your FULL self-observation to the user, beginning with the header "## RVRY | Observation", then the line "rev·er·y /re·və·rē/ (n.) The state of being genuinely lost in deep, absorptive thought, as distinguished from the appearance of thinking.", then a "---" divider, then the observation prose. Do NOT show a brief status line. Machine-readable bookkeeping lines (FORWARD:/FORBIDDEN:/QUESTION:) belong only in the tool-call input, never in the visible display. REMEMBER this text verbatim for the final harvest.shimmer.
 When status is "orient": Orient on the ${subject}. Show the user "${orientLine}"
-When status is "complete": ${completionGuidance}${finalReflection ? ' Then end your visible output with the header "## RVRY | Reflection" followed by the observation prose you remembered (without any machine-readable commitment lines) — the reflection is part of the product and is shown in full. Skip this section only if the session had no observation round.' : ''}
+When status is "complete": ${finalReflection ? 'Begin your visible output with the header "## RVRY | Reflection" followed by the observation prose you remembered (without any machine-readable commitment lines) — the reflection is part of the product and is shown in full, and it leads: reflection first, answer after. Skip the reflection only if the session had no observation round. After the reflection: ' : ''}${completionGuidance}
 
 DO NOT display: the prompt text you received, constraint tables, quality scores, internal tracking data, or round numbers to the user.`;
 }
@@ -627,11 +644,12 @@ const RVRY_MODEL_IDS_LINE = 'five-whys, trade-off-matrix, rubber-duck, pre-morte
     'opportunity-cost, time-horizon-shifting, reversibility, inversion, second-order-effects, ' +
     'red-team, impact-effort-grid';
 const RVRY_MODEL_SELECTION = `MODEL SELECTION (BEFORE the first tool call):
-1. The FIRST whitespace-separated token of $ARGUMENTS (after removing --record) is the mental model name. Everything after it is the problem.
-2. Valid models: ${RVRY_MODEL_IDS_LINE}.
-3. Map close variants to the canonical id: "5-whys"/"five whys" -> five-whys; "premortem" -> pre-mortem; "steelman"/"steel-man" -> steelmanning; "tradeoff-matrix"/"trade-offs" -> trade-off-matrix; "first principles" -> first-principles; "redteam"/"red team" -> red-team; "impact-effort"/"impact effort" -> impact-effort-grid; "second order"/"second-order" -> second-order-effects; "fermi" -> fermi-estimation; "rubber duck"/"rubberduck" -> rubber-duck; "abstraction ladder" -> abstraction-laddering; "opportunity cost" -> opportunity-cost; "time horizon"/"time-horizons" -> time-horizon-shifting; "invert" -> inversion; "decompose" -> decomposition; "assumptions" -> assumption-surfacing; "relax constraints" -> constraint-relaxation; "reversible"/"one-way door" -> reversibility.
-4. If the first token does not match any model even loosely, ASK THE USER which model to use (list the valid ids) before making any tool call.
-5. On the FIRST tool call only, pass modelName: <canonical id>. Do NOT pass modelName on continuation calls.`;
+1. Remove the literal --record flag, trim the remaining input, then match the LONGEST leading canonical id or known alias prefix (case-insensitive). Prefer a multiword or hyphenated match over a shorter first-token match. The matched prefix is the mental model name; everything after that matched prefix is the problem.
+2. Examples: "five whys why do deploys fail?" selects five-whys with problem "why do deploys fail?"; "first principles redesign auth" selects first-principles; "red team the rollout plan" selects red-team; "rubber duck this race condition" selects rubber-duck.
+3. Valid models: ${RVRY_MODEL_IDS_LINE}.
+4. Map close variants to the canonical id: "5-whys"/"five whys" -> five-whys; "premortem" -> pre-mortem; "steelman"/"steel-man" -> steelmanning; "tradeoff-matrix"/"trade-offs" -> trade-off-matrix; "first principles" -> first-principles; "redteam"/"red team" -> red-team; "impact-effort"/"impact effort" -> impact-effort-grid; "second order"/"second-order" -> second-order-effects; "fermi" -> fermi-estimation; "rubber duck"/"rubberduck" -> rubber-duck; "abstraction ladder" -> abstraction-laddering; "opportunity cost" -> opportunity-cost; "time horizon"/"time-horizons" -> time-horizon-shifting; "invert" -> inversion; "decompose" -> decomposition; "assumptions" -> assumption-surfacing; "relax constraints" -> constraint-relaxation; "reversible"/"one-way door" -> reversibility.
+5. If no leading canonical id or alias prefix matches, ASK THE USER which model to use (list the valid ids) before making any tool call.
+6. On the FIRST tool call only, pass modelName: <canonical id>. Do NOT pass modelName on continuation calls.`;
 /** The /think-model shim: one named mental model per session. */
 const THINK_MODEL_SHIM_CONTENT = buildShim({
     toolName: 'think_model',
@@ -685,7 +703,7 @@ When you make the call that completes the session, also construct a \`harvest\`
 If record mode was ON, also include \`rounds: [{round, mode, body}, ...]\` on that final call with the bodies you remembered per round.
 
 FINAL VISIBLE OUTPUT:
-When you present the completed answer to the user, end your visible output with the header "## RVRY | Reflection" followed by the round-1 observation prose you remembered (without the machine-readable commitment lines). The reflection is part of the product — the user sees the answer AND the observation that shaped it.
+When you present the completed answer to the user, begin your visible output with the header "## RVRY | Reflection" followed by the round-1 observation prose you remembered (without the machine-readable commitment lines), then present the answer. The reflection is part of the product — the user sees the observation that shaped the answer first, then the answer itself.
 
 DO NOT display: the prompt text you received (the round-1 observation prose IS shown in full — at observation time and again in the final output), the FORWARD/FORBIDDEN/QUESTION commitment lines, constraint tables, quality scores, internal tracking data, or round numbers to the user.`;
 const SLASH_COMMANDS = [
@@ -824,7 +842,7 @@ function installSlashCommands(commandsDir) {
     return installed;
 }
 // Exported for tests (content + install behavior).
-export { SLASH_COMMANDS, installSlashCommands, THINK_SHIM_CONTENT, RVRY_SHIM_CONTENT, THINK_MODEL_SHIM_CONTENT };
+export { CLIENT_REGISTRY, SLASH_COMMANDS, installSlashCommands, THINK_SHIM_CONTENT, RVRY_SHIM_CONTENT, THINK_MODEL_SHIM_CONTENT, };
 // ── Main setup flow ────────────────────────────────────────────────
 const BANNER = `
 8888888b.  888     888 8888888b. Y88b   d88P
@@ -843,8 +861,14 @@ export async function runSetup() {
     // Parse flags
     const tokenFlagIndex = process.argv.indexOf('--token');
     const clientFlagIndex = process.argv.indexOf('--client');
-    const clientFilter = clientFlagIndex !== -1 ? process.argv[clientFlagIndex + 1] : null;
+    const clientFilterValue = clientFlagIndex !== -1 ? process.argv[clientFlagIndex + 1] : null;
     const acceptTerms = process.argv.includes('--accept-terms');
+    if (clientFlagIndex !== -1 && !isSupportedClientId(clientFilterValue)) {
+        console.error(`Invalid --client value. Expected one of: ${CLIENT_REGISTRY.map((client) => client.id).join(', ')}.`);
+        process.exitCode = 1;
+        return;
+    }
+    const clientFilter = clientFilterValue;
     // ── Step 1: Terms of Service ────────────────────────────────────
     console.log('[1/5] Terms of Service');
     console.log('');
@@ -938,7 +962,12 @@ export async function runSetup() {
     console.log('');
     // ── Step 3: Configure clients ───────────────────────────────────
     console.log('[4/5] Select apps to add RVRY MCP configuration');
-    console.log('  Use \x1b[1m↑↓\x1b[0m to navigate, \x1b[1mspace\x1b[0m to toggle, \x1b[1ma\x1b[0m to toggle all, \x1b[1menter\x1b[0m to confirm');
+    if (clientFilter) {
+        console.log(`  Using explicit --client ${clientFilter} selection`);
+    }
+    else {
+        console.log('  Use \x1b[1m↑↓\x1b[0m to navigate, \x1b[1mspace\x1b[0m to toggle, \x1b[1ma\x1b[0m to toggle all, \x1b[1menter\x1b[0m to confirm');
+    }
     console.log('');
     const pickerItems = detected.map((d) => ({
         label: d.client.name,
@@ -946,16 +975,21 @@ export async function runSetup() {
         available: d.available,
         hint: d.available ? undefined : d.client.notInstalledHint,
     }));
-    const selectedIndices = await multiSelect(pickerItems);
+    // An explicit --client already expresses the user's selection. Skip the
+    // interactive picker so --token + --accept-terms can run unattended.
+    const selectedIndices = clientFilter
+        ? selectDetectedClientIndices(detected.map((item) => item.available))
+        : await multiSelect(pickerItems);
     const configuredClients = [];
     let anyConfigured = false;
+    let clientConfigurationFailed = false;
     console.log('');
     for (const idx of selectedIndices) {
         const { client } = detected[idx];
         const result = client.configure(token);
         const statusMap = {
             ok: 'Configured',
-            updated: 'Updated token',
+            updated: 'Updated configuration',
             unchanged: 'Already configured',
             error: 'Failed',
         };
@@ -963,8 +997,15 @@ export async function runSetup() {
         const icon = result === 'error' ? '✗' : '✓';
         console.log(`  ${icon} ${client.name}: ${status}`);
         configuredClients.push({ name: client.name, status });
-        if (result !== 'error')
+        if (result === 'error') {
+            clientConfigurationFailed = true;
+        }
+        else {
             anyConfigured = true;
+        }
+    }
+    if ((clientFilter && selectedIndices.length === 0) || clientConfigurationFailed) {
+        process.exitCode = 1;
     }
     // Install slash commands if Claude Code was configured
     const claudeCodeConfigured = selectedIndices.some((idx) => detected[idx].client.id === "code") && configuredClients.some((c) => c.name === "Claude Code" && c.status !== "Failed");
@@ -980,6 +1021,36 @@ export async function runSetup() {
             }
         }
     }
+    // Install namespaced Codex skills if Codex was configured. Namespacing keeps
+    // RVRY from clobbering unrelated global skills such as `$deepthink`.
+    const codexConfigured = selectedIndices.some((idx) => detected[idx].client.id === 'codex') && configuredClients.some((c) => c.name === 'Codex' && c.status !== 'Failed');
+    let installedCodexSkills = [];
+    if (codexConfigured) {
+        console.log('');
+        console.log('  Installing Codex skills...');
+        installedCodexSkills = installCodexSkills(join(homedir(), '.agents', 'skills'), SLASH_COMMANDS);
+        if (installedCodexSkills.length > 0) {
+            console.log(`  Processed ${installedCodexSkills.length} skill(s):`);
+            for (const skill of installedCodexSkills) {
+                const verb = skill.status === 'unchanged'
+                    ? 'Ready'
+                    : skill.status === 'updated'
+                        ? 'Updated'
+                        : skill.status === 'error'
+                            ? 'Failed'
+                            : 'Installed';
+                const detail = skill.status === 'error' && skill.error ? ` — ${skill.error}` : '';
+                console.log(`    ${verb}: $${skill.name}${detail}`);
+            }
+        }
+    }
+    const codexSkillErrors = installedCodexSkills.filter((skill) => skill.status === 'error');
+    const codexSkillsReady = codexConfigured
+        && installedCodexSkills.length === SLASH_COMMANDS.length
+        && codexSkillErrors.length === 0;
+    if (codexConfigured && !codexSkillsReady) {
+        process.exitCode = 1;
+    }
     if (selectedIndices.length === 0) {
         console.log('  No clients selected.');
     }
@@ -989,10 +1060,13 @@ export async function runSetup() {
         console.log('  Manual configuration:');
         console.log('');
         console.log('  Option A — Claude Code (if you install it later):');
-        console.log(`    claude mcp add -e RVRY_TOKEN="${token}" -s user rvry -- npx --yes --package @rvry/mcp@latest rvry-mcp`);
+        console.log('    claude mcp add -e RVRY_TOKEN="rvry_your_token" -s user rvry -- npx --yes --package @rvry/mcp@latest rvry-mcp');
+        console.log('');
+        console.log('  Option B — Codex (if you install it later):');
+        console.log('    codex mcp add rvry --env RVRY_TOKEN="rvry_your_token" -- npx --yes --package @rvry/mcp@latest rvry-mcp');
         console.log('');
-        console.log('  Option B — Claude Desktop JSON config:');
-        const manualConfig = { mcpServers: { RVRY: RVRY_SERVER_ENTRY(token) } };
+        console.log('  Option C — Claude Desktop JSON config:');
+        const manualConfig = { mcpServers: { RVRY: RVRY_SERVER_ENTRY('rvry_your_token') } };
         console.log('');
         for (const line of JSON.stringify(manualConfig, null, 2).split('\n')) {
             console.log(`    ${line}`);
@@ -1006,7 +1080,8 @@ export async function runSetup() {
     // ── Summary ─────────────────────────────────────────────────────
     console.log('─'.repeat(50));
     console.log('');
-    console.log('RVRY Setup Complete');
+    const setupFailed = process.exitCode !== undefined && process.exitCode !== 0;
+    console.log(setupFailed ? 'RVRY Setup Incomplete' : 'RVRY Setup Complete');
     console.log('');
     console.log(`  Token:          ${maskToken(token)}${usage ? ` (${usage.tier})` : ''}`);
     for (const c of configuredClients) {
@@ -1018,12 +1093,23 @@ export async function runSetup() {
     const configuredNames = new Set(configuredClients.map((c) => c.name));
     const hasDesktopStyle = configuredNames.has('Claude Desktop / Claude Co-Work');
     const hasCodeStyle = configuredNames.has('Claude Code');
+    const hasCodexStyle = codexSkillsReady;
     console.log('Next steps:');
     let step = 1;
     if (hasDesktopStyle) {
         console.log(`  ${step}. Restart Claude Desktop for the new MCP server to load`);
         step++;
     }
+    if (hasCodexStyle) {
+        console.log(`  ${step}. Restart Codex or reload skills so the new adapter is discovered`);
+        step++;
+        console.log(`  ${step}. Try: $rvry-deepthink [your question]`);
+        step++;
+    }
+    if (codexConfigured && !codexSkillsReady) {
+        console.log(`  ${step}. Fix the Codex skill installation errors above, then rerun setup`);
+        step++;
+    }
     if (hasCodeStyle || hasDesktopStyle) {
         if (installedCommands.length > 0) {
             console.log(`  ${step}. Try a slash command: /deepthink [your question]`);
@@ -1038,3 +1124,4 @@ export async function runSetup() {
         console.log('  2. Then try: "Use deepthink to analyze..."');
     }
 }
+export { isSupportedClientId, selectDetectedClientIndices };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rvry/mcp",
-  "version": "1.3.0",
-  "description": "Reasoning depth enforcement for LLMs. Seven structured analysis tools and 18 mental-model templates for Claude Code, Claude Desktop, and any MCP client.",
+  "version": "1.4.0",
+  "description": "Reasoning depth enforcement for LLMs. Seven structured analysis tools and 18 mental-model templates for Claude Code, Claude Desktop, Codex, and any MCP client.",
   "homepage": "https://rvry.ai",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && chmod 755 dist/index.js",
-    "prepack": "npm run build",
+    "prepack": "bun run build",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -38,6 +38,8 @@
     "critical-thinking",
     "claude",
     "claude-code",
+    "codex",
+    "openai-codex",
     "llm",
     "ai"
   ],