docs: restructure the README into a short landing page and topic guides

[scott-lowe-vapi]

Value

V.A.L.U.E. tier: small — docs only. This restructures the README for readers arriving from the Vapi docs. Not micro: more than 200 lines and 8 files.

• Problem: the README was 1,096 lines written for four audiences at once: newcomers, daily operators, promotion and CI admins, and coding agents. The first-run path was spread across three sections, some content appeared two or three times, and the docs/learnings/ field guide was only mentioned in a file tree.
• Who it affects: first-time visitors, who decide in seconds whether this is for them, and existing users looking for a specific topic.
• What changes:
  • A 275-line README, covering:
    • what the repo does, and a diagram;
    • a five-step quick start: get a private copy, install, connect an org, deploy, test;
    • core concepts, including what's committed and what isn't;
    • a one-line command table and guide links;
    • the field guide, and staying up to date;
    • security, contributing and license.
  • Getting a copy: clone-and-repush keeps upstream history, so updates are an ordinary merge. "Use this template" (the repo is a template) needs --allow-unrelated-histories once. A public fork would publish the user's configuration.
  • Long-form content moves verbatim into docs/guides/: commands, workflows, file formats, PR checks, promotion, how it works, configuration, troubleshooting. Only heading levels and relative links change, so this PR reviews as a move; docs: edit the guides for new readers and fix inaccuracies #71 edits the content.
  • References to old README sections (in vapi-checks.yml, AGENTS.md, SECURITY.md, simulations.md and the starter example) now point at the guides.

Evidence of value

• Nothing lost: of the old README's 795 content lines, 755 appear verbatim in the new README or a guide. The other 40 are the sections rewritten in the new README (intro, quick start, supported resources, API links) or retitled headings, and I checked each one by hand.
• Links: all links and anchors across 45 markdown files resolve.
• Tests: npm test passes, 496 tests, including the snippet test, which now reads the file formats guide.

Testing plan

• The link checker and the examples snippet test cover the moved content.
• The Mermaid diagram renders on GitHub (checked on this branch's README).
• Not tested: how the README renders on the Vapi docs site, if it's embedded there rather than linked.

Stacked on #69.

🤖 Generated with Claude Code

[scott-lowe-vapi]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• feat: identify every gitops API request with a User-Agent #78
• feat(validate): catch broken references and show findings on the PR #77
• ci: validate every org's resources on every pull request #76
• ci: lint workflows and test the PR check's key-sharing decision #75
• test(docs): check that doc links, commands and flags exist #74
• fix(cleanup): never delete resources matched by .vapi-ignore #73
• docs(agents): one compact guide for Claude, Codex and Cursor #72
• docs: edit the guides for new readers and fix inaccuracies #71
• docs: restructure the README into a short landing page and topic guides #70 👈 (View in Graphite)
• docs: prepare for public release: scrub internal names, fix examples, add community files #69
• feat(promotion): gate promotion out of an org on a passing check #66
• fix(promotion): commit the files of transitions that applied when a later one fails #65
• test(promotion): pin the exact files promoting an assistant writes to the target #68
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.