Plan — /soul-join: managed remote souls + catalog + project binding

Problem

Three demarkus surfaces can be configured at once — a hand-wired .mcp.json demarkus server ("pure MCP", e.g. demarkus-soul → soul.demarkus.io), the demarkus-memory plugin (local managed soul), and the demarkus-knowledge plugin (broker KS). All expose identical mark_* tools, so the agent can't tell which to write to. Today a remote soul can only be reached by hand-editing .mcp.json, which also leaks the auth token in plaintext into both .mcp.json and claude mcp list. There is no /soul-join (the soul index Vocabulary already anticipates one).

Decision (Fritz, 2026-06-22)

Build /soul-join into demarkus-memory so there is no manual MCP for souls, mirroring /knowledge-join. Token storage = wrapper + 0600 file (no secret in config). Maintain a catalog of souls plus a per-project binding that routes writes. Detect existing hand-wired demarkus-mcp entries and offer to adopt them.

Data model

• Catalog — ~/.demarkus/souls (tab-separated, one row per remote soul): <slug>\t<host>\t<insecure 0|1>\t<token-file|->. The local managed soul stays in plugin-memory.conf (tier=local); a catalog view unions local + remote + knowledge endpoints. Tiers: local (plugin-managed), remote (joined).
• Per-project binding — ~/.demarkus/project-souls: <project-dir>\t<slug>. Which catalog soul this repo writes to by default. Set when /soul-join runs inside a repo. This is the routing key that ends the "which one?" confusion.
• MCP registration scope — orthogonal: project (repo .mcp.json, default when joined in a repo) or user (global, no binding).

Components

1. lib.sh — SOULS_REGISTRY, PROJECT_SOULS paths; helpers register_remote_soul, remote_soul_fields, list_remote_souls, is_registered_remote_soul, bind_project_soul, project_soul_binding. Extend publish_gate_scope so the tag-gate also fires on registered remote souls (today only demarkus-memory).
2. scripts/soul-join.sh <host> [--token T] [--insecure] — normalize host (mark:// scheme, :6309 default port), derive + sanitize slug from first DNS label, write token to ~/.demarkus/soul-<slug>.token (mode 600), register_remote_soul, emit key=value. Reachability = best-effort (demarkus is QUIC, no HTTP metadata; first tool call is the real check).
3. scripts/soul-remote-wrapper.sh <slug> — registry-driven; exports DEMARKUS_AUTH from the token file and execs demarkus-mcp -host <host> [-insecure]. Same pattern as the local mcp-wrapper.sh.
4. scripts/detect-manual-souls.sh — scan project + user .mcp.json for unmanaged demarkus-mcp entries; feed the adopt flow.
5. commands/soul-join.md — mirrors knowledge-join.md; includes the detect-and-adopt step.
6. context/session-guidance.md — describe catalog + binding + roles.
7. tests/soul-join_test.sh; bump plugin.json version.

Constraints (project conventions)

• Pure awk/bash, no runtime deps (jq/python/node forbidden).
• Bash 3.2 (macOS stock). Branch + PR; Fritz commits. Never ship broken.

Open / phase 2

• A destination gate (PreToolUse on mark_publish) enforcing the project→soul binding so a misrouted write is denied, not just guided.
• /soul-join reachability hardening (one-shot stdio MCP probe).