vora-ai 0.1.0

package/docs/reference/token-use.md

@@ -0,0 +1,175 @@
+---
+summary: "How Vora builds prompt context and reports token usage + costs"
+read_when:
+  - Explaining token usage, costs, or context windows
+  - Debugging context growth or compaction behavior
+title: "Token Use and Costs"
+---
+
+# Token use & costs
+
+Vora tracks **tokens**, not characters. Tokens are model-specific, but most
+OpenAI-style models average ~4 characters per token for English text.
+
+## How the system prompt is built
+
+Vora assembles its own system prompt on every run. It includes:
+
+- Tool list + short descriptions
+- Skills list (only metadata; instructions are loaded on demand with `read`)
+- Self-update instructions
+- Workspace + bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` when new, plus `MEMORY.md` when present or `memory.md` as a lowercase fallback). Large files are truncated by `agents.defaults.bootstrapMaxChars` (default: 20000), and total bootstrap injection is capped by `agents.defaults.bootstrapTotalMaxChars` (default: 150000). `memory/*.md` files are on-demand via memory tools and are not auto-injected.
+- Time (UTC + user timezone)
+- Reply tags + heartbeat behavior
+- Runtime metadata (host/OS/model/thinking)
+
+See the full breakdown in [System Prompt](/concepts/system-prompt).
+
+## What counts in the context window
+
+Everything the model receives counts toward the context limit:
+
+- System prompt (all sections listed above)
+- Conversation history (user + assistant messages)
+- Tool calls and tool results
+- Attachments/transcripts (images, audio, files)
+- Compaction summaries and pruning artifacts
+- Provider wrappers or safety headers (not visible, but still counted)
+
+For images, Vora downscales transcript/tool image payloads before provider calls.
+Use `agents.defaults.imageMaxDimensionPx` (default: `1200`) to tune this:
+
+- Lower values usually reduce vision-token usage and payload size.
+- Higher values preserve more visual detail for OCR/UI-heavy screenshots.
+
+For a practical breakdown (per injected file, tools, skills, and system prompt size), use `/context list` or `/context detail`. See [Context](/concepts/context).
+
+## How to see current token usage
+
+Use these in chat:
+
+- `/status` → **emoji‑rich status card** with the session model, context usage,
+  last response input/output tokens, and **estimated cost** (API key only).
+- `/usage off|tokens|full` → appends a **per-response usage footer** to every reply.
+  - Persists per session (stored as `responseUsage`).
+  - OAuth auth **hides cost** (tokens only).
+- `/usage cost` → shows a local cost summary from Vora session logs.
+
+Other surfaces:
+
+- **TUI/Web TUI:** `/status` + `/usage` are supported.
+- **CLI:** `vora status --usage` and `vora channels list` show
+  provider quota windows (not per-response costs).
+
+## Cost estimation (when shown)
+
+Costs are estimated from your model pricing config:
+
+```
+models.providers.<provider>.models[].cost
+```
+
+These are **USD per 1M tokens** for `input`, `output`, `cacheRead`, and
+`cacheWrite`. If pricing is missing, Vora shows tokens only. OAuth tokens
+never show dollar cost.
+
+## Cache TTL and pruning impact
+
+Provider prompt caching only applies within the cache TTL window. Vora can
+optionally run **cache-ttl pruning**: it prunes the session once the cache TTL
+has expired, then resets the cache window so subsequent requests can re-use the
+freshly cached context instead of re-caching the full history. This keeps cache
+write costs lower when a session goes idle past the TTL.
+
+Configure it in [Gateway configuration](/gateway/configuration) and see the
+behavior details in [Session pruning](/concepts/session-pruning).
+
+Heartbeat can keep the cache **warm** across idle gaps. If your model cache TTL
+is `1h`, setting the heartbeat interval just under that (e.g., `55m`) can avoid
+re-caching the full prompt, reducing cache write costs.
+
+In multi-agent setups, you can keep one shared model config and tune cache behavior
+per agent with `agents.list[].params.cacheRetention`.
+
+For a full knob-by-knob guide, see [Prompt Caching](/reference/prompt-caching).
+
+For Anthropic API pricing, cache reads are significantly cheaper than input
+tokens, while cache writes are billed at a higher multiplier. See Anthropic’s
+prompt caching pricing for the latest rates and TTL multipliers:
+[https://docs.anthropic.com/docs/build-with-claude/prompt-caching](https://docs.anthropic.com/docs/build-with-claude/prompt-caching)
+
+### Example: keep 1h cache warm with heartbeat
+
+```yaml
+agents:
+  defaults:
+    model:
+      primary: "anthropic/claude-opus-4-6"
+    models:
+      "anthropic/claude-opus-4-6":
+        params:
+          cacheRetention: "long"
+    heartbeat:
+      every: "55m"
+```
+
+### Example: mixed traffic with per-agent cache strategy
+
+```yaml
+agents:
+  defaults:
+    model:
+      primary: "anthropic/claude-opus-4-6"
+    models:
+      "anthropic/claude-opus-4-6":
+        params:
+          cacheRetention: "long" # default baseline for most agents
+  list:
+    - id: "research"
+      default: true
+      heartbeat:
+        every: "55m" # keep long cache warm for deep sessions
+    - id: "alerts"
+      params:
+        cacheRetention: "none" # avoid cache writes for bursty notifications
+```
+
+`agents.list[].params` merges on top of the selected model's `params`, so you can
+override only `cacheRetention` and inherit other model defaults unchanged.
+
+### Example: enable Anthropic 1M context beta header
+
+Anthropic's 1M context window is currently beta-gated. Vora can inject the
+required `anthropic-beta` value when you enable `context1m` on supported Opus
+or Sonnet models.
+
+```yaml
+agents:
+  defaults:
+    models:
+      "anthropic/claude-opus-4-6":
+        params:
+          context1m: true
+```
+
+This maps to Anthropic's `context-1m-2025-08-07` beta header.
+
+This only applies when `context1m: true` is set on that model entry.
+
+Requirement: the credential must be eligible for long-context usage (API key
+billing, or subscription with Extra Usage enabled). If not, Anthropic responds
+with `HTTP 429: rate_limit_error: Extra usage is required for long context requests`.
+
+If you authenticate Anthropic with OAuth/subscription tokens (`sk-ant-oat-*`),
+Vora skips the `context-1m-*` beta header because Anthropic currently
+rejects that combination with HTTP 401.
+
+## Tips for reducing token pressure
+
+- Use `/compact` to summarize long sessions.
+- Trim large tool outputs in your workflows.
+- Lower `agents.defaults.imageMaxDimensionPx` for screenshot-heavy sessions.
+- Keep skill descriptions short (skill list is injected into the prompt).
+- Prefer smaller models for verbose, exploratory work.
+
+See [Skills](/tools/skills) for the exact skill list overhead formula.

package/docs/reference/transcript-hygiene.md

@@ -0,0 +1,151 @@
+---
+summary: "Reference: provider-specific transcript sanitization and repair rules"
+read_when:
+  - You are debugging provider request rejections tied to transcript shape
+  - You are changing transcript sanitization or tool-call repair logic
+  - You are investigating tool-call id mismatches across providers
+title: "Transcript Hygiene"
+---
+
+# Transcript Hygiene (Provider Fixups)
+
+This document describes **provider-specific fixes** applied to transcripts before a run
+(building model context). These are **in-memory** adjustments used to satisfy strict
+provider requirements. These hygiene steps do **not** rewrite the stored JSONL transcript
+on disk; however, a separate session-file repair pass may rewrite malformed JSONL files
+by dropping invalid lines before the session is loaded. When a repair occurs, the original
+file is backed up alongside the session file.
+
+Scope includes:
+
+- Tool call id sanitization
+- Tool call input validation
+- Tool result pairing repair
+- Turn validation / ordering
+- Thought signature cleanup
+- Image payload sanitization
+- User-input provenance tagging (for inter-session routed prompts)
+
+If you need transcript storage details, see:
+
+- [/reference/session-management-compaction](/reference/session-management-compaction)
+
+---
+
+## Where this runs
+
+All transcript hygiene is centralized in the embedded runner:
+
+- Policy selection: `src/agents/transcript-policy.ts`
+- Sanitization/repair application: `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/google.ts`
+
+The policy uses `provider`, `modelApi`, and `modelId` to decide what to apply.
+
+Separate from transcript hygiene, session files are repaired (if needed) before load:
+
+- `repairSessionFileIfNeeded` in `src/agents/session-file-repair.ts`
+- Called from `run/attempt.ts` and `compact.ts` (embedded runner)
+
+---
+
+## Global rule: image sanitization
+
+Image payloads are always sanitized to prevent provider-side rejection due to size
+limits (downscale/recompress oversized base64 images).
+
+This also helps control image-driven token pressure for vision-capable models.
+Lower max dimensions generally reduce token usage; higher dimensions preserve detail.
+
+Implementation:
+
+- `sanitizeSessionMessagesImages` in `src/agents/pi-embedded-helpers/images.ts`
+- `sanitizeContentBlocksImages` in `src/agents/tool-images.ts`
+- Max image side is configurable via `agents.defaults.imageMaxDimensionPx` (default: `1200`).
+
+---
+
+## Global rule: malformed tool calls
+
+Assistant tool-call blocks that are missing both `input` and `arguments` are dropped
+before model context is built. This prevents provider rejections from partially
+persisted tool calls (for example, after a rate limit failure).
+
+Implementation:
+
+- `sanitizeToolCallInputs` in `src/agents/session-transcript-repair.ts`
+- Applied in `sanitizeSessionHistory` in `src/agents/pi-embedded-runner/google.ts`
+
+---
+
+## Global rule: inter-session input provenance
+
+When an agent sends a prompt into another session via `sessions_send` (including
+agent-to-agent reply/announce steps), Vora persists the created user turn with:
+
+- `message.provenance.kind = "inter_session"`
+
+This metadata is written at transcript append time and does not change role
+(`role: "user"` remains for provider compatibility). Transcript readers can use
+this to avoid treating routed internal prompts as end-user-authored instructions.
+
+During context rebuild, Vora also prepends a short `[Inter-session message]`
+marker to those user turns in-memory so the model can distinguish them from
+external end-user instructions.
+
+---
+
+## Provider matrix (current behavior)
+
+**OpenAI / OpenAI Codex**
+
+- Image sanitization only.
+- Drop orphaned reasoning signatures (standalone reasoning items without a following content block) for OpenAI Responses/Codex transcripts.
+- No tool call id sanitization.
+- No tool result pairing repair.
+- No turn validation or reordering.
+- No synthetic tool results.
+- No thought signature stripping.
+
+**Google (Generative AI / Gemini CLI / Antigravity)**
+
+- Tool call id sanitization: strict alphanumeric.
+- Tool result pairing repair and synthetic tool results.
+- Turn validation (Gemini-style turn alternation).
+- Google turn ordering fixup (prepend a tiny user bootstrap if history starts with assistant).
+- Antigravity Claude: normalize thinking signatures; drop unsigned thinking blocks.
+
+**Anthropic / Minimax (Anthropic-compatible)**
+
+- Tool result pairing repair and synthetic tool results.
+- Turn validation (merge consecutive user turns to satisfy strict alternation).
+
+**Mistral (including model-id based detection)**
+
+- Tool call id sanitization: strict9 (alphanumeric length 9).
+
+**OpenRouter Gemini**
+
+- Thought signature cleanup: strip non-base64 `thought_signature` values (keep base64).
+
+**Everything else**
+
+- Image sanitization only.
+
+---
+
+## Historical behavior (pre-2026.1.22)
+
+Before the 2026.1.22 release, Vora applied multiple layers of transcript hygiene:
+
+- A **transcript-sanitize extension** ran on every context build and could:
+  - Repair tool use/result pairing.
+  - Sanitize tool call ids (including a non-strict mode that preserved `_`/`-`).
+- The runner also performed provider-specific sanitization, which duplicated work.
+- Additional mutations occurred outside the provider policy, including:
+  - Stripping `<final>` tags from assistant text before persistence.
+  - Dropping empty assistant error turns.
+  - Trimming assistant content after tool calls.
+
+This complexity caused cross-provider regressions (notably `openai-responses`
+`call_id|fc_id` pairing). The 2026.1.22 cleanup removed the extension, centralized
+logic in the runner, and made OpenAI **no-touch** beyond image sanitization.

package/docs/reference/wizard.md

@@ -0,0 +1,235 @@
+---
+summary: "Full reference for CLI onboarding: every step, flag, and config field"
+read_when:
+  - Looking up a specific onboarding step or flag
+  - Automating onboarding with non-interactive mode
+  - Debugging onboarding behavior
+title: "Onboarding Reference"
+sidebarTitle: "Onboarding Reference"
+---
+
+# Onboarding Reference
+
+This is the full reference for `vora onboard`.
+For a high-level overview, see [Onboarding (CLI)](/start/wizard).
+
+## Flow details (local mode)
+
+<Steps>
+  <Step title="Existing config detection">
+    - If `~/.vora/vora.json` exists, choose **Keep / Modify / Reset**.
+    - Re-running onboarding does **not** wipe anything unless you explicitly choose **Reset**
+      (or pass `--reset`).
+    - CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full`
+      to also remove workspace.
+    - If the config is invalid or contains legacy keys, the wizard stops and asks
+      you to run `vora doctor` before continuing.
+    - Reset uses `trash` (never `rm`) and offers scopes:
+      - Config only
+      - Config + credentials + sessions
+      - Full reset (also removes workspace)
+  </Step>
+  <Step title="Model/Auth">
+    - **Anthropic API key**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
+    - **Anthropic Claude CLI**: on macOS onboarding checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present and switches model selection to `claude-cli/...`.
+    - **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
+    - **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, onboarding can reuse it.
+    - **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
+      - Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
+    - **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then stores it in auth profiles.
+    - **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider.
+    - **OpenCode**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at https://opencode.ai/auth) and lets you pick the Zen or Go catalog.
+    - **Ollama**: prompts for the Ollama base URL, offers **Cloud + Local** or **Local** mode, discovers available models, and auto-pulls the selected local model when needed.
+    - More detail: [Ollama](/providers/ollama)
+    - **API key**: stores the key for you.
+    - **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
+    - More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)
+    - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
+    - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
+    - **MiniMax**: config is auto-written; hosted default is `MiniMax-M2.7`.
+    - More detail: [MiniMax](/providers/minimax)
+    - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
+    - More detail: [Synthetic](/providers/synthetic)
+    - **Moonshot (Kimi K2)**: config is auto-written.
+    - **Kimi Coding**: config is auto-written.
+    - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
+    - **Skip**: no auth configured yet.
+    - Pick a default model from detected options (or enter provider/model manually). For best quality and lower prompt-injection risk, choose the strongest latest-generation model available in your provider stack.
+    - Onboarding runs a model check and warns if the configured model is unknown or missing auth.
+    - API key storage mode defaults to plaintext auth-profile values. Use `--secret-input-mode ref` to store env-backed refs instead (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`).
+    - OAuth credentials live in `~/.vora/credentials/oauth.json`; auth profiles live in `~/.vora/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
+    - More detail: [/concepts/oauth](/concepts/oauth)
+    <Note>
+    Headless/server tip: complete OAuth on a machine with a browser, then copy
+    `~/.vora/credentials/oauth.json` (or `$VORA_STATE_DIR/credentials/oauth.json`) to the
+    gateway host.
+    </Note>
+  </Step>
+  <Step title="Workspace">
+    - Default `~/.vora/workspace` (configurable).
+    - Seeds the workspace files needed for the agent bootstrap ritual.
+    - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
+  </Step>
+  <Step title="Gateway">
+    - Port, bind, auth mode, tailscale exposure.
+    - Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
+    - In token mode, interactive setup offers:
+      - **Generate/store plaintext token** (default)
+      - **Use SecretRef** (opt-in)
+      - Quickstart reuses existing `gateway.auth.token` SecretRefs across `env`, `file`, and `exec` providers for onboarding probe/dashboard bootstrap.
+      - If that SecretRef is configured but cannot be resolved, onboarding fails early with a clear fix message instead of silently degrading runtime auth.
+    - In password mode, interactive setup also supports plaintext or SecretRef storage.
+    - Non-interactive token SecretRef path: `--gateway-token-ref-env <ENV_VAR>`.
+      - Requires a non-empty env var in the onboarding process environment.
+      - Cannot be combined with `--gateway-token`.
+    - Disable auth only if you fully trust every local process.
+    - Non‑loopback binds still require auth.
+  </Step>
+  <Step title="Channels">
+    - [WhatsApp](/channels/whatsapp): optional QR login.
+    - [Telegram](/channels/telegram): bot token.
+    - [Discord](/channels/discord): bot token.
+    - [Google Chat](/channels/googlechat): service account JSON + webhook audience.
+    - [Mattermost](/channels/mattermost) (plugin): bot token + base URL.
+    - [Signal](/channels/signal): optional `signal-cli` install + account config.
+    - [BlueBubbles](/channels/bluebubbles): **recommended for iMessage**; server URL + password + webhook.
+    - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access.
+    - DM security: default is pairing. First DM sends a code; approve via `vora pairing approve <channel> <code>` or use allowlists.
+  </Step>
+  <Step title="Web search">
+    - Pick a provider: Perplexity, Brave, Gemini, Grok, or Kimi (or skip).
+    - Paste your API key (QuickStart auto-detects keys from env vars or existing config).
+    - Skip with `--skip-search`.
+    - Configure later: `vora configure --section web`.
+  </Step>
+  <Step title="Daemon install">
+    - macOS: LaunchAgent
+      - Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
+    - Linux (and Windows via WSL2): systemd user unit
+      - Onboarding attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
+      - May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
+    - **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
+    - If token auth requires a token and `gateway.auth.token` is SecretRef-managed, daemon install validates it but does not persist resolved plaintext token values into supervisor service environment metadata.
+    - If token auth requires a token and the configured token SecretRef is unresolved, daemon install is blocked with actionable guidance.
+    - If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, daemon install is blocked until mode is set explicitly.
+  </Step>
+  <Step title="Health check">
+    - Starts the Gateway (if needed) and runs `vora health`.
+    - Tip: `vora status --deep` adds gateway health probes to status output (requires a reachable gateway).
+  </Step>
+  <Step title="Skills (recommended)">
+    - Reads the available skills and checks requirements.
+    - Lets you choose a node manager: **npm / pnpm** (bun not recommended).
+    - Installs optional dependencies (some use Homebrew on macOS).
+  </Step>
+  <Step title="Finish">
+    - Summary + next steps, including iOS/Android/macOS apps for extra features.
+  </Step>
+</Steps>
+
+<Note>
+If no GUI is detected, onboarding prints SSH port-forward instructions for the Control UI instead of opening a browser.
+If the Control UI assets are missing, onboarding attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).
+</Note>
+
+## Non-interactive mode
+
+Use `--non-interactive` to automate or script onboarding:
+
+```bash
+vora onboard --non-interactive \
+  --mode local \
+  --auth-choice apiKey \
+  --anthropic-api-key "$ANTHROPIC_API_KEY" \
+  --gateway-port 18789 \
+  --gateway-bind loopback \
+  --install-daemon \
+  --daemon-runtime node \
+  --skip-skills
+```
+
+Add `--json` for a machine‑readable summary.
+
+Gateway token SecretRef in non-interactive mode:
+
+```bash
+export VORA_GATEWAY_TOKEN="your-token"
+vora onboard --non-interactive \
+  --mode local \
+  --auth-choice skip \
+  --gateway-auth token \
+  --gateway-token-ref-env VORA_GATEWAY_TOKEN
+```
+
+`--gateway-token` and `--gateway-token-ref-env` are mutually exclusive.
+
+<Note>
+`--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
+</Note>
+
+Provider-specific command examples live in [CLI Automation](/start/wizard-cli-automation#provider-specific-examples).
+Use this reference page for flag semantics and step ordering.
+
+### Add agent (non-interactive)
+
+```bash
+vora agents add work \
+  --workspace ~/.vora/workspace-work \
+  --model openai/gpt-5.2 \
+  --bind whatsapp:biz \
+  --non-interactive \
+  --json
+```
+
+## Gateway wizard RPC
+
+The Gateway exposes the onboarding flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
+Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.
+
+## Signal setup (signal-cli)
+
+Onboarding can install `signal-cli` from GitHub releases:
+
+- Downloads the appropriate release asset.
+- Stores it under `~/.vora/tools/signal-cli/<version>/`.
+- Writes `channels.signal.cliPath` to your config.
+
+Notes:
+
+- JVM builds require **Java 21**.
+- Native builds are used when available.
+- Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.
+
+## What the wizard writes
+
+Typical fields in `~/.vora/vora.json`:
+
+- `agents.defaults.workspace`
+- `agents.defaults.model` / `models.providers` (if Minimax chosen)
+- `tools.profile` (local onboarding defaults to `"coding"` when unset; existing explicit values are preserved)
+- `gateway.*` (mode, bind, auth, tailscale)
+- `session.dmScope` (behavior details: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals))
+- `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
+- `skills.install.nodeManager`
+- `wizard.lastRunAt`
+- `wizard.lastRunVersion`
+- `wizard.lastRunCommit`
+- `wizard.lastRunCommand`
+- `wizard.lastRunMode`
+
+`vora agents add` writes `agents.list[]` and optional `bindings`.
+
+WhatsApp credentials go under `~/.vora/credentials/whatsapp/<accountId>/`.
+Sessions are stored under `~/.vora/agents/<agentId>/sessions/`.
+
+Some channels are delivered as plugins. When you pick one during setup, onboarding
+will prompt to install it (npm or a local path) before it can be configured.
+
+## Related docs
+
+- Onboarding overview: [Onboarding (CLI)](/start/wizard)
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Config reference: [Gateway configuration](/gateway/configuration)
+- Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy)
+- Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config)

package/docs/security/CONTRIBUTING-THREAT-MODEL.md

@@ -0,0 +1,98 @@
+---
+title: "Contributing to the Threat Model"
+summary: "How to contribute to the Vora threat model"
+read_when:
+  - You want to contribute security findings or threat scenarios
+  - Reviewing or updating the threat model
+---
+
+# Contributing to the Vora Threat Model
+
+Thanks for helping make Vora more secure. This threat model is a living document and we welcome contributions from anyone - you don't need to be a security expert.
+
+## Ways to Contribute
+
+### Add a Threat
+
+Spotted an attack vector or risk we haven't covered? Open an issue on [vora/trust](https://github.com/vora/trust/issues) and describe it in your own words. You don't need to know any frameworks or fill in every field - just describe the scenario.
+
+**Helpful to include (but not required):**
+
+- The attack scenario and how it could be exploited
+- Which parts of Vora are affected (CLI, gateway, channels, ClawHub, MCP servers, etc.)
+- How severe you think it is (low / medium / high / critical)
+- Any links to related research, CVEs, or real-world examples
+
+We'll handle the ATLAS mapping, threat IDs, and risk assessment during review. If you want to include those details, great - but it's not expected.
+
+> **This is for adding to the threat model, not reporting live vulnerabilities.** If you've found an exploitable vulnerability, see our [Trust page](https://trust.vora.ai) for responsible disclosure instructions.
+
+### Suggest a Mitigation
+
+Have an idea for how to address an existing threat? Open an issue or PR referencing the threat. Useful mitigations are specific and actionable - for example, "per-sender rate limiting of 10 messages/minute at the gateway" is better than "implement rate limiting."
+
+### Propose an Attack Chain
+
+Attack chains show how multiple threats combine into a realistic attack scenario. If you see a dangerous combination, describe the steps and how an attacker would chain them together. A short narrative of how the attack unfolds in practice is more valuable than a formal template.
+
+### Fix or Improve Existing Content
+
+Typos, clarifications, outdated info, better examples - PRs welcome, no issue needed.
+
+## What We Use
+
+### MITRE ATLAS
+
+This threat model is built on [MITRE ATLAS](https://atlas.mitre.org/) (Adversarial Threat Landscape for AI Systems), a framework designed specifically for AI/ML threats like prompt injection, tool misuse, and agent exploitation. You don't need to know ATLAS to contribute - we map submissions to the framework during review.
+
+### Threat IDs
+
+Each threat gets an ID like `T-EXEC-003`. The categories are:
+
+| Code    | Category                                   |
+| ------- | ------------------------------------------ |
+| RECON   | Reconnaissance - information gathering     |
+| ACCESS  | Initial access - gaining entry             |
+| EXEC    | Execution - running malicious actions      |
+| PERSIST | Persistence - maintaining access           |
+| EVADE   | Defense evasion - avoiding detection       |
+| DISC    | Discovery - learning about the environment |
+| EXFIL   | Exfiltration - stealing data               |
+| IMPACT  | Impact - damage or disruption              |
+
+IDs are assigned by maintainers during review. You don't need to pick one.
+
+### Risk Levels
+
+| Level        | Meaning                                                           |
+| ------------ | ----------------------------------------------------------------- |
+| **Critical** | Full system compromise, or high likelihood + critical impact      |
+| **High**     | Significant damage likely, or medium likelihood + critical impact |
+| **Medium**   | Moderate risk, or low likelihood + high impact                    |
+| **Low**      | Unlikely and limited impact                                       |
+
+If you're unsure about the risk level, just describe the impact and we'll assess it.
+
+## Review Process
+
+1. **Triage** - We review new submissions within 48 hours
+2. **Assessment** - We verify feasibility, assign ATLAS mapping and threat ID, validate risk level
+3. **Documentation** - We ensure everything is formatted and complete
+4. **Merge** - Added to the threat model and visualization
+
+## Resources
+
+- [ATLAS Website](https://atlas.mitre.org/)
+- [ATLAS Techniques](https://atlas.mitre.org/techniques/)
+- [ATLAS Case Studies](https://atlas.mitre.org/studies/)
+- [Vora Threat Model](/security/THREAT-MODEL-ATLAS)
+
+## Contact
+
+- **Security vulnerabilities:** See our [Trust page](https://trust.vora.ai) for reporting instructions
+- **Threat model questions:** Open an issue on [vora/trust](https://github.com/vora/trust/issues)
+- **General chat:** Discord #security channel
+
+## Recognition
+
+Contributors to the threat model are recognized in the threat model acknowledgments, release notes, and the Vora security hall of fame for significant contributions.