docs: prioritize low-complexity agent primitives

[Yeshwanthyk]

Summary

This is a documentation-only exploration PR. It compares Ziggy with current agent frameworks, then turns the useful OpenClaw/Hermes invariants into a low-complexity implementation queue without adding another runtime, state authority, or protocol.

What this PR adds

• source-grounded Ziggy/eve/Flue comparison at:
  • vercel/eve@6c5f4fe2
  • withastro/flue@a171cc1b
  • ziggy@98988c29
• refreshed OpenClaw/Hermes source audit at:
  • openclaw/openclaw@50a30b73
  • NousResearch/hermes-agent@42708f8b
• an implementation-ready plan with three deliberately bounded slices:
  1. Pi-backed, read-only ziggy sessions <profile> [--json]
  2. local-only, non-mutating ziggy doctor <profile> [--json]
  3. optional (Profile, channel face) duplicate-resident lease, only if the operational risk is demonstrated
• corrected documentation for pinned Pi 0.82.0: recursive inventory should use SessionManager.listAll(customDirectory), not cwd-filtered list
• aligned the existing primitive, CLI, lease, and scheduler plans with that scope

Main decisions

Do next

1. Session inventory first

   • Pi remains the only JSONL/session-format reader.
   • Ziggy projects only ID, relative path, timestamps, and message count.
   • Transcript previews never leave the Pi adapter.
   • Symlink and Pi-metadata omission behavior is explicit and testable.

2. Narrow doctor second

   • Reads SOUL.md and reuses local channel/automation decoders plus session inventory.
   • Performs no provider call, channel connection, repair, migration, or extension execution.
   • Deliberately does not call Auth.status; Pi auth checks may create or refresh credential files.

3. Face-scoped lease only if needed

   • Prevents two Telegram residents, two Discord residents, or two Slack residents for one Profile.
   • Does not prevent Telegram + Discord + Slack from running together.
   • Uses an OS-released SQLite transaction, not PID files, heartbeats, stale-lock policy, or a daemon registry.

Keep out

• Profile-wide lease while channels are separate commands
• graceful-drain lifecycle state before interrupted work has a promised outcome
• scheduler/claim state before an automatic trigger exists
• custom skill metadata/parser, tool-search bridge, or marketplace
• durable gateway journals, replay, receipts, or a control plane
• embedding eve/Flue runtimes inside Ziggy

Integration conclusion

• Flue/eve: useful as separately owned remote workers over public clients/HTTP. Do not merge their sessions, memory, durability, or channel authorities into Ziggy.
• OpenClaw/Hermes: reference implementations for operational invariants, not runtimes to embed.
• Portable unit across these systems: Agent Skills, with host-specific tool/cwd/credential adaptation.

Key files

• docs/research/eve-flue-ziggy-comparison.md
• docs/research/openclaw-hermes-current-primitives.md
• docs/plans/openclaw-hermes-primitives.md
• docs/plans/resident-lease.md
• docs/plans/primitive-status.md
• docs/research/pi-sdk-surface.md

Validation

• bun run check
• bun test ./src ./extensions && bun run test:helpers — 74 Bun tests + helper suites pass
• git diff --check
• changed-document local links and source permalink line ranges verified against the exact cloned commits

Runtime impact

None. No production code, dependency, Profile format, session format, or persisted state changes in this PR.