docs: refocus README on team outcomes and move deep details to docs/

[benvinegar]

Summary

• rewrite README to lead with what Baudbot does for developer teams (always-on, multiplayer, Linux-native execution, persistent memory)
• add a concrete end-to-end workflow example (Slack request → dev agent → PR/CI → thread update)
• condense security coverage in README and position it as enabling infrastructure
• add deep-dive docs pages under docs/ for workflow, agents, memory, runtime, operations, and architecture
• add cross-links in CONTRIBUTING/SECURITY and update AGENTS docs-update guidance

Notes

• docs-only change
• no runtime behavior changes

[greptile-apps]

Greptile Summary

Rewrites the README to lead with team-facing outcomes (always-on Slack interface, multiplayer workflows, persistent memory) instead of security internals, and relocates deep architectural, operational, and behavioral documentation into six new pages under docs/.

• README.md: Condensed from ~230 lines to ~140 lines. Replaces detailed architecture diagrams, security stack table, operations runbook, and agent/integration tables with concise overviews and links to dedicated docs pages. Adds a concrete end-to-end workflow example.
• New docs/ pages: team-workflow.md, agents.md, memory.md, linux-runtime.md, operations.md, architecture.md — each covers a focused topic with internal cross-links.
• Cross-link updates: AGENTS.md convention updated to include docs/ in the docs-update checklist. CONTRIBUTING.md gains a documentation map section. SECURITY.md adds a navigation preamble.
• Minor note: The old README's "Adding agents" how-to (create skill file → add tmux spawn → deploy) was removed and not relocated to any docs/ page. This is a small discoverability gap for contributors wanting to add custom agent roles — consider adding it to docs/agents.md in a follow-up.

Confidence Score: 5/5

• This PR is safe to merge — it contains only documentation changes with no runtime behavior impact.
• All changes are documentation-only (Markdown files). No code, scripts, or configuration files are modified. Cross-links have been verified against existing files. CLI commands documented in ops pages match the actual bin/baudbot dispatcher. Content is factually consistent with AGENTS.md and SECURITY.md.
• No files require special attention. All changes are documentation restructuring.

Important Files Changed

Filename	Overview
README.md	Major rewrite: shifts from security-first positioning to team-outcomes framing. Removes detailed architecture/operations/security sections in favor of concise overview with links to new docs/ pages. Adds end-to-end workflow example. All links verified correct.
AGENTS.md	Single-line change: adds "relevant pages in docs/" to the docs-update guidance convention. Consistent with the new docs/ directory structure.
CONTRIBUTING.md	Adds "Documentation map" section with links to README, docs/, SECURITY.md, and CONFIGURATION.md. Updates test suite count from 8 to 10 to match AGENTS.md.
SECURITY.md	Adds cross-link paragraph at the top pointing to README.md, docs/architecture.md, and docs/operations.md. No changes to security content.
docs/team-workflow.md	New file: documents the request lifecycle from intake to close-out, including single-repo, multi-repo, follow-up, and failure/escalation flows. Cross-links to agents.md and operations.md.
docs/agents.md	New file: documents the three agent roles (control, dev, sentry), session model, concurrency limits, and communication contract. Content consistent with README and AGENTS.md.
docs/memory.md	New file: documents persistent memory design, file locations, operating rules, entry format, and maintenance guidance. Consistent with the memory section previously in README.
docs/linux-runtime.md	New file: documents Linux execution model, Docker wrapper usage, workspace layout, platform support (Ubuntu/Arch), and operational boundaries. Cross-links to SECURITY.md.
docs/operations.md	New file: documents day-2 ops commands (start/stop/deploy/update/rollback/doctor/audit), control plane setup, runbook actions, and uninstall. All CLI commands verified against bin/baudbot.
docs/architecture.md	New file: documents source/release/runtime layout, deployment flow, agent topology, and data path. Consistent with existing AGENTS.md architecture section.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    README["README.md\n(team outcomes overview)"]
    CONTRIB["CONTRIBUTING.md"]
    SECURITY["SECURITY.md"]
    AGENTS_MD["AGENTS.md"]
    CONFIG["CONFIGURATION.md"]

    TW["docs/team-workflow.md"]
    AG["docs/agents.md"]
    MEM["docs/memory.md"]
    LR["docs/linux-runtime.md"]
    OPS["docs/operations.md"]
    ARCH["docs/architecture.md"]

    README -->|"Documentation section"| TW
    README -->|"Documentation section"| AG
    README -->|"Documentation section"| MEM
    README -->|"Documentation section"| LR
    README -->|"Documentation section"| OPS
    README -->|"Documentation section"| ARCH
    README --> SECURITY
    README --> CONFIG
    README --> CONTRIB

    CONTRIB -->|"Documentation map"| README
    CONTRIB --> SECURITY
    CONTRIB --> CONFIG

    SECURITY -->|"nav preamble"| README
    SECURITY --> ARCH
    SECURITY --> OPS

    TW --> AG
    TW --> OPS
    AG --> TW
    MEM --> AG
    LR --> SECURITY
    OPS --> ARCH
    OPS --> SECURITY
    ARCH --> SECURITY
    AGENTS_MD -->|"docs-update convention"| README

Loading

_{Last reviewed commit: 97f4aca}