@rvry/mcp 1.2.0 → 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RVRY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,6 +4,8 @@
 
 RVRY is an MCP server that improves AI reliability by forcing your model to finish thinking before it answers. When your AI raises a question, RVRY remembers it. When it makes an assumption, RVRY flags it. When it tries to wrap up while those are still unaddressed, RVRY doesn't let it.
 
+Same model. Same question. Different answer.
+
 ## Quick Start
 
 ```bash
@@ -11,6 +13,7 @@ npx --yes --package @rvry/mcp@latest rvry-mcp setup
 ```
 
 The wizard will:
+
 1. Open your browser to sign in (or prompt for a token)
 2. Auto-detect supported clients on your machine
 3. Configure them automatically
@@ -21,7 +24,7 @@ Restart any running clients after setup, and RVRY is ready.
 
 ### Manual Configuration
 
-For Claude Desktop or any other MCP client that supports **stdio transport**, add this to your MCP config:
+For any MCP client that supports **stdio transport**, add this to your MCP config:
 
 ```json
 {
@@ -39,66 +42,87 @@ Get your token at [rvry.ai/dashboard](https://rvry.ai/dashboard) after signing u
 
 ## Tools
 
-| Tool | What it does | Tier |
+| Tool | What it does | Plan |
 |------|-------------|------|
-| **`think`** | Lighter single-session analysis for questions that need structure but not the full deepthink loop. | All |
-| **`deepthink`** | Extended multi-round analysis. Catches assumptions, tests them, and doesn't let your AI wrap up until it's dealt with what it found. | All |
-| **`rvry`** | Three-round reflective answering: a protected observation round surfaces commitments the answer must honor, then the answer is produced under them, then at most one resolution round. | All |
-| **`think_model`** | Applies one named mental model — 18 available — as a structured session. | All |
-| **`problem_solve`** | Structured decision-making. Forces orientation, anticipation, and evaluation before committing to a recommendation. | Pro+ |
-| **`challenge`** | Adversarial stress-testing. Finds weaknesses, tests assumptions, and surfaces failure modes in a proposal before you commit. | Pro+ |
+| **`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 |
 
-### Parameters
+## The 18 Mental Models
 
-All tools accept:
+`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.
 
-| 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>/<slug>/round-N-<mode>.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. |
+| | | |
+|---|---|---|
+| `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` |
 
-**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.
+```
+/think-model pre-mortem we're migrating the billing system to event sourcing next quarter
+```
 
-**SHIMMER display:** SHIMMER is always round 1. The model displays `RVRY SHIMMER` with the revery definition before its self-observation — this is the priming phase, where the model observes its own processing before structured analysis begins.
+A Five Whys session ends with a verified causal chain and a root-cause fix. A Pre-mortem ends with a failure catalog, early warnings, and a written kill condition. A Red Team session attacks your proposal as named adversaries would and disposes of every attack — mitigated, or accepted in writing.
 
-**Client-owned harvest (Path B):** On the call that completes the session, the client constructs and passes a `harvest` object describing the final synthesis; the local writer renders `.rvry/<op>/<slug>/harvest.md` from it. With `--record`, each round is also written as `round-N-<mode>.md` in that folder.
+**Choosing:** stuck on a bug → `rubber-duck`; recurring problem → `five-whys`; risky initiative → `pre-mortem`; already made up your mind → `steelmanning`; deciding how much rigor a decision deserves → `reversibility`; backlog to order → `impact-effort-grid`; every solution feels like a compromise → `constraint-relaxation`. Close variants of names resolve automatically (`premortem`, `steelman`, `5-whys`, …).
 
 ## Slash Commands (Claude Code)
 
-When you run `npx --yes --package @rvry/mcp@latest rvry-mcp setup` and select Claude Code, the wizard installs these slash commands:
+When you run setup and select Claude Code, the wizard installs these commands:
 
 | Command | Tool | What it does |
 |---------|------|-------------|
-| `/think` | think | Structured single-session analysis with a Difficulty Gate |
-| `/deepthink` | deepthink | Deep multi-round analysis |
-| `/rvry` | rvry | Reflective answering under surfaced commitments |
-| `/think-model` | think_model | Applies one named mental model (18 available) as a structured session |
-| `/problem-solve` | problem_solve | Structured decision-making |
-| `/challenge` | challenge | Adversarial stress-testing |
-| `/meta` | meta | Metacognitive observation |
+| `/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 MCP tool and includes rendering instructions so analysis appears as visible markdown rather than hidden in tool calls.
+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.
 
-**`--record` flag:** Append `--record` to any command (e.g. `/deepthink --record [question]`) to archive per-round bodies under `.rvry/<op>/<slug>/round-N-<mode>.md` alongside the harvest file.
+**`--record` flag:** Append `--record` to any command (e.g. `/deepthink --record [question]`) to archive per-round bodies under `.rvry/<op>/<timestamp>-<slug>/` alongside the harvest file.
 
 **Updating commands:** Re-running setup refreshes the RVRY-owned command files. Any pre-existing file is backed up to `<name>.md.bak` before it is overwritten.
 
 Commands are installed to `~/.claude/commands/`.
 
-## How it Works
+## Parameters
 
-Same model. Same question. Different answer.
+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. |
 
-Your AI already has the reasoning capacity. RVRY forces it to use that capacity by holding it accountable — when it raises a question, that question has to get answered. When it makes an assumption, that assumption has to get tested. It keeps working not because it was told to think harder, but because it hasn't finished what it started.
+`think_model` additionally requires `modelName` (one of the 18 model ids) on the first call.
 
-On hard questions, a smaller model with RVRY outperforms a bigger model without it. The bottleneck was never how smart the AI is. It was whether the AI finished thinking.
+**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.
+
+**Local session artifacts:** On the call that completes a session, the client persists the synthesis to `.rvry/<op>/<timestamp>-<slug>/harvest.md` in your project — every session leaves a durable artifact. With `--record`, each round's full body is archived alongside it. Add `.rvry/` to `.gitignore` if you don't want session artifacts in version control.
+
+## How It Works
+
+Your AI already has the reasoning capacity. RVRY forces it to use that capacity by holding it accountable — when it raises a question, that question has to get answered. When it makes an assumption, that assumption has to get tested. Throughout a session the engine tracks three kinds of obligation — things the analysis must still address, moves it must not make, and questions it can't silently drop — and a session cannot conclude while any of them are open.
+
+The model keeps working not because it was told to think harder, but because it hasn't finished what it started. On hard questions, a smaller model with RVRY outperforms a bigger model without it. The bottleneck was never how smart the AI is. It was whether the AI finished thinking.
 
 [Learn more →](https://rvry.ai/how-it-works)
 
@@ -106,8 +130,17 @@ On hard questions, a smaller model with RVRY outperforms a bigger model without
 
 | Plan | Sessions | Tools | Price |
 |------|----------|-------|-------|
-| Free | 5/month | deepthink, think | $0 |
-| Pro | 21/month | deepthink, think, problem_solve, challenge | $20/mo |
-| Max | Unlimited | All tools including meta | $99/mo |
+| 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)
+
+## License
+
+MIT — this package is the open client. The RVRY engine is a hosted service; a token from [rvry.ai](https://rvry.ai) is required.

package/dist/index.d.ts

@@ -19,13 +19,5 @@ declare const questionCache: Map<string, string>;
  */
 declare const TOOL_MAP: Record<string, RvryTool>;
 declare const TOOL_DEFS: Tool[];
-/**
- * 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 ONLY when the called tool
- * is rvry (R-6): legacy ops keep dropping prompt/instruction on their priming
- * round.
- */
 declare function stripResponse(result: ThinkResponse, question: string, toolName?: string): Record<string, unknown>;
 export { TOOL_MAP, TOOL_DEFS, stripResponse, questionCache };

package/dist/index.js

@@ -66,7 +66,7 @@ const TOOL_DEFS = [
     {
         name: 'deepthink',
         description: 'Deep, multi-round structured analysis for high-stakes or complex questions. ' +
-            'Runs 4 rounds of rigorous analysis with self-checks and adversarial stress-testing. ' +
+            'Runs 2-4 analytical rounds with self-checks and adversarial stress-testing. ' +
             'The first response orients you on the question — follow the instruction field to orient, then call again. ' +
             'Each subsequent round returns a prompt (work through it internally) and an instruction (follow it). ' +
             'Show the user only a brief status line per round (e.g. \'Round 3 — stress-testing the position\'). ' +
@@ -141,7 +141,7 @@ const TOOL_DEFS = [
     {
         name: 'problem_solve',
         description: 'Structured decision-making that forces thorough evaluation before commitment. ' +
-            'Runs 5 rounds through orient, anticipate, generate, evaluate, and commit phases. ' +
+            'Moves through orient, anticipate, generate, evaluate, and commit phases over 3-4 analytical rounds. ' +
             'The first response orients you — follow the instruction field, then call again. ' +
             'Each round returns a prompt and instruction. Work through the prompt internally. ' +
             'Show the user only a brief status line per round (e.g. \'Round 2 — mapping failure modes\'). ' +
@@ -327,7 +327,7 @@ const TOOL_DEFS = [
     {
         name: 'challenge',
         description: 'Adversarial analysis that stress-tests a proposal or idea before commitment. ' +
-            'Runs 5 rounds identifying weaknesses, testing assumptions, and surfacing failure modes. ' +
+            'Runs 3-4 analytical rounds identifying weaknesses, testing assumptions, and surfacing failure modes. ' +
             'The first response orients you — follow the instruction field, then call again. ' +
             'Each round returns a prompt and instruction. Work through the prompt internally. ' +
             'Show the user only a brief status line per round. Do not display internal data. ' +
@@ -673,10 +673,12 @@ 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 ONLY when the called tool
- * is rvry (R-6): legacy ops keep dropping prompt/instruction on their priming
- * round.
+ * 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.
  */
+const SHIMMER_VISIBLE_TOOLS = new Set(['rvry', 'deepthink', 'problem_solve']);
 function stripResponse(result, question, toolName) {
     const stripped = {
         sessionId: result.sessionId,
@@ -691,7 +693,7 @@ function stripResponse(result, question, toolName) {
         stripped.prompt = result.prompt;
         stripped.instruction = result.instruction;
     }
-    if (result.status === 'shimmer' && toolName === 'rvry') {
+    if (result.status === 'shimmer' && toolName !== undefined && SHIMMER_VISIBLE_TOOLS.has(toolName)) {
         stripped.prompt = result.prompt;
         stripped.instruction = result.instruction;
     }

package/dist/setup.d.ts

@@ -14,11 +14,13 @@ 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, beginning with \"**RVRY SHIMMER**\" and the revery definition, exactly as the instruction field describes. Do NOT show a brief status line.\n3. End your observation with the commitments that surfaced, one per line as FORWARD:/FORBIDDEN:/QUESTION: lines \u2014 or the single line NOTHING if none surfaced.\n4. REMEMBER your observation text verbatim \u2014 you will pass it as harvest.shimmer on the final call.\n5. Call the rvry tool again with your observation text 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\nDO NOT display: the prompt text you received (the round-1 observation you produce IS shown in full), constraint tables, quality scores, internal tracking data, or round numbers to the user.";
+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;
 }[];
 /**
  * Install RVRY slash commands into the given directory.

package/dist/setup.js

@@ -539,7 +539,7 @@ function ensureGitignore() {
  * defined sections to compose with the shared body.
  */
 function buildShim(opts) {
-    const { toolName, subject, orientLine, completionGuidance, shortSessionNote, perRoundPrelude, analyticalGuidance, prePerRoundBlock, finalCallExtras, } = opts;
+    const { toolName, subject, orientLine, completionGuidance, shortSessionNote, perRoundPrelude, analyticalGuidance, prePerRoundBlock, finalCallExtras, finalReflection, } = opts;
     return `Call the ${toolName} MCP tool with your ${subject} to start an analysis session.
 
 ${subject.charAt(0).toUpperCase() + subject.slice(1)}: $ARGUMENTS
@@ -574,9 +574,9 @@ If the pre-harvest self-check surfaced a concern, do not dismiss it in the same
 If record mode was ON, also include \`rounds: [{round, mode, body}, ...]\` on that final call with the bodies you remembered per round.
 
 STATUS BEHAVIOR:
-When status is "shimmer": Show your FULL self-observation to the user, beginning with "RVRY SHIMMER" and the revery definition. REMEMBER this text verbatim for the final harvest.shimmer.
+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}
+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.' : ''}
 
 DO NOT display: the prompt text you received, constraint tables, quality scores, internal tracking data, or round numbers to the user.`;
 }
@@ -660,10 +660,10 @@ ARGUMENT PARSING:
 
 ROUND 1 — OBSERVATION (status "shimmer"):
 1. The response's prompt field is your observation task. Work through it.
-2. Show the user your FULL observation, beginning with "**RVRY SHIMMER**" and the revery definition, exactly as the instruction field describes. Do NOT show a brief status line.
-3. End your observation with the commitments that surfaced, one per line as FORWARD:/FORBIDDEN:/QUESTION: lines — or the single line NOTHING if none surfaced.
-4. REMEMBER your observation text verbatim — you will pass it as harvest.shimmer on the final call.
-5. Call the rvry tool again with your observation text as input and the sessionId.
+2. 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.
+3. 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.
+4. REMEMBER your observation text verbatim — you will pass it as harvest.shimmer on the final call, and you will re-display its prose in the final output.
+5. Call the rvry tool again with your observation text (prose + commitment lines) as input and the sessionId.
 
 ROUNDS 2-3 — ANSWER AND RESOLUTION (status "active"):
 1. Read the prompt field — this is your task. DO NOT display it to the user.
@@ -684,7 +684,10 @@ 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.
 
-DO NOT display: the prompt text you received (the round-1 observation you produce IS shown in full), constraint tables, quality scores, internal tracking data, or round numbers to the user.`;
+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.
+
+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 = [
     {
         file: 'deepthink.md',
@@ -693,8 +696,11 @@ const SLASH_COMMANDS = [
             subject: 'question',
             orientLine: 'Orienting on the question.',
             completionGuidance: 'Present your final synthesis with key findings as bold headings. Lead with insights, not process.',
+            finalReflection: true,
         }),
         label: '/deepthink — deep analysis',
+        description: 'Deep multi-round analysis of a hard question',
+        argumentHint: '<question> [--record]',
     },
     {
         file: 'problem-solve.md',
@@ -705,23 +711,32 @@ const SLASH_COMMANDS = [
             completionGuidance: 'Present your final synthesis as a structured decision with key findings as bold headings. Lead with your recommendation, not process.',
             analyticalGuidance: PROBLEM_SOLVE_DECISION_TYPE,
             finalCallExtras: PROBLEM_SOLVE_FINAL_EXTRAS,
+            finalReflection: true,
         }),
         label: '/problem-solve — structured decision-making',
+        description: 'Structured decision-making on a problem, stress-tested before commitment',
+        argumentHint: '<problem> [--record]',
     },
     {
         file: 'think.md',
         content: THINK_SHIM_CONTENT,
         label: '/think — structured single-session analysis',
+        description: 'Quick structured analysis of a question (short session)',
+        argumentHint: '<question> [--record]',
     },
     {
         file: 'rvry.md',
         content: RVRY_SHIM_CONTENT,
         label: '/rvry — reflective answering',
+        description: 'Reflective answering — self-observation first, then the answer',
+        argumentHint: '<question> [--record]',
     },
     {
         file: 'think-model.md',
         content: THINK_MODEL_SHIM_CONTENT,
         label: '/think-model — apply one named mental model',
+        description: 'Apply one named mental model (five-whys, pre-mortem, inversion, ...) to a problem',
+        argumentHint: '<model> <problem> [--record]',
     },
     {
         file: 'challenge.md',
@@ -734,6 +749,8 @@ const SLASH_COMMANDS = [
             finalCallExtras: CHALLENGE_FINAL_EXTRAS,
         }),
         label: '/challenge — adversarial stress-testing',
+        description: 'Adversarial stress-test of a proposal with a GO / NO_GO verdict',
+        argumentHint: '<proposal> [--record] [--auto]',
     },
     {
         file: 'meta.md',
@@ -744,8 +761,16 @@ const SLASH_COMMANDS = [
             completionGuidance: 'Present your final metacognitive synthesis as a cohesive narrative reflection -- not a structured report. Lead with insights, not process.',
         }),
         label: '/meta — metacognitive observation (Max tier)',
+        description: 'Metacognitive observation on a topic (Max tier)',
+        argumentHint: '<topic> [--record]',
     },
 ];
+/** Frontmatter gives the command a human-readable description in the
+ * Claude Code picker; without it the picker falls back to the file's first
+ * line, which is a model instruction ("Call the think MCP tool ..."). */
+function withFrontmatter(cmd) {
+    return `---\ndescription: ${cmd.description}\nargument-hint: ${cmd.argumentHint}\n---\n\n${cmd.content}`;
+}
 /**
  * Install RVRY slash commands into the given directory.
  * Only called when Claude Code is the selected client.
@@ -770,7 +795,7 @@ function installSlashCommands(commandsDir) {
             if (existed) {
                 writeFileSync(`${filePath}.bak`, readFileSync(filePath, "utf-8"), "utf-8");
             }
-            writeFileSync(filePath, cmd.content + "\n", "utf-8");
+            writeFileSync(filePath, withFrontmatter(cmd) + "\n", "utf-8");
             console.log(existed
                 ? `  Updated ${cmd.file} (previous version backed up to ${cmd.file}.bak)`
                 : `  Installed ${cmd.file}`);

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@rvry/mcp",
-  "version": "1.2.0",
-  "description": "RVRY reasoning depth enforcement (RDE) engine client.",
+  "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.",
+  "homepage": "https://rvry.ai",
   "type": "module",
   "bin": {
     "rvry-mcp": "dist/index.js"
@@ -20,18 +21,25 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "latest"
+    "@modelcontextprotocol/sdk": "^1.27.1"
   },
   "devDependencies": {
-    "typescript": "latest",
-    "@types/node": "latest"
+    "typescript": "^5.9.3",
+    "@types/node": "^25.3.3"
   },
   "keywords": [
     "mcp",
+    "mcp-server",
+    "model-context-protocol",
     "rvry",
     "reasoning",
-    "rde",
-    "claude"
+    "structured-reasoning",
+    "mental-models",
+    "critical-thinking",
+    "claude",
+    "claude-code",
+    "llm",
+    "ai"
   ],
   "license": "MIT"
 }