docs: prepare for public release: scrub internal names, fix examples, add community files

[scott-lowe-vapi]

Value

V.A.L.U.E. tier: small — docs, examples and tests for the public launch of this repo, plus comment and fixture-name changes in code. No behaviour change. Not micro: it spans more than 8 files.

• Problem: we're about to link this repo from the Vapi docs, which will bring many more readers, and it wasn't ready for them.
  • Leaks: tracked files named customers and their products, described a customer's production incident, and cited internal ticket IDs and staff handles.
  • Broken examples: the README's simulation examples used fields the API rejects, so a new user copying them would fail on their first apply.
  • No community files: there was no CONTRIBUTING.md or SECURITY.md, so issues and vulnerability reports had nowhere to go.
• Who it affects: everyone arriving from the docs, and the customers named in the files.
• What changes:
  • Scrub: customer, product and person names, the incident's identifying details, an internal logging tool's name, and internal ticket IDs are removed from CLAUDE.md, improvements.md, docs/learnings/, code comments and test fixtures. The lessons are kept in neutral words, and renamed fixtures keep the same test meaning.
  • Fixed examples:
    • personalities need assistant, and scenarios need instructions and evaluations;
    • state files store {"uuid": …} entries;
    • squads hand off through handoff tools.
  • examples/starter/: a complete small org that the README's File Formats section is now built from.
  • New tests/examples.test.ts, checking that:
    • every example org passes validate;
    • every example has the fields the API requires;
    • the starter's PR check builds cleanly;
    • every doc snippet that starts with # examples/<path> matches that file exactly.
  • CONTRIBUTING.md and SECURITY.md. Security reports go through GitHub private vulnerability reporting, which is already enabled on the repo.
  • Issue forms (bug, feature, contact links) and a current package.json description.

Evidence of value

• Scrub: a word-boundary search of every tracked file for the customer, product, person and ticket names now finds nothing; a broader search for internal tools and monorepo paths is also clean.
• Examples test catches drift: changing one character in examples/starter/.../squads/front-desk.yml turns the snippet test red, naming the file.
• Starter dry run: npm run check -- core --dry-run on the starter builds 1 simulation (3.5 KB) with no warnings.
• Links: every relative link and anchor across all 37 markdown files resolves.
• Tests: npm test goes from 492 to 496 passing.

Testing plan

• tests/examples.test.ts (4 tests), plus the existing suite with renamed fixtures.
• Not tested:
  • a live deploy of the starter (it uses example.com tool URLs on purpose);
  • git history still contains the removed names. Rewriting public history is a separate decision.

Stacked on #66.

🤖 Generated with Claude Code

[scott-lowe-vapi]

• 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
• docs: prepare for public release: scrub internal names, fix examples, add community files #69 👈 (View in Graphite)
• 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.

[chris-garber-vapi]

lgtm, I think this all goes in the right direction

[scott-lowe-vapi]

Merge activity

• Oct 7, 5:47 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Oct 7, 5:53 PM UTC: Graphite rebased this pull request as part of a merge.
• Oct 7, 5:53 PM UTC: @scott-lowe-vapi merged this pull request with Graphite.