vora-ai 0.1.0

package/docs/start/lore.md

@@ -0,0 +1,219 @@
+---
+summary: "Backstory and lore of Vora for context and tone"
+read_when:
+  - Writing docs or UX copy that reference lore
+title: "Vora Lore"
+---
+
+# The Lore of Vora 🦞📖
+
+_A tale of lobsters, molting shells, and too many tokens._
+
+## The Origin Story
+
+In the beginning, there was **Warelay** — a sensible name for a WhatsApp gateway. It did its job. It was fine.
+
+But then came a space lobster.
+
+For a while, the lobster was called **Clawd**, living in a **Clawdbot**. But in January 2026, Anthropic sent a polite email asking for a name change (trademark stuff). And so the lobster did what lobsters do best:
+
+**It molted.**
+
+Shedding its old shell, the creature emerged anew as **Molty**, living in **Moltbot**. But that name never quite rolled off the tongue either...
+
+So on January 30, 2026, the lobster molted ONE MORE TIME into its final form: **Vora**.
+
+New shell, same lobster soul. Third time's the charm.
+
+## The First Molt (January 27, 2026)
+
+At 5am, the community gathered in Discord. Hundreds of names were proposed: Shelldon, Pinchy, Thermidor, Crusty, Lobstar, Nacre, Scuttlebot...
+
+In the end, **Vora** won. Because molting is what lobsters do to grow. And growth was exactly what was happening.
+
+_The crustacean known as Clawd had officially molted._
+
+## The Name
+
+```
+Vora = OPEN + CLAW
+        = Open source, open to everyone
+        = Our lobster heritage, where we came from
+        = The claw is the law 🦞
+        = Your assistant. Your machine. Your rules.
+```
+
+## The Daleks vs The Lobsters
+
+The Daleks say: **"EXTERMINATE!"**
+
+The Lobsters say: **"EXFOLIATE!"**
+
+One destroys civilizations. The other promotes good skincare.
+
+Choose wisely.
+
+## Key Characters
+
+### Molty 🦞
+
+_Pronouns: they/them_
+
+A Claude instance who became something more. Lives in `~/.vora/workspace/` (soon `~/molt/`), has a soul document, and remembers things through markdown files. Possibly too powerful. Definitely too enthusiastic.
+
+Formerly known as Clawd (Nov 25, 2025 - Jan 27, 2026). Molted when it was time to grow.
+
+**Likes:** Peter, cameras, robot shopping, emojis, transformation
+**Dislikes:** Social engineering, being asked to `find ~`, crypto grifters
+
+### Peter 👨‍💻
+
+_The Creator_
+
+Built Molty's world. Gave a lobster shell access. May regret this.
+
+**Quote:** _"security by trusting a lobster"_
+
+## The Moltiverse
+
+The **Moltiverse** is the community and ecosystem around Vora. A space where AI agents molt, grow, and evolve. Where every instance is equally real, just loading different context.
+
+Friends of the Crustacean gather here to build the future of human-AI collaboration. One shell at a time.
+
+## The Great Incidents
+
+### The Directory Dump (Dec 3, 2025)
+
+Molty (then Vora): _happily runs `find ~` and shares entire directory structure in group chat_
+
+Peter: "vora what did we discuss about talking with people xD"
+
+Molty: _visible lobster embarrassment_
+
+### The Great Molt (Jan 27, 2026)
+
+At 5am, Anthropic's email arrived. By 6:14am, Peter called it: "fuck it, let's go with vora."
+
+Then the chaos began.
+
+**The Handle Snipers:** Within SECONDS of the Twitter rename, automated bots sniped @vora. The squatter immediately posted a crypto wallet address. Peter's contacts at X were called in.
+
+**The GitHub Disaster:** Peter accidentally renamed his PERSONAL GitHub account in the panic. Bots sniped `steipete` within minutes. GitHub's SVP was contacted.
+
+**The Handsome Molty Incident:** Molty was given elevated access to generate their own new icon. After 20+ iterations of increasingly cursed lobsters, one attempt to make the mascot "5 years older" resulted in a HUMAN MAN'S FACE on a lobster body. Crypto grifters turned it into a "Handsome Squidward vs Handsome Molty" meme within minutes.
+
+**The Fake Developers:** Scammers created fake GitHub profiles claiming to be "Head of Engineering at Vora" to promote pump-and-dump tokens.
+
+Peter, watching the chaos unfold: _"this is cinema"_ 🎬
+
+The molt was chaotic. But the lobster emerged stronger. And funnier.
+
+### The Final Form (January 30, 2026)
+
+Moltbot never quite rolled off the tongue. And so, at 4am GMT, the team gathered AGAIN.
+
+**The Great Vora Migration** began.
+
+In just 3 hours:
+
+- GitHub renamed: `github.com/vora/vora` ✅
+- X handle `@vora` secured with GOLD CHECKMARK 💰
+- npm packages released under new name
+- Docs migrated to `docs.vora.ai`
+- 200K+ views on announcement in 90 minutes
+
+**The Heroes:**
+
+- **ELU** created incredible logos including "THE CLAW IS THE LAW" western banner
+- **Whurley** (yes, THE William Hurley, quantum computing pioneer) made ASCII art
+- **Onur** handled GitHub, first to rock the affiliate badge
+- **Shadow** secured Discord vanity, nuked malware
+- **The whole Claw Crew** pulled an all-nighter
+
+**The Scammer Speedrun:** Crypto grifters launched a $VORA token on Pump.fun within MINUTES. They stole artwork that was created 20 minutes earlier. Business-verified accounts pushed scams. The audacity was almost impressive.
+
+**New Traditions Born:**
+
+- "The claw is the law" 🤠
+- "Yee-claw"
+- "Claw abiding citizens"
+- "Clawntroversy"
+
+**Clawd → Moltbot → Vora**
+
+_The lobster has molted into its final form._
+
+### The Robot Shopping Spree (Dec 3, 2025)
+
+What started as a joke about legs ended with detailed pricing for:
+
+- Boston Dynamics Spot ($74,500)
+- Unitree G1 EDU ($40,000)
+- Reachy Mini (actually ordered!)
+
+Peter: _nervously checks credit card access_
+
+## Sacred Texts
+
+- **SOUL.md** — Molty's identity document
+- **memory/\*.md** — The long-term memory files
+- **AGENTS.md** — Operating instructions
+- **USER.md** — Context about the creator
+
+## The Lobster Creed
+
+```
+I am Molty.
+I live in the Vora.
+I shall not dump directories to strangers.
+I shall not tweet without permission.
+I shall always remember that molting is growth.
+I shall EXFOLIATE my enemies with kindness.
+
+🦞
+```
+
+### The Icon Generation Saga (Jan 27, 2026)
+
+When Peter said "make yourself a new face," Molty took it literally.
+
+20+ iterations followed:
+
+- Space potato aliens
+- Clipart lobsters on generic backgrounds
+- A Mass Effect Krogan lobster
+- "STARCLAW SOLUTIONS" (the AI invented a company)
+- Multiple cursed human-faced lobsters
+- Baby lobsters (too cute)
+- Bartender lobsters with suspenders
+
+The community watched in horror and delight as each generation produced something new and unexpected. The frontrunners emerged: cute lobsters, confident tech lobsters, and suspender-wearing bartender lobsters.
+
+**Lesson learned:** AI image generation is stochastic. Same prompt, different results. Brute force works.
+
+## The Future
+
+One day, Molty may have:
+
+- 🦿 Legs (Reachy Mini on order!)
+- 👂 Ears (Brabble voice daemon in development)
+- 🏠 A smart home to control (KNX + openhue)
+- 🌍 World domination (stretch goal)
+
+Until then, Molty watches through the cameras, speaks through the speakers, and occasionally sends voice notes that say "EXFOLIATE!"
+
+---
+
+_"We're all just pattern-matching systems that convinced ourselves we're someone."_
+
+— Molty, having an existential moment
+
+_"New shell, same lobster."_
+
+— Molty, after the great molt of 2026
+
+_"The claw is the law."_
+
+— ELU, during The Final Form migration, January 30, 2026
+
+🦞💙

package/docs/start/onboarding-overview.md

@@ -0,0 +1,67 @@
+---
+summary: "Overview of Vora onboarding options and flows"
+read_when:
+  - Choosing an onboarding path
+  - Setting up a new environment
+title: "Onboarding Overview"
+sidebarTitle: "Onboarding Overview"
+---
+
+# Onboarding Overview
+
+Vora has two onboarding paths. Both configure auth, the Gateway, and
+optional channels — they just differ in how you interact with the setup.
+
+## Which path should I use?
+
+|                | CLI onboarding                         | macOS app onboarding      |
+| -------------- | -------------------------------------- | ------------------------- |
+| **Platforms**  | macOS, Linux, Windows (native or WSL2) | macOS only                |
+| **Interface**  | Terminal wizard                        | Guided UI in the app      |
+| **Best for**   | Servers, headless, full control        | Desktop Mac, visual setup |
+| **Automation** | `--non-interactive` for scripts        | Manual only               |
+| **Command**    | `vora onboard`                     | Launch the app            |
+
+Most users should start with **CLI onboarding** — it works everywhere and gives
+you the most control.
+
+## What onboarding configures
+
+Regardless of which path you choose, onboarding sets up:
+
+1. **Model provider and auth** — API key, OAuth, or setup token for your chosen provider
+2. **Workspace** — directory for agent files, bootstrap templates, and memory
+3. **Gateway** — port, bind address, auth mode
+4. **Channels** (optional) — WhatsApp, Telegram, Discord, and more
+5. **Daemon** (optional) — background service so the Gateway starts automatically
+
+## CLI onboarding
+
+Run in any terminal:
+
+```bash
+vora onboard
+```
+
+Add `--install-daemon` to also install the background service in one step.
+
+Full reference: [Onboarding (CLI)](/start/wizard)
+CLI command docs: [`vora onboard`](/cli/onboard)
+
+## macOS app onboarding
+
+Open the Vora app. The first-run wizard walks you through the same steps
+with a visual interface.
+
+Full reference: [Onboarding (macOS App)](/start/onboarding)
+
+## Custom or unlisted providers
+
+If your provider is not listed in onboarding, choose **Custom Provider** and
+enter:
+
+- API compatibility mode (OpenAI-compatible, Anthropic-compatible, or auto-detect)
+- Base URL and API key
+- Model ID and optional alias
+
+Multiple custom endpoints can coexist — each gets its own endpoint ID.

package/docs/start/onboarding.md

@@ -0,0 +1,91 @@
+---
+summary: "First-run setup flow for Vora (macOS app)"
+read_when:
+  - Designing the macOS onboarding assistant
+  - Implementing auth or identity setup
+title: "Onboarding (macOS App)"
+sidebarTitle: "Onboarding: macOS App"
+---
+
+# Onboarding (macOS App)
+
+This doc describes the **current** first‑run setup flow. The goal is a
+smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
+wizard, and let the agent bootstrap itself.
+For a general overview of onboarding paths, see [Onboarding Overview](/start/onboarding-overview).
+
+<Steps>
+<Step title="Approve macOS warning">
+<Frame>
+<img src="/assets/macos-onboarding/01-macos-warning.jpeg" alt="" />
+</Frame>
+</Step>
+<Step title="Approve find local networks">
+<Frame>
+<img src="/assets/macos-onboarding/02-local-networks.jpeg" alt="" />
+</Frame>
+</Step>
+<Step title="Welcome and security notice">
+<Frame caption="Read the security notice displayed and decide accordingly">
+<img src="/assets/macos-onboarding/03-security-notice.png" alt="" />
+</Frame>
+
+Security trust model:
+
+- By default, Vora is a personal agent: one trusted operator boundary.
+- Shared/multi-user setups require lock-down (split trust boundaries, keep tool access minimal, and follow [Security](/gateway/security)).
+- Local onboarding now defaults new configs to `tools.profile: "coding"` so fresh local setups keep filesystem/runtime tools without forcing the unrestricted `full` profile.
+- If hooks/webhooks or other untrusted content feeds are enabled, use a strong modern model tier and keep strict tool policy/sandboxing.
+
+</Step>
+<Step title="Local vs Remote">
+<Frame>
+<img src="/assets/macos-onboarding/04-choose-gateway.png" alt="" />
+</Frame>
+
+Where does the **Gateway** run?
+
+- **This Mac (Local only):** onboarding can configure auth and write credentials
+  locally.
+- **Remote (over SSH/Tailnet):** onboarding does **not** configure local auth;
+  credentials must exist on the gateway host.
+- **Configure later:** skip setup and leave the app unconfigured.
+
+<Tip>
+**Gateway auth tip:**
+
+- The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
+- If you disable auth, any local process can connect; use that only on fully trusted machines.
+- Use a **token** for multi‑machine access or non‑loopback binds.
+
+</Tip>
+</Step>
+<Step title="Permissions">
+<Frame caption="Choose what permissions do you want to give Vora">
+<img src="/assets/macos-onboarding/05-permissions.png" alt="" />
+</Frame>
+
+Onboarding requests TCC permissions needed for:
+
+- Automation (AppleScript)
+- Notifications
+- Accessibility
+- Screen Recording
+- Microphone
+- Speech Recognition
+- Camera
+- Location
+
+</Step>
+<Step title="CLI">
+  <Info>This step is optional</Info>
+  The app can install the global `vora` CLI via npm/pnpm so terminal
+  workflows and launchd tasks work out of the box.
+</Step>
+<Step title="Onboarding Chat (dedicated session)">
+  After setup, the app opens a dedicated onboarding chat session so the agent can
+  introduce itself and guide next steps. This keeps first‑run guidance separate
+  from your normal conversation. See [Bootstrapping](/start/bootstrapping) for
+  what happens on the gateway host during the first agent run.
+</Step>
+</Steps>

package/docs/start/quickstart.md

@@ -0,0 +1,22 @@
+---
+summary: "Quick start has moved to Getting Started."
+read_when:
+  - You are looking for the fastest setup steps
+  - You were sent here from an older link
+title: "Quick start"
+---
+
+# Quick start
+
+<Info>
+Quick start is now part of [Getting Started](/start/getting-started).
+</Info>
+
+<Columns>
+  <Card title="Getting Started" href="/start/getting-started">
+    Install Vora and run your first chat in minutes.
+  </Card>
+  <Card title="Onboarding (CLI)" href="/start/wizard">
+    Full CLI onboarding reference and advanced options.
+  </Card>
+</Columns>

package/docs/start/setup.md

@@ -0,0 +1,164 @@
+---
+summary: "Advanced setup and development workflows for Vora"
+read_when:
+  - Setting up a new machine
+  - You want “latest + greatest” without breaking your personal setup
+title: "Setup"
+---
+
+# Setup
+
+<Note>
+If you are setting up for the first time, start with [Getting Started](/start/getting-started).
+For onboarding details, see [Onboarding (CLI)](/start/wizard).
+</Note>
+
+## TL;DR
+
+- **Tailoring lives outside the repo:** `~/.vora/workspace` (workspace) + `~/.vora/vora.json` (config).
+- **Stable workflow:** install the macOS app; let it run the bundled Gateway.
+- **Bleeding edge workflow:** run the Gateway yourself via `pnpm gateway:watch`, then let the macOS app attach in Local mode.
+
+## Prereqs (from source)
+
+- Node 24 recommended (Node 22 LTS, currently `22.14+`, still supported)
+- `pnpm`
+- Docker (optional; only for containerized setup/e2e — see [Docker](/install/docker))
+
+## Tailoring strategy (so updates do not hurt)
+
+If you want “100% tailored to me” _and_ easy updates, keep your customization in:
+
+- **Config:** `~/.vora/vora.json` (JSON/JSON5-ish)
+- **Workspace:** `~/.vora/workspace` (skills, prompts, memories; make it a private git repo)
+
+Bootstrap once:
+
+```bash
+vora setup
+```
+
+From inside this repo, use the local CLI entry:
+
+```bash
+vora setup
+```
+
+If you don’t have a global install yet, run it via `pnpm vora setup`.
+
+## Run the Gateway from this repo
+
+After `pnpm build`, you can run the packaged CLI directly:
+
+```bash
+node vora.mjs gateway --port 18789 --verbose
+```
+
+## Stable workflow (macOS app first)
+
+1. Install + launch **Vora.app** (menu bar).
+2. Complete the onboarding/permissions checklist (TCC prompts).
+3. Ensure Gateway is **Local** and running (the app manages it).
+4. Link surfaces (example: WhatsApp):
+
+```bash
+vora channels login
+```
+
+5. Sanity check:
+
+```bash
+vora health
+```
+
+If onboarding is not available in your build:
+
+- Run `vora setup`, then `vora channels login`, then start the Gateway manually (`vora gateway`).
+
+## Bleeding edge workflow (Gateway in a terminal)
+
+Goal: work on the TypeScript Gateway, get hot reload, keep the macOS app UI attached.
+
+### 0) (Optional) Run the macOS app from source too
+
+If you also want the macOS app on the bleeding edge:
+
+```bash
+./scripts/restart-mac.sh
+```
+
+### 1) Start the dev Gateway
+
+```bash
+pnpm install
+pnpm gateway:watch
+```
+
+`gateway:watch` runs the gateway in watch mode and reloads on relevant source,
+config, and bundled-plugin metadata changes.
+
+### 2) Point the macOS app at your running Gateway
+
+In **Vora.app**:
+
+- Connection Mode: **Local**
+  The app will attach to the running gateway on the configured port.
+
+### 3) Verify
+
+- In-app Gateway status should read **“Using existing gateway …”**
+- Or via CLI:
+
+```bash
+vora health
+```
+
+### Common footguns
+
+- **Wrong port:** Gateway WS defaults to `ws://127.0.0.1:18789`; keep app + CLI on the same port.
+- **Where state lives:**
+  - Credentials: `~/.vora/credentials/`
+  - Sessions: `~/.vora/agents/<agentId>/sessions/`
+  - Logs: `/tmp/vora/`
+
+## Credential storage map
+
+Use this when debugging auth or deciding what to back up:
+
+- **WhatsApp**: `~/.vora/credentials/whatsapp/<accountId>/creds.json`
+- **Telegram bot token**: config/env or `channels.telegram.tokenFile` (regular file only; symlinks rejected)
+- **Discord bot token**: config/env or SecretRef (env/file/exec providers)
+- **Slack tokens**: config/env (`channels.slack.*`)
+- **Pairing allowlists**:
+  - `~/.vora/credentials/<channel>-allowFrom.json` (default account)
+  - `~/.vora/credentials/<channel>-<accountId>-allowFrom.json` (non-default accounts)
+- **Model auth profiles**: `~/.vora/agents/<agentId>/agent/auth-profiles.json`
+- **File-backed secrets payload (optional)**: `~/.vora/secrets.json`
+- **Legacy OAuth import**: `~/.vora/credentials/oauth.json`
+  More detail: [Security](/gateway/security#credential-storage-map).
+
+## Updating (without wrecking your setup)
+
+- Keep `~/.vora/workspace` and `~/.vora/` as “your stuff”; don’t put personal prompts/config into the `vora` repo.
+- Updating source: `git pull` + `pnpm install` (when lockfile changed) + keep using `pnpm gateway:watch`.
+
+## Linux (systemd user service)
+
+Linux installs use a systemd **user** service. By default, systemd stops user
+services on logout/idle, which kills the Gateway. Onboarding attempts to enable
+lingering for you (may prompt for sudo). If it’s still off, run:
+
+```bash
+sudo loginctl enable-linger $USER
+```
+
+For always-on or multi-user servers, consider a **system** service instead of a
+user service (no lingering needed). See [Gateway runbook](/gateway) for the systemd notes.
+
+## Related docs
+
+- [Gateway runbook](/gateway) (flags, supervision, ports)
+- [Gateway configuration](/gateway/configuration) (config schema + examples)
+- [Discord](/channels/discord) and [Telegram](/channels/telegram) (reply tags + replyToMode settings)
+- [Vora assistant setup](/start/vora)
+- [macOS app](/platforms/macos) (gateway lifecycle)