# RKA Usage Guide — Setting Up Claude Desktop + Claude Code as Brain & Executor (v2.3)

This guide walks PIs (researchers) through the full setup and research workflow, from a fresh laptop to producing research outputs with Brain (strategy) and Executor (implementation) actors.

> ### ⚠️ This guide requires the **Claude Desktop** native app — **NOT** the [claude.ai](https://claude.ai) website.
>
> RKA connects to Claude through MCP (Model Context Protocol), and **only the desktop and IDE apps support MCP servers** — the web app at claude.ai does not. You will need:
>
> | Actor | App | Role |
> |-------|-----|------|
> | **Brain** | [Claude Desktop](https://claude.ai/download) (macOS / Windows) | Strategy, synthesis, knowledge organization |
> | **Executor** | [Claude Code](https://www.anthropic.com/claude-code) (VS Code extension or CLI) | Implementation, experiments, coding |
> | **PI** | You, the human researcher | Supervises both, ratifies decisions |
>
> All three share one memory — RKA — so context survives across sessions.

---

## Table of Contents

- [Architecture at a glance](#architecture-at-a-glance)
- [Prerequisites](#prerequisites)
- [Setup — step by step](#setup--step-by-step)
  - [Step 1. Install Docker Desktop](#step-1-install-docker-desktop)
  - [Step 2. Clone and start RKA](#step-2-clone-and-start-rka)
  - [Step 3. Install the RKA MCP binary](#step-3-install-the-rka-mcp-binary)
  - [Step 4. Configure Claude Desktop (Brain)](#step-4-configure-claude-desktop-brain)
  - [Step 5. Configure Claude Code (Executor)](#step-5-configure-claude-code-executor)
  - [Step 6. Verify everything works](#step-6-verify-everything-works)
  - [Step 7. Load the Brain skill in Claude Desktop](#step-7-load-the-brain-skill-in-claude-desktop)
  - [Step 8. Load the Executor skill in Claude Code](#step-8-load-the-executor-skill-in-claude-code)
- [Starting Your First Session](#starting-your-first-session)
  - [What Happens at Session Start](#what-happens-at-session-start)
- [The Research Lifecycle](#the-research-lifecycle)
  - [Phase 1: Define Your Research](#phase-1-define-your-research)
  - [Phase 2: Collect Evidence](#phase-2-collect-evidence)
  - [Phase 3: Assign Work to the Executor](#phase-3-assign-work-to-the-executor)
  - [Phase 4: Review and Synthesize](#phase-4-review-and-synthesize)
  - [Phase 5: Produce Research Outputs](#phase-5-produce-research-outputs)
- [Working With Claude Code (Executor)](#working-with-claude-code-executor)
  - [How the Executor Picks Up Missions](#how-the-executor-picks-up-missions)
  - [The Backbrief](#the-backbrief)
  - [Checkpoints and Escalation](#checkpoints-and-escalation)
  - [Mission Reports](#mission-reports)
- [Validation Gates](#validation-gates)
- [Knowledge Freshness](#knowledge-freshness)
- [Using the Web Dashboard](#using-the-web-dashboard)
- [Multi-Project Workflows](#multi-project-workflows)
- [Knowledge Pack Export and Import](#knowledge-pack-export-and-import)
- [Tips and Best Practices](#tips-and-best-practices)
- [Troubleshooting](#troubleshooting)

---

## Architecture at a glance

```
┌─────────────────────┐      ┌─────────────────────┐
│  Claude Desktop     │      │  Claude Code        │
│  (Brain)            │      │  (Executor)         │
└─────────┬───────────┘      └─────────┬───────────┘
          │ MCP stdio                   │ MCP stdio
          ▼                             ▼
   ┌──────────────────────────────────────────┐
   │  rka MCP binary (~/.local/bin/rka)       │   ← installed via uv
   │  Thin proxy: forwards calls over HTTP    │
   └──────────────────┬───────────────────────┘
                      │ HTTP (localhost:9712)
                      ▼
   ┌──────────────────────────────────────────┐
   │  Docker containers                       │
   │  ├─ rka-server  (FastAPI + web UI)       │   ← `docker compose up -d`
   │  ├─ rka-worker  (background embeddings)  │
   │  └─ SQLite database (persistent volume)  │
   └──────────────────────────────────────────┘
```

You install the Docker stack once, then point both Claude apps at the MCP binary. Switching between Brain and Executor is just switching apps — both read and write the same shared memory.

---

## Prerequisites

Install these before running through Setup. Click the links to download.

| # | Component | Why you need it | Where to get it |
|---|-----------|-----------------|-----------------|
| 1 | **Docker Desktop** | Runs RKA's API + database in containers | [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) |
| 2 | **uv** (Python package manager) | Installs the RKA MCP binary outside Docker | [docs.astral.sh/uv/getting-started/installation](https://docs.astral.sh/uv/getting-started/installation/) |
| 3 | **git** | Clones the RKA repo | Built into macOS / [git-scm.com/downloads](https://git-scm.com/downloads) |
| 4 | **Claude Desktop** (the **native app**, not [claude.ai](https://claude.ai) web) | Hosts the Brain | [claude.ai/download](https://claude.ai/download) |
| 5 | **Claude Code** (VS Code extension or CLI) | Hosts the Executor | [anthropic.com/claude-code](https://www.anthropic.com/claude-code) |

> **Why two Claude apps?** Brain and Executor are different roles, run in different sessions, with different skills loaded. Mixing them — using one Claude conversation to "do everything" — collapses the role separation that RKA's architecture is designed around.

---

## Setup — step by step

### Step 1. Install Docker Desktop

1. Download from [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) (macOS / Windows / Linux)
2. Install and launch the app. Wait until the whale icon in the menu bar / system tray says **"Docker Desktop is running"**.
3. Verify on the command line:

   ```bash
   docker --version
   docker compose version
   ```

Both should print version numbers without errors.

### Step 2. Clone and start RKA

```bash
git clone https://github.com/infinitywings/rka.git
cd rka
docker compose up -d
```

The first run will pull base images and build the web UI — expect 3–5 minutes. Subsequent starts are seconds.

Verify:

```bash
docker compose ps
# Should show rka-server (healthy) and rka-worker running
```

Open [http://localhost:9712](http://localhost:9712) in your browser — you should see the RKA web dashboard.

> **Tip — keep this terminal handy.** When you bump RKA later, you'll come back here and run `git pull && docker compose up -d --build`.

### Step 3. Install the RKA MCP binary

Claude Desktop and Claude Code reach RKA through a small command-line binary that runs outside Docker. It's a thin proxy that forwards MCP tool calls to the container's REST API.

From the **same `rka/` directory** as Step 2:

```bash
UV_CACHE_DIR=/tmp/uv-cache uv tool install --force .
```

This installs `rka` at `~/.local/bin/rka`. Verify:

```bash
~/.local/bin/rka --version
```

If `~/.local/bin` is not on your `PATH`, either add it (e.g. in `~/.zshrc`: `export PATH="$HOME/.local/bin:$PATH"`) or always reference the full path in the configs below.

> **After upgrading RKA** (`git pull`), re-run this command **and** `docker compose up -d --build` to refresh both halves.

### Step 4. Configure Claude Desktop (Brain)

1. Open **Claude Desktop**.
2. Go to **Settings → Developer → Edit Config**, or open the file directly:
   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux:** `~/.config/Claude/claude_desktop_config.json`
3. Add (or merge into) the following. **Replace `<your-username>` with your actual username** — the path must be absolute, not `~`. Set `RKA_PROJECT` to your primary project's id so every fresh session starts in that project (see "Pin your default project" below):

   ```json
   {
     "mcpServers": {
       "rka": {
         "command": "/Users/<your-username>/.local/bin/rka",
         "args": ["mcp"],
         "env": {
           "RKA_PROJECT": "prj_01ABC..."
         }
       }
     }
   }
   ```

   On Windows the command is something like `C:\\Users\\<your-username>\\.local\\bin\\rka.exe`.
4. Save the file and **fully quit Claude Desktop** (Cmd+Q on macOS / right-click tray icon → Quit on Windows), then reopen it. A reload alone is not always enough.

You should now see RKA tools available in any new conversation.

**Pin your default project (highly recommended).** With `RKA_PROJECT=<project_id>` set in the MCP `env` block above, both the MCP `_session.project_id` AND the API-side fallback resolve to that project on every fresh session. Without it, MCP subprocesses default to `proj_default`, and writes silently land there if Brain or Executor doesn't call `rka_set_project()` first. To find your project id: open `http://localhost:9712`, switch to the project you want, and copy the id from the URL — or run `rka_list_projects()` once in a Claude session.

### Step 5. Configure Claude Code (Executor)

Claude Code uses the same MCP binary. There are two common ways to register it:

**Option A — VS Code extension (graphical):** Open VS Code → Claude Code panel → click the gear → **MCP Servers** → **Add Server**. Use the same JSON shape as Step 4 (including the `env.RKA_PROJECT` field).

**Option B — Per-project config file (recommended for teams):** Create `.claude/mcp.json` in your repo root with:

```json
{
  "mcpServers": {
    "rka": {
      "command": "/Users/<your-username>/.local/bin/rka",
      "args": ["mcp"],
      "env": {
        "RKA_PROJECT": "prj_01ABC..."
      }
    }
  }
}
```

After saving, reload the VS Code window: **Cmd+Shift+P** (macOS) / **Ctrl+Shift+P** (Windows/Linux) → **"Developer: Reload Window"**.

If you're using the Claude Code CLI instead of the extension, the equivalent config lives in `~/.claude/settings.json` under the same `mcpServers` key.

### Step 6. Verify everything works

**In Claude Desktop** (Brain), start a **new conversation** and ask:

> List my RKA projects.

Claude should call `rka_list_projects()` and return a list (an empty list is fine on a fresh install).

**In Claude Code** (Executor), open any project and ask:

> Check the RKA status.

Claude should call `rka_get_status()` and return the current project state.

If either fails:
- ✓ Is Docker running? `docker compose ps` should show `rka-server (healthy)`.
- ✓ Is the binary installed? `~/.local/bin/rka mcp` should hang waiting for stdin — Ctrl+C to exit.
- ✓ Did you fully quit-and-reopen Claude Desktop, or reload the VS Code window?
- ✓ Is the path in the JSON config absolute (not `~/.local/bin/rka`)?

### Step 7. Load the Brain skill in Claude Desktop

The MCP server ships **role skills** as MCP prompts: `brain_skill`, `executor_skill`, and `pi_skill`. These are detailed workflow guides (~450 lines for the Brain) that teach Claude the session-start protocol, PI-attribution discipline, provenance rules, and anti-patterns.

In Claude Desktop, the simplest way is to type:

> Load your brain skill.

Claude will call the `brain_skill` MCP prompt and adopt that workflow for the rest of the conversation.

You can also invoke it explicitly: type `/` in the chat input → select **rka → brain_skill** from the prompt menu (Claude Desktop surfaces all `@mcp.prompt()` entries from connected servers there).

The Brain skill covers:
- Session start protocol (the exact tool-call sequence on every new conversation)
- PI attribution discipline (`source="pi"`, `verbatim_input="..."` — preserving your exact words)
- Provenance discipline (linking decisions ↔ journal ↔ missions ↔ literature)
- Claim extraction best practices
- Multi-task parsing (splitting compound instructions into separate missions)
- Coordinating with the Executor
- Research Map navigation
- Anti-patterns to avoid

> **Repeat at the start of every Brain conversation.** MCP prompts don't auto-load; loading the skill once at the top of a chat is the standard pattern.

### Step 8. Load the Executor skill in Claude Code

In Claude Code, ask:

> Load your executor skill.

Claude will call the `executor_skill` MCP prompt. The Executor skill covers:
- How to pick up a mission (`rka_get_mission` → read `motivated_by_decision` → load context)
- The **Backbrief** protocol (presenting your plan before starting)
- When to raise a checkpoint vs. proceed autonomously
- Mission-report format (summary / findings / anomalies / questions)
- Scope discipline (no out-of-scope changes; raise a checkpoint instead)

> **Tip — pin a project-level CLAUDE.md.** For repos where the Executor will work often, run `rka_generate_claude_md()` from the Brain. It auto-writes a project-specific CLAUDE.md that Claude Code reads on every session, so the Executor starts with the right context even before the skill is loaded.

---

## Starting Your First Session

### What Happens at Session Start

When you start a conversation with the Brain, it should automatically:

1. **Check what changed** — `rka_get_changelog(since="yesterday")` shows new entries, decisions, claims, and missions since your last session
2. **Load the research map** — `rka_get_research_map()` shows your research questions, evidence clusters, and claim counts
3. **Process maintenance** — `rka_get_pending_maintenance()` detects provenance gaps. The Brain silently fixes up to 10 items (adding missing links, tags, or claim extractions)
4. **Greet you** with a summary of where things stand

You don't need to tell Claude to do this — the skill guide instructs it to.

---

## The Research Lifecycle

### Phase 1: Define Your Research

**You (PI) tell the Brain your research direction:**

> "I want to study whether horizontal sharding can solve MQTT broker scalability problems under high device density."

**What the Brain does:**

1. **Confirmation Brief** — The Brain restates your intent to verify understanding:

   > *"Let me make sure I understand: you want to identify the device density threshold where MQTT brokers degrade, and then test whether horizontal sharding mitigates the problem. Assumptions: lab environment, QoS 1, single-broker baseline. Does this match your intent?"*

2. After you confirm, the Brain **records your direction** with proper attribution:

   ```
   rka_add_note(
     content="Brain analysis: PI directed study of MQTT broker scalability...",
     source="pi",
     verbatim_input="I want to study whether horizontal sharding can solve MQTT broker scalability problems under high device density.",
     type="directive",
     tags=["research-protocol", "gate-0"]
   )
   ```

   Your exact words are preserved in `verbatim_input`. The Brain's interpretation goes in `content`. These are kept separate so your intellectual contribution is always traceable.

3. The Brain **creates research questions** as decision nodes:

   ```
   rka_add_decision(
     question="At what device density does MQTT broker performance degrade beyond 5% packet loss?",
     kind="research_question",
     decided_by="pi",
     assumptions=["Network latency negligible in lab", "Devices publish at 1 msg/sec"]
   )
   ```

### Phase 2: Collect Evidence

**Adding literature:**

> "I found a paper by Smith and Lee (2024) on MQTT broker stress testing. They report 12% packet loss above 400 devices."

The Brain records the paper and processes your reading annotations:

```
rka_add_literature(title="MQTT Broker Performance Under Stress", authors=["Smith, J.", "Lee, K."], year=2024)

rka_process_paper(
  lit_id="lit_01...",
  summary="Benchmarks MQTT brokers at scale. Key finding: 12% packet loss above 400 devices.",
  annotations=[
    {passage: "Table 3: 12% packet loss at 400 devices", note: "Threshold lower than expected",
     claim_type: "evidence", confidence: 0.85, cluster_id: "ecl_01..."}
  ]
)
```

`rka_process_paper` does three things in one call:
- Creates a journal entry with your reading notes
- Extracts structured claims from each annotation
- Assigns claims to evidence clusters

**The Brain creates evidence clusters** to organize related claims:

```
rka_create_cluster(label="Broker Performance Thresholds", research_question_id="dec_01...")
```

As you discuss more papers and findings, the Brain extracts claims and assigns them to clusters. The Research Map grows organically.

### Phase 3: Assign Work to the Executor

When there's implementation work to do (experiments, code, data collection), the Brain creates a **mission** for the Executor:

> "We need to run our own stress test to verify Smith & Lee's numbers."

The Brain creates a mission with a structured handoff:

```
rka_create_mission(
  objective="Run stress test to verify packet loss measurements at 400 devices",
  tasks=[
    {"description": "Replicate Smith & Lee setup (Mosquitto 2.0, 4-core, QoS 1)"},
    {"description": "Run 5 trials at 400 devices, compute mean and stddev"},
    {"description": "Compare results with published 12% figure"}
  ],
  context="INTENT: Verify published packet loss threshold...\nBACKGROUND: Smith & Lee report 12%...\nCONSTRAINTS: Do not modify broker config...\nASSUMPTIONS: 1. Network latency negligible...\nVERIFICATION: Mean packet loss with 95% CI",
  motivated_by_decision="dec_01..."
)
```

**To hand this to the Executor**: Open Claude Code and tell it:

> "Pick up mission mis_01... from RKA"

See [Working With Claude Code (Executor)](#working-with-claude-code-executor) for details.

### Phase 4: Review and Synthesize

After the Executor completes work and submits a report, the Brain:

1. **Reviews the report** — `rka_get_report(mission_id="mis_01...")`
2. **Checks for contradictions** — `rka_detect_contradictions(entity_id="clm_01...")`
3. **Flags stale evidence** — `rka_flag_stale(entity_id="clm_01...", reason="Contradicted by our experiment")`
4. **Writes cluster syntheses** — `rka_review_cluster(cluster_id="ecl_01...", synthesis="Our 5-trial experiment shows 8.2% mean packet loss...")`
5. **Advances research questions** — `rka_advance_rq(rq_id="dec_01...", status="partially_answered", conclusion="Threshold identified at ~400 devices")`

### Phase 5: Produce Research Outputs

When you need a draft for a paper section, literature review, or progress report:

> "Give me a progress report on the broker scalability question"

The Brain calls:

```
rka_assemble_evidence(research_question_id="dec_01...", format="progress_report")
```

This produces a structured markdown document pulling together:
- Key findings (top claims by confidence)
- Decisions made (with rationale)
- Current gaps
- Suggested next steps

Three formats are available:
- `progress_report` — findings + decisions + gaps + next steps
- `lit_review` — cluster-by-cluster with claims and cited papers
- `proposal_section` — framing + evidence + methodology + results

The output is a starting point — the Brain refines it before presenting to you.

---

## Working With Claude Code (Executor)

### How the Executor Picks Up Missions

In Claude Code, tell it to pick up a mission:

> "Pick up your RKA mission"

or if you have a specific mission ID:

> "Work on mission mis_01KP4DB5PZF7YXYRPV2AGQJSE6"

The Executor will:
1. Call `rka_get_mission()` to load the mission details
2. Read the `motivated_by_decision` to understand WHY the work exists
3. Read all context links (journal entries, decisions, literature)
4. Load the Executor skill for workflow guidance

### The Backbrief

Before starting significant work, the Executor presents a **Backbrief** — its plan for accomplishing the mission. This catches misalignment early:

> *"Before I start, here's my plan: I'll replicate the Smith & Lee setup in Docker, run 5 independent trials at 400 devices, and compute mean ± stddev. I interpret 'verify' to mean checking if our results fall within the published confidence interval..."*

The Executor records the Backbrief as a journal entry tagged `backbrief` and waits for the Brain to approve. You can review it in Claude Desktop:

> "The Executor submitted a backbrief for the stress test mission. Review it."

### Checkpoints and Escalation

During execution, the Executor raises **checkpoints** when it hits problems:

- **Assumption invalidation** — "The mission assumes network latency is negligible, but I measured 5ms"
- **Scope expansion** — "Fixing this requires changes outside the stated scope"
- **Contradictory results** — "Our measurements don't match the expected values"

Checkpoints appear in Claude Desktop via `rka_get_checkpoints(status="open")`. You and the Brain resolve them:

> "The Executor flagged that network latency isn't negligible. Tell it to re-run with simulated latency."

### Mission Reports

When the Executor finishes, it submits a report via `rka_submit_report()` with:
- **Summary**: What was done and what was found
- **Findings**: Key results
- **Anomalies**: Unexpected observations
- **Questions**: Open questions for the PI

The Brain reviews the report and either marks the mission complete or creates follow-up missions.

---

## Validation Gates

Gates are formal go/no-go checkpoints at critical transitions. They prevent compounding errors by forcing evaluation before proceeding.

### The 4 Gate Types

| Gate | When | Who Creates | Who Evaluates |
|------|------|-------------|---------------|
| **Gate 0: Problem Framing** | Before research starts | Brain | Brain + PI |
| **Gate 1: Plan Validation** | After mission created, before Executor starts | Brain | Brain (reviews Backbrief) |
| **Gate 2: Evidence Review** | After experiments/evidence gathering | Executor | Brain + PI |
| **Gate 3: Synthesis Validation** | Before committing conclusions | Brain | Brain + PI |

### Example: Using Gates

**You say**: "Create a gate before the Executor starts the stress test."

The Brain creates a Gate 1:

```
rka_create_gate(
  mission_id="mis_01...",
  gate_type="plan_validation",
  deliverables=["Executor Backbrief journal entry"],
  pass_criteria=["Plan addresses all tasks", "Assumptions are consistent"],
  assumptions_to_verify=["Network latency is negligible"]
)
```

After the Executor submits its Backbrief, the Brain evaluates:

```
rka_evaluate_gate(
  gate_id="chk_01...",
  verdict="go",
  notes="Plan is aligned. Proceed.",
  assumption_status={"Network latency is negligible": "validated"}
)
```

Verdicts:
- **Go** — proceed to the next phase
- **Kill** — abandon this direction
- **Hold** — wait for more information
- **Recycle** — revise and resubmit

If any assumption is marked `"invalidated"`, RKA automatically flags the related decision as stale and propagates through the knowledge graph.

### When to Use Gates

Not every task needs all 4 gates:
- **Quick bug fix**: Gate 1 only (Backbrief)
- **New research direction**: All 4 gates
- **Literature review**: Gate 0 (protocol) + Gate 3 (synthesis validation)
- **Experiment**: Gate 1 (plan) + Gate 2 (evidence review)

---

## Knowledge Freshness

RKA tracks whether evidence is still current. As new findings arrive, old claims may become stale.

### Staleness Levels

| Level | Meaning | Icon |
|-------|---------|------|
| Green | Fresh — no known issues | 🟢 |
| Yellow | Aging or partially conflicting | 🟡 |
| Red | Directly contradicted or invalidated | 🔴 |

### How Staleness Works

1. **Detection**: The Brain runs `rka_check_freshness()` to find aging claims, superseded sources, and clusters with stale evidence
2. **Flagging**: `rka_flag_stale(entity_id, reason, propagate=true)` marks a claim as stale
3. **Propagation**: When `propagate=true`, staleness cascades:
   - Stale claim → if >50% of claims in a cluster are stale → cluster flagged
   - Stale cluster → decisions citing it are flagged
4. **Resolution**: The Brain reviews stale items and either updates them with new evidence or confirms they're still valid

### Contradiction Detection

When new evidence conflicts with existing claims:

```
rka_detect_contradictions(entity_id="clm_01...")
```

Returns semantically similar claims that may conflict. The Brain reviews and decides:
- Are they genuinely contradictory?
- Should the old claim be flagged stale?
- Does this change any decisions?

---

## Using the Web Dashboard

The web dashboard at http://localhost:9712 provides a visual interface for browsing your research without using Claude.

### Key Pages

| Page | What You See |
|------|-------------|
| **Dashboard** | Project overview, recent entries, active missions, export/import controls |
| **Research Map** | Three-level drill-down: research questions → clusters → claims. Click a cluster to see full synthesis, all claims, and edit confidence |
| **Journal** | Timeline of all entries grouped by date, with type/confidence filters |
| **Decisions** | Interactive decision tree visualization |
| **Literature** | Table with reading pipeline status (to_read → reading → read) |
| **Missions** | Active and historical missions with task progress |
| **Knowledge Graph** | Entity relationship graph showing provenance links |
| **Notebook** | Ask questions grounded in your knowledge base (requires LLM) |
| **Settings** | LLM configuration, API health, database stats |

### Project Selection

Use the sidebar to switch between projects. The dashboard stores your active project locally and applies it to all API calls.

---

## Multi-Project Workflows

RKA supports multiple isolated research projects in the same database.

**Create a new project:**

> "Create a new RKA project called 'IoT Broker Scalability'"

**Switch between projects:**

> "Switch to the IoT Broker Scalability project"

All tool calls operate on the active project. **Brain and Executor must verify the active project at session start with `rka_get_status()`** — the MCP `_session.project_id` is per-process and ephemeral, so previous-session state is gone on every fresh subprocess. Without verification, writes silently land in `proj_default`. Set `RKA_PROJECT=<project_id>` in your MCP config (see Step 4) to make this default automatic.

---

## Knowledge Pack Export and Import

Knowledge packs are portable snapshots of a project — all data in a single `.rka-pack_v2.zip` file.

### Export

**From the web dashboard**: Dashboard → Export Pack

**From MCP**: `rka_export()` (or `GET /api/projects/export`)

The pack includes schema version metadata and table counts. The categorized table registry ensures no tables are silently dropped during export.

### Import

**From the web dashboard**: Dashboard → Import Pack → select the .zip file

**From REST API**:
```bash
curl -X POST http://localhost:9712/api/projects/import \
  -F "file=@my_project.rka-pack_v2.zip"
```

After import, RKA automatically runs an integrity check and reports any issues (orphaned edges, missing references, count mismatches).

### Before Upgrades

Before upgrading RKA to a new version:
1. Export all projects as knowledge packs
2. Run `rka_check_integrity()` to verify current state
3. Upgrade and rebuild Docker
4. Verify the migration ran cleanly
5. Run `rka_check_integrity()` again

---

## Tips and Best Practices

### For the PI

1. **Be specific when giving direction** — The Brain will create a Confirmation Brief to verify understanding. Correct any misalignment immediately — it's much cheaper to fix now than after implementation.

2. **Let the Brain handle recording** — Don't worry about which tool to use. Just tell the Brain what you're thinking. It handles the attribution (`source: "pi"`, `verbatim_input: "your exact words"`).

3. **Review the Research Map regularly** — Open http://localhost:9712/research-map or ask the Brain: "Show me the research map." It tells you at a glance which questions have strong evidence and which have gaps.

4. **Use the web dashboard for browsing** — It's faster than asking Claude for routine lookups. The Research Map page lets you click into clusters, see all claims, and even edit confidence and synthesis directly.

5. **Keep sessions focused** — Start each Brain session with context about what you want to accomplish. The Brain loads prior state automatically, but knowing your goal for *this session* helps it prioritize.

### For Working With the Brain

1. **Trust the session start protocol** — The Brain checks for changes, processes maintenance, and loads the research map before greeting you. This takes a few seconds but ensures it has full context.

2. **Give compound instructions naturally** — If you say "fix the search, update the docs, and check the import," the Brain should parse this into separate missions for the Executor rather than bundling everything together.

3. **Review gate evaluations** — When the Brain evaluates gates, it records assumption status. If assumptions are invalidated, staleness propagates automatically. Check these evaluations to stay informed.

### For Working With the Executor

1. **Let it backbrief** — When the Executor presents its plan, read it. Catching misalignment here saves hours.

2. **Don't skip missions** — Even for small tasks, creating a mission ensures the work is recorded with proper provenance (who asked for it, why, what was found).

3. **Check reports** — When the Executor submits a report, review it in Claude Desktop. The Brain can verify findings against the knowledge base.

---

## Troubleshooting

### "RKA tools not showing up in Claude Desktop"

1. Check the MCP config file path and JSON syntax (see [Step 4](#step-4-configure-claude-desktop-brain))
2. Make sure the `command` path is **absolute** — `~/.local/bin/rka` will fail; use `/Users/<your-username>/.local/bin/rka`
3. Fully quit Claude Desktop (Cmd+Q on macOS / right-click tray icon → Quit on Windows), then reopen — a window reload is not enough
4. Verify the binary works: `~/.local/bin/rka mcp` should hang waiting for stdin (Ctrl+C to exit)
5. Check Docker is running: `docker compose ps` should show `rka-server (healthy)`

### "RKA tools not showing up in Claude Code"

1. Check `.claude/mcp.json` (or VS Code's MCP settings) — same config shape as Claude Desktop
2. Reload the VS Code window: Cmd+Shift+P → "Developer: Reload Window"
3. If using the Claude Code CLI, edit `~/.claude/settings.json` instead

### "Brain skill not loading / Claude doesn't follow the workflow"

The skill is an MCP **prompt**, not a tool — it must be loaded explicitly at the top of each conversation. Type `/` in the chat input and look for the **rka → brain_skill** entry, or just ask: *"Load your brain skill."*

### "Tools return errors about connection refused"

The MCP binary proxies to `http://localhost:9712`. Make sure:
- Docker container is running and healthy
- Port 9712 is not blocked by firewall
- No other service is using port 9712

### "After code changes, tools behave the same as before"

The MCP binary caches aggressively. After any code changes:

```bash
uv tool uninstall rka
rm -rf /tmp/uv-cache
UV_CACHE_DIR=/tmp/uv-cache uv tool install --force --reinstall .
docker compose up -d --build
```

Then restart Claude Desktop and reload the VS Code window.

### "Knowledge pack export fails"

Run `rka_check_integrity()` to check for issues. Common causes:
- Tables missing from the registry (shows as explicit error naming the table)
- Orphaned edges (the integrity check reports these)

### "The web dashboard shows an old version number"

The version on the dashboard is read live from `/api/health`, which reflects the version baked into the running container — not the source code on disk. After `git pull`, rebuild the container:

```bash
docker compose up -d --build
```

If the build fails on macOS with errors about `._*` files (AppleDouble metadata on non-APFS volumes), run `dot_clean .` in the repo root and retry.

---

## Quick Reference Card

### Brain (Claude Desktop) — Key Commands

| You say... | Brain does... |
|------------|--------------|
| "Start a new research project about X" | Creates project, research protocol, initial RQs |
| "I found a paper by..." | Records literature, processes annotations, extracts claims |
| "We should focus on X" | Confirmation Brief → records directive with `verbatim_input` |
| "Create a mission for the Executor to..." | Creates mission with structured handoff |
| "Review the Executor's report" | Reads report, checks findings, marks mission complete |
| "Show me the research map" | Displays RQs → clusters → claims hierarchy |
| "What changed since yesterday?" | Runs `rka_get_changelog(since="yesterday")` |
| "Give me a progress report on RQ1" | Assembles evidence as structured markdown |
| "Check for stale evidence" | Runs freshness scan, flags outdated claims |

### Executor (Claude Code) — Key Commands

| You say... | Executor does... |
|------------|-----------------|
| "Pick up your mission" | Loads mission, reads context, presents Backbrief |
| "Check RKA status" | Shows project state, active missions, open checkpoints |
| "Submit your report" | Submits findings, anomalies, and recommendations |
| "Raise a checkpoint" | Creates blocking checkpoint for Brain/PI input |

### Web Dashboard — Key URLs

| URL | Page |
|-----|------|
| http://localhost:9712 | Dashboard (overview + export/import) |
| http://localhost:9712/research-map | Research Map (RQs → clusters → claims) |
| http://localhost:9712/journal | Journal entries timeline |
| http://localhost:9712/decisions | Decision tree visualization |
| http://localhost:9712/missions | Missions with task progress |
| http://localhost:9712/docs | API documentation (Swagger UI) |
