docs(learnings): squad re-entry, silence, Cartesia, multi-STT keyterm, and rename gotchas

[dhruva-reddy]

Describe your changes

Adds eight battle-tested learnings entries to the gitops template, sourced from the customers/amazon/gitops-amazon3p deployment tracker (§7 "Known footguns"). All entries are tracker-validated against specific iterations (Iter13–Iter24), generalized to strip customer/business specifics, and concentrated in the existing learnings files most likely to be consulted before each gotcha bites.

docs/learnings/squads.md — three new sections, all gitops-relevant squad gotchas not previously covered:

• Inline model.messages in assistantOverrides silently shadows the assistant .md. Surfaced as an 8.6k-char inline prompt drifting from its source .md over multiple iterations. Recommends keeping the .md as single source of truth and using a second assistant file when a different prompt is genuinely needed.
• firstMessage replays on every handoff re-entry. Default firstMessageMode is assistant-speaks-first, which fires on every control transfer back to that assistant — not just call start. Recommends firstMessage: "" + assistant-speaks-first-with-model-generated-message for any non-terminal squad member, plus a "RE-ENTRY PROTOCOL" prompt block.
• Two silence handlers fire at once when both are configured. messagePlan.idleMessages (per-assistant) and customer.speech.timeout hooks (per-assistant or via membersOverrides.hooks) both fire on the same silence event. Recommends picking one — squad-level hooks usually preferable for triggerMaxCount / triggerResetMode support.

docs/learnings/assistants.md — refines an existing entry and adds a Cartesia subsection:

• numWords: 2 produces a 500–800ms TTS overlap window that drops STT confidence on barge-in, often filtering out the customer's first sentence after interrupting. The existing entry only documented the "lower = more interruptible" tradeoff; the new entry explains why numWords: 1 + Krisp denoising is the recommended pairing.
• Cartesia-specific config gotchas table covering rejected ElevenLabs-only fields (enableSsmlParsing, top-level voice.speed, voice.stability, voice.similarityBoost), plus the correct nested paths for generationConfig.speed and generationConfig.experimental.accentLocalization.
• Cartesia Sonic-3 mangles em-dashes and SSML <break> tags — pacing should use commas/periods/semicolons instead.

docs/learnings/multilingual.md — adds:

• English-heavy keyterm arrays bias Deepgram language: multi toward English. The language-ID step uses partial transcripts; an English-leaning keyterm tilts that signal, sending non-English audio through the English pipeline and producing low-confidence transcripts that get filtered. Recommends Gladia Solaria for code-switching customers, with a fallback recommendation for staying on Deepgram.

AGENTS.md — adds a "Renaming an existing resource" subsection under Naming Conventions:

• Documents that the engine's name_mismatch guard auto-bootstraps state from the dashboard before applying, so manually editing .vapi-state.<org>.json to repoint a renamed file at an existing UUID does not work. Lays out the two correct paths (rename locally + new UUID + cleanup orphan, or rename in dashboard + pull preserves UUID).

Relevant Context (linear ticket, slack link, etc)

Surfaced during a sweep of the Amazon 3P deployment tracker's "Known footguns" section after several of these gotchas hit consecutive iterations on a single customer. Eight of the sixteen tracked footguns were already covered by existing learnings (call-duration.md for LLM wall-clock, transfers.md for routing-bias, etc.) or are out of scope for the gitops template (dashboard UX bugs, customer-specific call-flow design). The remaining eight were filed here.

Engine-logic candidate flagged for follow-up, not included in this PR: the inline-model.messages shadow in squad overrides (#7 in the tracker) is plausibly a npm run push lint-warn opportunity — but legitimate cases for partial model overrides exist (temperature, tool sets), so a precise rule would need to target only the messages field. The doc warning is the right first step; the engine warning can come once the rule is well-scoped.

API Changes

• Is this changing the public API?

  • Yes
  • No

• If yes, is it backward‐compatible?

  • Yes
  • No

N/A — docs-only change. No engine or API surface modifications.

Non backward-compatible changes might break customers' agents. Please proceed with care and notify the team.

How did you test this?

• npm run build (tsc --noEmit) passes.
• Each new claim cross-checked against the tracker iteration that surfaced it (Iter13–Iter24, listed in the "First surfaced" column of customers/amazon/gitops-amazon3p/TRACKER.md §7).
• Generalization sweep run on the diff: rg -i 'amazon|youssaf|mudflap|notable|zeals|3p|iform|FBA' against the changed files returns only one false-positive hit (the literal string "duplication" in squads.md); no customer or business-specific terms leaked.
• Internal cross-references (call-duration.md, assistants.md interior links) verified to point at existing sections.

[dhruva-reddy]

• docs(learnings): squad re-entry, silence, Cartesia, multi-STT keyterm, and rename gotchas #12 👈 (View in Graphite)
• main

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

[dhruva-reddy]

Merge activity

• Apr 23, 5:36 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Apr 23, 5:36 PM UTC: @dhruva-reddy merged this pull request with Graphite.