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

- Remove customer, product and person names, a customer incident's
  details, internal tool names and internal ticket IDs from docs, agent
  instructions, code comments and test fixtures. Lessons are kept in
  neutral terms; fixture renames don't change what tests check.
- Fix README examples a new user would copy and break on: personalities
  need an assistant and scenarios need instructions and evaluations (the
  old examples used fields the API rejects), state files store
  {"uuid": …} entries, and squads hand off through handoff tools.
- Add examples/starter, a complete small org, and build the README's File
  Formats section from its files. tests/examples.test.ts checks that every
  example org passes validate and has the fields the API requires, that the
  starter's PR check builds cleanly, and that every doc snippet naming an
  example file matches it exactly.
- Add CONTRIBUTING.md, SECURITY.md (GitHub private vulnerability
  reporting), and issue forms; update package.json's description.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: scott-lowe-vapi

.conductor/setup.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Conductor setup script for gitops-mudflap.
+# Conductor setup script for this repository.
 #
 # Wire-up: this script is dispatched from `conductor.json` at the repo root:
 #   {"scripts": {"setup": "bash .conductor/setup.sh"}}

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug report
+description: Something in the sync engine, CLI or workflows didn't work as documented.
+labels: [bug]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+      description: What you expected, and what happened instead.
+    validations:
+      required: true
+  - type: textarea
+    id: command
+    attributes:
+      label: Command and output
+      description: The exact command you ran and its output. Remove API keys and any customer data.
+      render: shell
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      description: The commit or release of this repo you're on (`git log -1 --oneline`).
+  - type: input
+    id: node
+    attributes:
+      label: Node version
+      description: Output of `node --version`.
+  - type: dropdown
+    id: region
+    attributes:
+      label: Vapi region
+      options: [US, EU]

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/VapiAI/gitops/security/advisories/new
+    about: Please report security issues privately, not as public issues.
+  - name: Vapi platform docs and support
+    url: https://docs.vapi.ai
+    about: Questions about the Vapi platform itself rather than this repository.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,15 @@
+name: Feature request
+description: Suggest a change or new capability.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem would this solve?
+      description: Describe what you're trying to do and what gets in the way today.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What would you like to happen?

.gitignore

@@ -5,7 +5,7 @@ node_modules/
 pnpm-lock.yaml
 
 # Environment files (secrets - never commit these!)
-# Covers dev/stg/prod and any org slug (e.g. .env.roofr-production)
+# Covers dev/stg/prod and any org slug (e.g. .env.acme-production)
 .env
 .env.*
 !.env.example

CLAUDE.md

@@ -15,7 +15,7 @@ When both files exist, follow both. If guidance overlaps, treat `AGENTS.md` as t
 
 **The Vapi PATCH API does NOT deep-merge nested objects. When you PATCH a nested object (`model`, `voice`, `transcriber`, `messagePlan`, `analysisPlan`, `artifactPlan`, `voicemailDetection`, `startSpeakingPlan`, `stopSpeakingPlan`) with a partial body, the API REPLACES the entire object — wiping every field you didn't include.**
 
-This wiped three live-production assistants' system prompts on 2026-05-13 (gitops-mudflap iForm barge fleet). The PATCH was `{"model": {"model": "gpt-4.1", "provider": "openai", "maxTokens": 260, "temperature": 0.3, "toolIds": [...]}}` — looked complete, but did NOT include `model.messages`. Result: prompts gone, live calls ran with empty system prompt until the operator forced a restore.
+This wiped three live-production assistants' system prompts in a customer fork on 2026-05-13. The PATCH was `{"model": {"model": "gpt-4.1", "provider": "openai", "maxTokens": 260, "temperature": 0.3, "toolIds": [...]}}` — looked complete, but did NOT include `model.messages`. Result: prompts gone, live calls ran with empty system prompt until the operator forced a restore.
 
 **Mandatory workflow for any direct API PATCH against a nested object:**
 
@@ -88,8 +88,7 @@ file paths with line numbers so future readers can verify your claims.
 When a fix lands, mark the entry `[RESOLVED YYYY-MM-DD] (#<PR-number>)` at
 the top — don't delete it. The history is the point.
 
-Customer-fork logs (`gitops-mudflap/improvements.md`,
-`gitops-amazon3p/improvements.md`) feed upstream: when an entry there is
+Customer forks' own `improvements.md` logs feed upstream: when an entry there is
 generic enough to apply across customers, surface it here in the same
 revision.
 

CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+Thanks for helping improve Vapi GitOps. Bug reports, docs fixes and new
+learnings are all welcome.
+
+## Reporting a problem
+
+- **Bugs and feature requests:** open a [GitHub issue](https://github.com/VapiAI/gitops/issues/new/choose).
+  For bugs, include the command you ran, its output (with API keys removed),
+  your Node version, and whether the org is in the US or EU region.
+- **Security issues:** don't open a public issue. Follow [SECURITY.md](SECURITY.md).
+- **Questions about the Vapi platform itself** (not this repo) belong with
+  [Vapi support](https://docs.vapi.ai).
+
+## Making a change
+
+1. Fork the repository and create a branch.
+2. Install and check that everything passes before you start:
+
+   ```bash
+   nvm use
+   npm ci
+   npm run build   # type-checks src/ and tests/
+   npm test
+   ```
+
+3. Make your change, with tests for any behaviour change. Tests use
+   `node:test` and live in `tests/`; they never call the real Vapi API.
+4. Run `npm run build` and `npm test` again, then open a pull request.
+
+Commit messages and PR titles follow [Conventional Commits](https://www.conventionalcommits.org/)
+(`fix(pull): …`, `feat(check): …`, `docs: …`).
+
+## Where things go
+
+| You're adding… | Put it in |
+| --- | --- |
+| A Vapi platform gotcha, recipe or troubleshooting guide | `docs/learnings/<topic>.md`, plus a row in [`docs/learnings/README.md`](docs/learnings/README.md) and the table in `AGENTS.md` for a new file |
+| A sync-engine pain point and its fix (pull, push, state, cleanup) | `improvements.md`, in its Problem → Current behavior → Risk → Current mitigation → Possible fix → Status format |
+| Setup or orientation for new users | `README.md` (keep it short; link to a guide for depth) |
+| An example users can copy | `examples/`. Snippets in the docs that start with `# examples/<path>` must match the file exactly; `npm test` checks this. |
+
+Don't edit `docs/changelog.md` here. It's a template for your own
+deployment's change log once you fork the repo.
+
+Coding agents (Claude Code, Cursor, Codex) read [`AGENTS.md`](AGENTS.md) and
+[`CLAUDE.md`](CLAUDE.md); keep them in step when a convention changes.