Restructure README for onboarding and ops docs

[prathamdby]

Summary

• Reworks README.md into an onboarding-focused layout (hero, TOC, Getting Started, Why, Features, See It in Action, How It Works, Data Privacy) with a Mermaid runtime topology diagram and async intake callout
• Adds Configure the agent provider covering Pi (AGENT_PROVIDER=pi, PI_PROVIDER, API keys) vs Cursor (AGENT_PROVIDER=cursor, CURSOR_API_KEY, supported models)
• Moves detailed behaviour, Docker/deployment notes, scripts table, and security logging into new docs/operations.md; trims duplicate local-dev prose from docs/agent-work-ops.md
• Replaces README screenshot placeholders with real PNGs for /describe, /review, /ask, /review-security, and /review-quality
• Adds an AGENTS.md rule to update the README Mermaid diagram when runtime topology changes

Test plan

• Preview README.md on GitHub (Mermaid, <details> images, anchor links)
• Confirm doc cross-links resolve (operations.md, configuration.md, agent-work-ops.md)

---

PR Agent Description

PR Type

Documentation, Enhancement

Description

• Rewrite README with TOC, Docker Compose quick-start, provider tables, screenshot galleries, runtime topology diagram, and data privacy section
• Create docs/operations.md consolidating behaviour semantics, deployment, developer scripts, and security notes from README and other sources
• Update AGENTS.md with doc maintenance rule for the README topology diagram
• Add 5 example screenshots for /describe, /review, /ask, /review-security, /review-quality

Changes Diagram

flowchart LR
  A["README.md rewrite"] --> B["New structure: TOC, quick-start, gallery"]
  B --> C["Runtime topology mermaid diagram"]
  D["docs/operations.md added"] --> E["Behaviour + deployment + scripts"]
  F["AGENTS.md update"] --> G["Diagram maintenance rule"]
  H["5 example screenshots"] --> I["Feature gallery in README"]

Loading

File Walkthrough

Documentation (10 files)

Complete README rewrite with new structure

README.md

• Add TOC, Getting Started, Docker Compose and local dev flows
• Add agent provider configuration tables (Pi, Cursor)
• Add feature tables, screenshot galleries, runtime topology diagram
• Add Why Use and Data Privacy sections
• Move detailed behaviour content to docs/operations.md

New consolidated operations reference

docs/operations.md

• Consolidate behaviour semantics from README
• Cover deployment, Docker Compose, runtime, local dev edge cases
• List developer scripts and Effect version gate
• Include security notes and logging config

Update to reference operations.md

docs/agent-work-ops.md

• Add cross-reference to new docs/operations.md
• Update queue list to include description queue

Add cross-reference to operations.md

docs/configuration.md

• Link to docs/operations.md for behaviour and deployment detail

Add documentation maintenance rules

AGENTS.md

• Add rule to update README topology diagram on runtime changes
• Define what counts as topology change vs not

Add /describe example screenshot

docs/readme/assets/describe.example.png

• Screenshot asset for README feature gallery

Add /review example screenshot

docs/readme/assets/review.example.png

• Screenshot asset for README feature gallery

Add /ask example screenshot

docs/readme/assets/ask.example.png

• Screenshot asset for README feature gallery

Add /review-security example screenshot

docs/readme/assets/review-security.example.png

• Screenshot asset for README feature gallery

Add /review-quality example screenshot

docs/readme/assets/review-quality.example.png

• Screenshot asset for README feature gallery

[zeus-review]

PR Agent Review

Note

This PR restructures the project's documentation: rewrites README.md as a polished landing page (removing detailed technical content), creates a new docs/operations.md file consolidating behaviour semantics, deployment details, and developer scripts, and updates cross-references in AGENTS.md, docs/agent-work-ops.md, and docs/configuration.md to point to the new operations.md. Five PNG example screenshots are added for the "See It in Action" section. No application code is changed — this is a documentation-only refactor.

Effort	Light · 1/5
Findings	No issues on this pass.
Relevant tests	no
Security	No security concerns identified

[prathamdby]

/review-quality

[zeus-review]

PR Agent Quality Review

Note

A documentation-only restructuring that splits the monolithic README into a polished landing page (README.md) with a Mermaid topology diagram, screenshots, and quick-start sections, while migrating detailed behaviour semantics, deployment instructions, developer scripts, and security notes into a new dedicated docs/operations.md. Cross-references are updated in AGENTS.md, docs/configuration.md, and docs/agent-work-ops.md. No application source code is changed.

Effort	Light · 1/5
Findings	No issues on this pass.
Relevant tests	no
Security	No security concerns identified