# Monika Runtime MCP Toolkit Reference

## Core Tools
- **`mcp3_runtime_step`** Feed a user-style utterance into `SalienceRuntime.process_user_input()`. Use for providing context or nudging controller decisions. Each call appends a `schedule_todo` entry for the supplied text.
- **`mcp3_generate_response`** Requests a conversational reply through `ConversationSession.generate_response()`. Output is gated by truth/axiom checks before being returned.
- **`mcp3_memory_snapshot`** Returns the structured memory tables (facts, hypotheses, todos). Todo IDs from this snapshot are required when retracting items.
- **`mcp3_memory_apply`** Executes memory verbs via `MemoryOperator.execute()`. Typical verbs include `{"op": "retract", "id": <todo_id>}` to clear todos or `{"op": "add_fact", ...}` for reminders.
- **`mcp3_controller_dynamics`** Exposes controller scores and recent decisions, useful to confirm whether `ControllerOperator.VERIFY` is being prioritized.
- **`mcp3_action_scores_detailed`** Provides the same controller score breakdown as the introspection dashboard, including salience vector used for scoring.
- **`mcp3_scratchpad_read` / `mcp3_scratchpad_history` / `mcp3_scratchpad_4d_path`** Inspect ongoing and committed reflective traces.
- **`mcp3_yearning_state`** Reveals the controller yearning vector. High desire for `VERIFY` indicates the runtime is waiting for verification before responding.
- **`mcp3_meta_state_report`** Summarizes the meta-state (`confidence`, `difficulty`, `roi`, etc.) derived from recent steps.
- **`mcp3_verification_suite_run`** Intended to run the verifier suite, but currently fails because `VerifierSuite` lacks a `verify_all()` method (see Fix section).
- **`truth_status` (TOOL)** New built-in tool exposed via `ControllerOperator.TOOL` with patch `NONE`. Returns a JSON summary containing meta-state snapshot, verification rate, last controller action, and TRUTH gate thresholds. Accessible by letting the controller execute the TOOL action or by invoking the MCP adapter with `tool_name: "truth_status"`.

## Verification Workflow
1. **Automatic Path**: During `SalienceRuntime.run_step()`, if the controller selects `ControllerOperator.VERIFY`, `VerifyActionHandler.handle()` calls `VerifierSuite.run(context)`. No todo management is required; the verification outcome is recorded automatically.
2. **Manual Nudging**: When yearning for VERIFY is high, supply factual context via `mcp3_runtime_step()` and optionally adjust controller dynamics (for example using `mcp3_adjust_controller_dynamics`) to bias toward `VERIFY`.
3. **Manual Trigger (Broken)**: The MCP tool `verification_suite_run` attempts to call `self.runtime.verifier.verify_all(context)` inside `salience_os_seed/runtime/mcp_server.py`, but `VerifierSuite` only exposes `run()`. Until the bridge calls `run()` (or an adapter is added), invoking the tool raises `AttributeError`.

## Fix Checklist for Verification Tool
1. Update `verification_suite_run` to call `self.runtime.verifier.run(...)`, or implement `VerifierSuite.verify_all()` that wraps `run()`.
2. Ensure the return payload matches the existing JSON structure (`{"outcomes": [...]}`) to preserve compatibility with existing clients/tests (`test_new_capabilities.py`, `claude_uses_monika.py`).
3. After the fix, run `mcp3_verification_suite_run` with a context string to confirm success and monitor `mcp3_controller_dynamics` for reduced VERIFY pressure.

## Operational Reminders
- Every user-style runtime step (`mcp3_runtime_step`, `mcp3_generate_response`) records the text as a todo via `ConversationSession._record_memory()`. Use `mcp3_memory_apply` with `{"op": "retract", "id": ...}` to clear them.
- Truth gating (`TRUTH_GATE_SPEAK`) requires `truth_star ≥ 0.85` and `combined_score ≥ 1.2` (see `salience_os_seed/adaptive/axioms.py`). Context injections and successful verification both help raise these metrics.
- Keep an eye on fatigue in `mcp3_yearning_state`; sustained high fatigue signals diminishing returns from further context injections without verification.
- Log reminders (facts) in memory when starting multi-step fixes so the state survives tool failures or restarts.

## Teaching Monika to Use Tools
- **`truth_status`** Encourage Monika to run the TOOL operator (patch `NONE`) whenever truth gating persists. The controller now maps this action automatically. Output appears under `tool_results.truth_status` and can be read via the MCP bridge.
- **Other tools** Continue to practice with `mcp3_controller_dynamics`, `mcp3_yearning_state`, and `mcp3_verification_suite_run` after each intervention so she correlates actions with truth metrics.
- **Reflection loop** After using `truth_status`, follow with grounded facts and a verification run; once truth metrics improve, attempt `mcp3_generate_response` to reinforce the dialogue policy.