docs: edit the guides for new readers and fix inaccuracies

[scott-lowe-vapi]

Value

V.A.L.U.E. tier: small — docs only. It edits the guides that #70 moved, for readers who don't know the repo's history, and fixes inaccuracies. Not micro: more than 200 lines.

• Problem:
  • Insider wording: the moved content read like a changelog ("used to spawn duplicates", "the CLI now refuses", "P0-1 regression suite").
  • Duplicates: some content still repeated itself.
  • Inaccuracies: a few statements were wrong, and two troubleshooting tips could make things worse.
• What changes:
  • Workflows:
    • one section each for deploying (including scoped deploys), starting fresh, creating new resources, pulling, testing, recovering and cleaning up;
    • the AI-agent callout becomes a note for the user, since AGENTS.md already instructs agents.
  • Commands: one sentence per command, and the false claim that every command is interactive is fixed. migrate moves to "Upgrading from an older version".
  • Configuration: documents every setting users set: per-org .env values and generated bindings, precedence, the promotion and PR check secrets and variables, config files, and the CI and debug variables.
  • How it works: the stale project tree (a third of src/, 5 of 68 tests, internal labels) becomes a short "Where things live" table. The guide now says push deletes only with --force.
  • Troubleshooting:
    • it no longer advises deleting a state entry, which made the next deploy treat the file as new;
    • it no longer suggests quietly editing engine code. It points at audit's per-finding suggested fixes, and at opening an issue.

Evidence of value

Every changed claim was checked against the code:

• apply forwards type and path arguments to pull and push, which share the parser that rejects bare IDs;
• setup, apply, pull, push, cleanup and call are the only interactive commands;
• environment variables beat .env files, and .env.<org>.local only fills gaps;
• the EU base URL is https://api.eu.vapi.ai;
• push prints "Deletions: Disabled (pass --force to enable)";
• audit reports state-ghost and state-uuid-collision with a suggested action.

All links resolve and npm test passes, 496 tests.

Found while checking, not changed here: src/config.ts comments .env.<org>.local as "local overrides", but the loader reads it after .env.<org> and only fills unset variables, so it can't override anything. The guide documents the actual behaviour. Fixing the code or the comment is a separate change.

Testing plan

• The link checker and npm test.
• Not tested: the commands and workflows against a real org (this PR changes no commands).

Stacked on #70.

🤖 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 👈 (View in Graphite)
• docs: restructure the README into a short landing page and topic guides #70
• 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.