#133 docs: rewrite README to lead with doer-reviewer loops and add FAQ

[Anonymous]

Originally created by: kumaakh

Summary

This PR rewrites the README and docs to lead with apra-fleet's strongest feature (doer-reviewer loops) instead of infrastructure orchestration, and makes the docs more discoverable by AI agents.

What this PR changes

• Repositioned the tagline and intro to lead with the doer-reviewer workflow instead of multi-machine SSH orchestration — this is the feature that makes fleet valuable even on a single machine
• Added a "single machine" quickstart path so new users don't assume they need remote servers to get started
• Added one-liner install commands for macOS, Linux, and Windows — copy-paste from the README and you're running
• Added provider recommendations table to the README (PM/doer/reviewer role guidance) — this was buried in the user guide
• Synced the README tool table with CLAUDE.md — added receive_files, compose_permissions, provision_llm_auth, version that were missing
• Added an FAQ section to the README with 8 collapsible Q&As sourced from the FAQ discussion index
• Created docs/FAQ.md as a structured lookup table optimized for AI agents, with llm-context, keywords, and see-also HTML comments
• Added LLM context hints to 8 doc files (user-guide, architecture, cloud-compute, provider-matrix, design-git-auth, adr-oob-password, vocabulary, ssh-setup) — invisible to humans on GitHub, but help AI agents match user questions to the right doc
• Converted all plain doc references to clickable links across README
• Added one-liner install to docs/user-guide.md alongside the existing manual install steps
• Documented send_files directory workaround in skills/fleet/SKILL.md — a tar+extract pattern for transferring directories until issue [#98] is resolved

Preserved

All existing content (tools table, git auth, cloud compute, secure password entry, development, roadmap, license) is unchanged.

Motivation

The current README leads with "coordinate AI coding agents across every machine in your network" which positions fleet as a multi-machine orchestration tool. This filters out single-machine developers who would benefit from the doer-reviewer loop. The rewrite puts the highest-value, lowest-barrier feature front and center.

Suggestions for the Apra Labs team

Beyond what this PR covers, here are additional improvements that need your involvement:

1. Adopt the llms.txt convention

The llms.txt convention (llmstxt.org) is emerging as the standard for AI-discoverable project docs. Rename or duplicate CLAUDE.md as llms.txt at the repo root — tools beyond Claude Code (Cursor, Copilot, Windsurf) will pick it up. You already support multiple agents; the docs should too.

2. Add a llms-full.txt that concatenates the key docs

Agents that land on a repo often read one file and stop. A single llms-full.txt that combines the user guide, FAQ, provider matrix, and vocabulary means one read gives full context. Can be auto-generated in CI.

3. Add a "What happens when I run install --skill?" section

The user guide lists what install does, but it's buried. People (and agents) hesitate to run installers they don't understand. A visible, short explainer of what gets written where builds trust. This needs verification against actual installer behavior, which is why it's not in this PR.

4. FAQ: "Can I use fleet without the PM skill?"

The --skill flag is optional but every example includes it. Users who just want basic remote execution might think PM is required. Clarify the minimal vs. full setup in your Discussions FAQ.

5. Add a CONTRIBUTING.md with agent-friendly context

CLAUDE.md links to it but the file doesn't exist. Contributors (human or AI) need to know: how to run tests, what the PR process looks like, which issues are good first picks. The ROADMAP exists but a proper contributing guide ties it together.

6. Update GitHub repo description and topics

The repo description should match the new tagline, not the old infra-focused one. Add topics like mcp, multi-agent, code-review, doer-reviewer, ssh, llm-orchestration — these are how both humans and agents discover repos.

7. Ship a demo gif or asciicast

A 30-second recording of: install, register two local members, pair them, watch the doer-reviewer loop run. Worth more than 1000 words of documentation. GitHub renders these inline in the README.

The big picture

The product is genuinely good. The doer-reviewer loop is a real differentiator — most multi-agent tools just parallelize work, they don't build in quality gates. But the project currently reads like it was written for infrastructure engineers. The audience should be any developer who wants better code — that's a much larger market. Lead with outcomes (better code, fewer bugs), not mechanisms (SSH, MCP, registries).

Test plan

• [ ] Verify all doc links resolve correctly
• [ ] Confirm FAQ collapsible sections render properly on GitHub
• [ ] Confirm one-liner install URLs resolve via releases/latest
• [ ] Review that no existing content was lost
• [ ] Verify LLM context comments are invisible when rendered on GitHub

🤖 Generated with Claude Code

[Anonymous]

Ticket changed by: kumaakh

• status: open --> closed