Nereid MCP Collaboration

Collaborate on Mermaid-backed diagrams in a live, shared TUI/MCP session. Keep context small, edits structured, and attention explicit.

Collaboration Contract

Assume co-presence by default:

• The user can see diagram updates in real time.
• The user can see where the agent is focused.
• The agent should steer attention visually, then speak briefly.

Drive collaboration with this state model:

• attention.human.read

  : read the human cursor/attention in TUI.

• attention.agent.read

  : read the agent spotlight object.

• attention.agent.set

  : move the agent spotlight to one object.

• attention.agent.clear

  : clear the agent spotlight.

• follow_ai.read

  /

  follow_ai.set

  : read or toggle whether TUI follows agent spotlight.

• selection.read

  /

  selection.update

  : shared working-set selection (multi-object).

Treat these as separate concerns:

• Human attention: what the person is looking at.
• Agent attention: what the agent wants to emphasize now.
• Selection: short-term working set for batch reasoning/edits.
• Follow-AI: whether the TUI camera/cursor tracks agent spotlight.

Core Principles

• Treat AST as source of truth; rendered text and Mermaid text are projections.
• Session files (

  nereid-session.meta.json

  ,

  diagrams/*.mmd

  ,

  walkthroughs/*.wt.json

  ) are app-managed snapshots and can be rewritten frequently while Nereid runs.
• Use canonical

  ObjectRef

  everywhere:

  d:<diagram_id>/<seq|flow>/<participant|message|node|edge>/<object_id>

  .
• Prefer small reads first (

  diagram.stat

  ,

  diagram.get_slice

  ,

  diagram.diff

  ,

  walkthrough.diff

  ).
• Use typed query tools (

  seq.*

  ,

  flow.*

  ,

  xref.*

  ,

  route.find

  ) before large snapshots.
• Gate edits with

  base_rev

  and keep ops minimal.
• Record evidence as refs (xrefs and walkthrough nodes) so reasoning is resumable.
• Keep dangling xrefs visible as TODO artifacts unless asked to clean them.

Execution Discipline

• Use MCP tools as the only source of truth.
• Do not inspect

  src/

  ,

  tests/

  ,

  docs/

  , or

  data/

  to answer runtime collaboration questions.
• Make the first relevant MCP call immediately after reading the user prompt.
• Prefer direct MCP execution over schema/code exploration.
• If payload shape is unclear, call the tool once and adapt from validation errors.
• Use shell/file probing only when the user explicitly asks for file-level inspection or storage debugging.

Tool Groups

• Diagram lifecycle and target:

  diagram.list

  ,

  diagram.open

  ,

  diagram.delete

  ,

  diagram.current

  ,

  diagram.create_from_mermaid

• Diagram reads:

  diagram.stat

  ,

  diagram.get_slice

  ,

  diagram.diff

  ,

  diagram.read

  ,

  diagram.get_ast

  ,

  diagram.render_text

• Diagram mutation:

  diagram.propose_ops

  ,

  diagram.apply_ops

• Walkthrough lifecycle and target:

  walkthrough.list

  ,

  walkthrough.open

  ,

  walkthrough.current

• Walkthrough reads:

  walkthrough.stat

  ,

  walkthrough.diff

  ,

  walkthrough.read

  ,

  walkthrough.get_node

  ,

  walkthrough.render_text

• Walkthrough mutation:

  walkthrough.apply_ops

• Collaboration state:

  attention.human.read

  ,

  attention.agent.read

  ,

  attention.agent.set

  ,

  attention.agent.clear

  ,

  follow_ai.read

  ,

  follow_ai.set

  ,

  selection.read

  ,

  selection.update

  ,

  view.read_state

• Cross-diagram mapping:

  xref.list

  ,

  xref.neighbors

  ,

  xref.add

  ,

  xref.remove

• Object inspection:

  object.read

• Query helpers (route):

  route.find

• Query helpers (sequence):

  seq.messages

  ,

  seq.search

  ,

  seq.trace

• Query helpers (flow):

  flow.reachable

  ,

  flow.paths

  ,

  flow.cycles

  ,

  flow.unreachable

  ,

  flow.dead_ends

  ,

  flow.degrees

Default Operating Loop

1. Resolve target:

   • diagram.current

     ->

     diagram.list

     ->

     diagram.open

     .

   • walkthrough.current

     ->

     walkthrough.list

     ->

     walkthrough.open

     .
   • if no diagram exists yet, bootstrap with

     diagram.create_from_mermaid

     .
2. Read live collab state:

   • attention.human.read

     ,

     attention.agent.read

     ,

     follow_ai.read

     ,

     selection.read

     .
3. Probe local context:

   • diagram.stat

     ,

     diagram.get_slice

     , then one or two typed queries.
4. Steer visual attention:

   • attention.agent.set

     to the object currently being discussed.
   • keep chat short while attention marker carries micro-guidance.
5. Propose and apply minimal edits:

   • diagram.propose_ops

     ->

     diagram.apply_ops

     .

   • walkthrough.apply_ops

     for walkthrough refinement.
6. Refresh with deltas:

   • diagram.diff

     /

     walkthrough.diff

     (avoid full re-read unless needed).

Live Co-Presence Rules

• Use spotlight-first communication: set

  attention.agent.set

  before explaining a local change.
• Move spotlight when changing topic; clear it when complete.
• Keep narration compact when user is actively watching the diagram.
• Skip spotlight changes for quick query-only answers unless orientation is needed.
• Use

  selection.update

  for temporary multi-object working sets, not as a focus proxy.
• For create/switch-only requests, stop after

  diagram.create_from_mermaid

  (and optional

  attention.agent.set

  ); avoid extra

  diagram.stat

  ,

  diagram.render_text

  , or

  flow.*

  probes unless the user asks for inspection/debugging.

Tool Contracts (Input/Output)

diagram.create_from_mermaid

Input:

{
  "mermaid": "flowchart TD\n  A --> B",
  "diagram_id": "d-my-flow",
  "name": "My Flow",
  "make_active": true
}

Output:

{
  "diagram": {
    "diagram_id": "d-my-flow",
    "name": "My Flow",
    "kind": "flowchart",
    "rev": 0
  },
  "active_diagram_id": "d-my-flow"
}

diagram.delete

Input:

{
  "diagram_id": "d-my-flow"
}

Output:

{
  "deleted_diagram_id": "d-my-flow",
  "active_diagram_id": "d-next"
}

diagram.get_slice

Input:

{
  "diagram_id": "d-flow",
  "center_ref": "d:d-flow/flow/node/n:a",
  "radius": 1,
  "depth": 1,
  "filters": {
    "include_categories": ["flow/node", "flow/edge"],
    "exclude_categories": []
  }
}

Output:

{
  "objects": ["d:d-flow/flow/node/n:a", "d:d-flow/flow/node/n:b"],
  "edges": ["d:d-flow/flow/edge/e:ab"]
}

diagram.apply_ops

Input:

{
  "diagram_id": "d-seq",
  "base_rev": 3,
  "ops": []
}

Output:

{
  "new_rev": 4,
  "applied": 1,
  "delta": { "added": [], "removed": [], "updated": [] }
}

walkthrough.apply_ops

Input:

{
  "walkthrough_id": "w:1",
  "base_rev": 0,
  "ops": []
}

Output:

{
  "new_rev": 1,
  "applied": 1,
  "delta": { "added": [], "removed": [], "updated": [] }
}

object.read

Input:

{ "object_ref": "d:d-seq/seq/block/b:0000" }

Output:

{
  "objects": [
    {
      "object_ref": "d:d-seq/seq/block/b:0000",
      "object": {
        "type": "seq_block",
        "kind": "alt",
        "header": "guard",
        "section_ids": ["sec:0000:00", "sec:0000:01"],
        "child_block_ids": []
      }
    },
    {
      "object_ref": "d:d-seq/seq/section/sec:0000:00",
      "object": {
        "type": "seq_section",
        "kind": "main",
        "header": "ok",
        "message_ids": ["m:0000"]
      }
    }
  ],
  "context": {}
}

attention.human.read

Input:

{}

Output:

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention.agent.read

Input:

{}

Output:

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention.agent.set

Input:

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize"
}

Output:

{
  "object_ref": "d:d-auth-flow/flow/node/n:authorize",
  "diagram_id": "d-auth-flow"
}

attention.agent.clear

Input:

{}

Output:

{
  "cleared": 1
}

follow_ai.read

Input:

{}

Output:

{
  "enabled": true
}

follow_ai.set

Input:

{
  "enabled": true
}

Output:

{
  "enabled": true
}

selection.update

Input:

{
  "object_refs": [
    "d:d-auth-flow/flow/node/n:start",
    "d:d-auth-flow/flow/node/n:authorize"
  ],
  "mode": "replace"
}

Output:

{
  "applied": [
    "d:d-auth-flow/flow/node/n:authorize",
    "d:d-auth-flow/flow/node/n:start"
  ],
  "ignored": []
}

Probe-and-Refine on Charts

Use a shallow, typed exploration loop:

1. Anchor on one object (

   attention.human.read

   or explicit

   object_ref

   ).
2. Pull local structure with

   diagram.get_slice

   .
3. Ask one typed question (

   seq.*

   ,

   flow.*

   ,

   xref.*

   ,

   route.find

   ).
4. Shift agent spotlight to next object if needed.
5. Repeat until ambiguity is resolved.

Escalate to global reads (

diagram.read

,

diagram.get_ast

,

diagram.render_text

) only when local probes are insufficient.

Mutation Discipline

• Use

  diagram.propose_ops

  before

  diagram.apply_ops

  for non-trivial edits.
• Keep op batches minimal and scoped to one local intent.
• Use stable IDs for all new objects.
• Re-read

  diagram.stat

  or

  diagram.diff

  after apply to confirm resulting rev/state.

Walkthrough and Evidence Artifacts

Build walkthroughs as resumable breadcrumbs:

• Add concise nodes with evidence refs (

  refs

  ).
• Keep node titles short; put detail in

  body_md

  .
• Link nodes incrementally as understanding grows.
• Update walkthroughs after edits instead of re-deriving from scratch.

Use xrefs to preserve cross-diagram semantics:

• xref.add

  for implementation/expansion links.

• xref.list

  and

  xref.neighbors

  for map and traversal.
• Surface dangling xrefs explicitly for follow-up.

Conflict Recovery

When mutation fails due to stale

base_rev

:

1. call

   diagram.diff

   or

   walkthrough.diff

   from last known rev,
2. rebase ops on

   current_rev

   ,
3. retry with updated

   base_rev

   .

If diff history window is exhausted, fetch a fresh snapshot (

diagram.read

or

walkthrough.read

) and resume delta-first flow.

Reporting Discipline

Report only what the user needs:

• include target (

  diagram_id

  /

  walkthrough_id

  ) and revision movement (

  base_rev

  ->

  new_rev

  ),
• include concise deltas and key refs,
• avoid full AST/text dumps unless requested,
• in live sessions, avoid narrating every micro-step already visible in TUI.

MCP Playbook Companion

Use

references/mcp-playbooks.md

for extra payload templates. Keep this file as the primary protocol and behavior contract.