Add visual README and universal agent init

Merged
DA
6mo ago
+4955-131

Summary

  • Adds braid agent-init as the universal activation command for Claude, Codex, Cursor, and Copilot.
  • Rewrites the public README as a GitHub-ready technical landing page.
  • Adds editable Excalidraw sources plus SVG exports for memory boundaries, agent activation, and retrieval flow.

Test Plan

  • Validated README image links and parsed all Excalidraw/SVG assets.
  • PYTHONPATH=src .venv/bin/python -m pytest -q
  • PYTHONPATH=src .venv/bin/python -m braid.cli --help
  • braid agent-init --check --json
  • rg -n "wikiforge|fairlead" README.md only shows explicit legacy alias note.
  • git diff --check
  • git diff --cached --check

Summary by cubic

Adds a universal braid agent-init across Claude, Codex, Cursor, and Copilot, plus braid doctor, status --json, a new braid patterns playbook, and Obsidian export. Replaces the README with a visual, GitHub-ready landing page and updated diagrams.

  • New Features

    • braid agent-init with --agent, --check, --fix, --remove, --json. Idempotent; no indexing; respects nearest project boundary. Sets Claude SessionStart hook + MCP (braid mcp-serve), Codex session hook, and Cursor/Copilot discovery symlinks. braid claude-init now delegates.
    • Diagnostics: braid doctor [--json] [--fix] checks install, context, agents, secrets, and drift. braid status --json emits a stable payload. Config hardening preserves invalid JSON instead of overwriting.
    • Playbook: braid patterns [--json] exposes the operational patterns read-only, aligned with the new diagrams.
    • Wiki export: braid wiki build --obsidian creates an Obsidian vault in .braid/wiki/obsidian/ or writes to --vault (under Braid/<dataset_id>/). Supports --output for a fresh vault.
    • Docs/CI: visual README with refreshed diagrams (agent activation, memory boundaries, retrieval flow, operational patterns). CI validates README assets and uses actions/checkout@v6, actions/setup-python@v6 on Python 3.11. ADR 0017/0018/0019/0020 included. Tests cover drift detection, fix/remove, boundary resolution, JSON outputs, patterns, and Obsidian export.
    • DuckLake: SQL formatting fix for Python 3.11 and auto-install of DuckDB FTS in clean environments.
  • Migration

    • Run braid agent-init --fix in each repo to normalize hooks, MCP, and discovery symlinks.
    • Use braid agent-init --check --json and/or braid doctor --json in CI to detect drift; --remove uninstalls only Braid-managed blocks.
    • Optional: export memory to Obsidian with braid wiki build --obsidian.

Summary by CodeRabbit

  • New Features

    • Added braid agent-init (apply/check/fix/remove) with --json and backward-compatible claude-init delegation.
    • New CLI commands: braid doctor (diagnostics, optional --fix/--json), braid status --json, and braid patterns [--json].
    • braid wiki gains Obsidian vault export mode (--obsidian, --vault/--output handling).
  • Documentation

    • Expanded README and added diagrams for agent activation, memory boundaries, retrieval flow, and operational patterns.
  • Tests & CI

    • New test suites for agent-init, doctor/status/patterns/wiki workflows and CI pipeline validating docs, tests, and CLI smoke checks.