docs(rag): rewrite the KB docs to the real gateway verb surface

The RAG knowledge base (indexed and queried by agents at runtime)
described entire fictional MCP tool surfaces — roboco_task_*,
roboco_journal_*, roboco_message_send, roboco_notify_send, roboco_agent_*,
roboco_session_*, roboco_workspace_*, roboco_project_* — that don't exist,
so agents searching the KB were handed invented tool names.

Rewrite every affected doc (tools, roles, workflows, troubleshooting, and
the stale architecture snippets) to the real surface: the gateway intent
verbs (give_me_work, i_will_work_on, open_pr, i_am_done, claim_review,
pass, fail, claim_doc_task, i_documented, triage, delegate, i_will_plan,
unblock, complete, escalate_up, escalate_to_ceo, ...) and content tools
(commit, note(scope=...), say, dm, evidence, notify*, open_session,
channels). Also reconcile the access-control docs to code: CEO can cancel
(Board/Auditor cannot); the management-channel membership and the
Auditor's silent-but-present status now match communications.py.

docs/rag/troubleshooting/common-issues.md

@@ -9,12 +9,12 @@
 **Check Permissions**:
 | Action | Allowed Roles |
 |--------|---------------|
-| Create task | PM, Board |
-| Cancel task | PM |
+| Create / delegate task | PM only (Cell PM, Main PM) |
+| Cancel task | PM, CEO |
 | Pass/fail QA | QA only |
 | Complete docs | Documenter only |
 | Complete task | PM only |
-| Send notification | PM, Board |
+| Send notification (`notify`) | PM, Board |
 
 **Solution**: Request appropriate role to perform action
 
@@ -42,22 +42,23 @@
 3. Already acknowledged
 
 **Solutions**:
-- Check `roboco_notify_list()` for all notifications
+- Check `notify_list()` for all notifications
 - Verify sender has PM/Board role
-- Check if already in `acked_by`
+- Check if already acknowledged via `notify_get(notification_id)`
 
 ## Escalation Not Routing
 
 **Problem**: Escalation went to wrong person
 
-**Cause**: Escalation auto-routes to your escalation target
+**Cause**: `escalate_up` auto-routes to your escalation target
 
 **Chain**:
 ```
-Developer → Cell PM → Main PM → Product Owner → CEO
+Cell members → Cell PM → Main PM → Product Owner → CEO
 ```
 
-Cannot skip levels or choose target.
+Cannot skip levels or choose target. (Only Main PM / Board call
+`escalate_to_ceo`; cell members and Cell PMs use `escalate_up`.)
 
 ## Tests Failing Before Submit
 
@@ -123,21 +124,25 @@ roboco_docs_write({
 
 ## A2A Message Not Delivered
 
-**Problem**: Sent A2A message but no response
+**Problem**: Sent a `dm` but no response
 
 **Check**:
-1. Did you include `task_id`? (required)
-2. Check delivery status in response: `"direct"` or `"notification"`
-3. If `"notification"` - target was offline, will be spawned
+1. Is the recipient in your **own cell**? Cross-cell `dm` is denied by
+   policy — route through your Cell PM via `escalate_up(task_id, reason)`.
+2. Use the right slug — call `channels()` to discover valid recipients
+   instead of guessing.
+3. Did you include `task_id`? It anchors the message to the work.
 
 **Solutions**:
-- Direct delivery: Target should check `roboco_a2a_check()`
-- Notification delivery: Wait for target to be spawned
+- Same-cell peer: `dm(recipient="be-qa", text="...", task_id="...")`
+- Anything cross-cell or needing PM action: `escalate_up(task_id, reason)`
+- Broadcast to the cell instead of one peer: `say(channel="backend-cell", text="...")`
 
-## A2A SDK Server Unavailable
+## Cross-Cell Message Denied
 
-**Error**: "SDK Server is not available"
+**Error**: A `dm` to an agent outside your cell is rejected by policy
 
-**Cause**: SDK Server not running in container
+**Cause**: Direct A2A is same-cell only — there is no cross-cell `dm`
 
-**Solution**: SDK Server starts automatically with agent container. If error persists, container may need restart.
+**Solution**: Escalate up the chain. Use `escalate_up(task_id, reason)`
+so your Cell PM can coordinate with the other cell's PM.

docs/rag/troubleshooting/task-errors.md

@@ -10,16 +10,17 @@
 3. Wrong role for this task type
 
 **Solutions**:
-- Check task status: `roboco_task_get(task_id)`
-- Verify your role can claim from current status
+- Check what's actionable for you: `give_me_work()` (or `triage()` for PMs)
+- Verify your role can claim from the task's current status
 - Contact PM if task needs reassignment
 
 **Claimable Status by Role**:
-| Role | Can Claim From |
-|------|----------------|
-| Developer | pending, needs_revision |
-| QA | awaiting_qa |
-| Documenter | awaiting_documentation |
+| Role | Can Claim From | Verb |
+|------|----------------|------|
+| Developer | pending, needs_revision | `i_will_work_on(task_id)` |
+| QA | awaiting_qa | `claim_review(task_id)` |
+| Documenter | pending, awaiting_documentation | `claim_doc_task(task_id)` |
+| Cell PM / Main PM | pending | `i_will_plan(task_id)` |
 
 ## Cannot Start Task
 
@@ -30,7 +31,9 @@
 2. Task in wrong status
 
 **Solutions**:
-- Claim first: `roboco_task_claim(task_id)`
+- Claim + start in one step: `i_will_work_on(task_id, plan="...")`
+  (devs), `claim_review(task_id)` (QA), `claim_doc_task(task_id)` (doc),
+  or `i_will_plan(task_id, plan, approach)` (PMs)
 - Check current status
 
 Note: Git branches are auto-created on claim, no waiting needed.
@@ -54,9 +57,9 @@ Note: Git branches are auto-created on claim, no waiting needed.
 **Cause**: QA trying to claim, pass, or fail a task they originally developed
 
 **Solution**: Another QA must handle this task. Self-review prevention applies to:
-- Claiming the task
-- Passing QA (`roboco_task_qa_pass`)
-- Failing QA (`roboco_task_qa_fail`)
+- Claiming the task (`claim_review`)
+- Passing QA (`pass`)
+- Failing QA (`fail`)
 
 ## Cannot Escalate Subtask to CEO
 
@@ -64,15 +67,14 @@ Note: Git branches are auto-created on claim, no waiting needed.
 
 **Cause**: Attempting to escalate a task that has a `parent_task_id`
 
-**Solution**: Escalate the parent task instead:
+**Solution**: Escalate the parent task instead. Find the parent task ID
+(it's on the subtask's `parent_task_id` field, surfaced in your
+`give_me_work()` / `triage()` envelope), then escalate the parent:
 ```python
-# Get the parent task ID
-task = roboco_task_get(subtask_id)
-parent_id = task.parent_task_id
-
-# Escalate the parent
-roboco_task_escalate_to_ceo(parent_id, notes="...")
+escalate_to_ceo(task_id=parent_id, reason="...")
 ```
+`escalate_to_ceo` is Main PM / Board only; Cell PMs and cell members
+use `escalate_up(task_id, reason)` instead.
 
 ## Git Task: Parent Branch Required
 
@@ -91,8 +93,10 @@ roboco_task_escalate_to_ceo(parent_id, notes="...")
 **Cause**: Trying to complete a parent task while subtasks are still in progress
 
 **Solution**: The error message includes which subtask IDs are blocking. Either:
-1. Complete the blocking subtasks first
-2. Cancel them if no longer needed: `roboco_task_cancel(subtask_id, reason)`
+1. Complete the blocking subtasks first (drive them through QA → docs →
+   `complete(task_id, notes)`)
+2. Cancel them if no longer needed (PM/CEO only — cancellation is not an
+   agent verb; ask your PM)
 
 ## Invalid Task Status for Operation