docs(readme): lead with the integration-filesystem-for-agents pitch + add comparison

[khaliqgant]

Summary

Restructures the top of the README so it leads with what relayfile is and why files before how to run it locally. Existing operational sections (Run Locally, Local Dev, Ecosystem, Hosted, Bring Existing Connections, Docs) are preserved unchanged.

What's added

• Hero — a short tagline plus an 8-line terminal example showing ls / cat / grep and a file-native PATCH writeback, so the value is visible in seconds without scrolling.
• Why files — context efficiency, completeness, and multi-agent coordination as the three reasons to pick this substrate over typed-tool MCP setups.
• What's in the box — file-native reads/writes, per-agent ACLs, real-time multi-agent sync, real OS mount, and the core + adapters + providers architecture as the resource-ceiling story.
• How relayfile compares — three factual contrasts:
  • vs. MCP servers — strong for typed writes, weaker for context cost and exhaustive enumeration. Calls out that the two compose well.
  • vs. Mirage and other virtual-filesystem-for-agents projects — polite, gives them credit, frames the difference as scope (storage/infra primitives vs. SaaS integrations) rather than head-to-head competition.
  • vs. rolling your own — when relayfile starts being worth it (multi-agent + ACLs + writeback contract).

Why now

• The "integration filesystem for agents" line was already in the README but buried; the doc led with docker compose up instead of the pitch.
• Other projects in the same conceptual space have shipped polished landings; the buyer who's evaluating "filesystems for agents" should be able to tell at a glance how relayfile is scoped without us slighting peers.
• File-native writeback (relayfile-adapters fix(mount): reduce websocket polling overhead #45) and the ACL / multi-agent story are real differentiators that weren't surfaced anywhere on the OSS landing.

Out of scope

• No badge row, architecture diagram, or asset additions in this PR — content first; visuals can land separately.
• No code changes; runtime behavior is unchanged.
• The post-Mount layout: add indexes, semantic aliases, and a SKILL.md to reduce agent file-shopping #106 mount layout (e.g. <sanitized-name>__<id>.json filenames) is not yet committed, so the example uses the simpler AGE-12.json form. When Mount layout: add indexes, semantic aliases, and a SKILL.md to reduce agent file-shopping #106 ships, the example can be tightened to match the canonical layout.

Test plan

• Render the diff on github.com/AgentWorkforce/relayfile/pull/ and confirm headings, code blocks, and the comparison table all render cleanly.
• Click every relative link (docs/guides/getting-started.md, docs/guides/cloud-integration.md, docs/api-reference.md, docker/README.md, openapi/relayfile-v1.openapi.yaml) and confirm none 404.
• Click every external link (relayfile-adapters, relayfile-providers, skills#28, Mirage) and confirm targets are correct.
• Skim with fresh eyes for tone — the Mirage paragraph should read polite, not throwaway and not adversarial.

🤖 Generated with Claude Code

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The README's introductory section is rewritten to present Relayfile as an integration filesystem for agents. The update expands the opening description, adds a workflow example demonstrating mount/cat/patch/grep operations, and introduces sections explaining the rationale for file-based interfaces, what Relayfile provides, and how it compares to MCP, Mirage, and custom agent integrations. The remainder of the document remains unchanged.

Changes

README Introduction Update

Layer / File(s)	Summary
README Introduction README.md	The top-level introduction (lines 1–49) is replaced with an expanded overview of Relayfile as an "integration filesystem for agents," including a practical mount/cat/patch/grep workflow example, explanations of why file-based interfaces matter for agents, a summary of Relayfile's capabilities, and a comparison to MCP, Mirage, and rolling custom solutions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• AgentWorkforce/relayfile#94: Directly related prior PR that also rewrites the README's top-level introduction to position Relayfile as an integration/VFS filesystem for agents.

Poem

🐰 A docs refresh, so clean and bright,
The README now explains it right,
A filesystem where agents play,
Mounting, patching files all day! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main changes: restructuring the README to lead with the 'integration-filesystem-for-agents' pitch and adding a comparison section.
Description check	✅ Passed	The description is comprehensive and directly related to the changeset, detailing all additions (Hero, Why files, What's in the box, How relayfile compares) and providing clear rationale.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree-readme-polish

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.