nodmix 2026.5.25

package/docs/start/getting-started.md

@@ -0,0 +1,152 @@
+---
+summary: "Get Nodmix installed and run your first chat in minutes."
+read_when:
+  - First time setup from zero
+  - You want the fastest path to a working chat
+title: "Getting started"
+---
+
+Install Nodmix, run onboarding, and chat with your AI assistant — all in
+about 5 minutes. By the end you will have a running Gateway, configured auth,
+and a working chat session.
+
+## What you need
+
+- **Node.js** — Node 24 recommended (Node 22.19+ also supported)
+- **An API key** from a model provider (Anthropic, OpenAI, Google, etc.) — onboarding will prompt you
+
+<Tip>
+Check your Node version with `node --version`.
+**Windows users:** both native Windows and WSL2 are supported. WSL2 is more
+stable and recommended for the full experience. See [Windows](/platforms/windows).
+Need to install Node? See [Node setup](/install/node).
+</Tip>
+
+## Quick setup
+
+<Steps>
+  <Step title="Install Nodmix">
+    <Tabs>
+      <Tab title="macOS / Linux">
+        ```bash
+        curl -fsSL https://nodmix.ai/install.sh | bash
+        ```
+        <img
+  src="/assets/install-script.svg"
+  alt="Install Script Process"
+  className="rounded-lg"
+/>
+      </Tab>
+      <Tab title="Windows (PowerShell)">
+        ```powershell
+        iwr -useb https://nodmix.ai/install.ps1 | iex
+        ```
+      </Tab>
+    </Tabs>
+
+    <Note>
+    Other install methods (Docker, Nix, npm): [Install](/install).
+    </Note>
+
+  </Step>
+  <Step title="Run onboarding">
+    ```bash
+    nodmix onboard --install-daemon
+    ```
+
+    The wizard walks you through choosing a model provider, setting an API key,
+    and configuring the Gateway. It takes about 2 minutes.
+
+    See [Onboarding (CLI)](/start/wizard) for the full reference.
+
+  </Step>
+  <Step title="Verify the Gateway is running">
+    ```bash
+    nodmix gateway status
+    ```
+
+    You should see the Gateway listening on port 18789.
+
+  </Step>
+  <Step title="Open the dashboard">
+    ```bash
+    nodmix dashboard
+    ```
+
+    This opens the Control UI in your browser. If it loads, everything is working.
+
+  </Step>
+  <Step title="Send your first message">
+    Type a message in the Control UI chat and you should get an AI reply.
+
+    Want to chat from your phone instead? The fastest channel to set up is
+    [Telegram](/channels/telegram) (just a bot token). See [Channels](/channels)
+    for all options.
+
+  </Step>
+</Steps>
+
+<Accordion title="Advanced: mount a custom Control UI build">
+  If you maintain a localized or customized dashboard build, point
+  `gateway.controlUi.root` to a directory that contains your built static
+  assets and `index.html`.
+
+```bash
+mkdir -p "$HOME/.nodmix/control-ui-custom"
+# Copy your built static files into that directory.
+```
+
+Then set:
+
+```json
+{
+  "gateway": {
+    "controlUi": {
+      "enabled": true,
+      "root": "$HOME/.nodmix/control-ui-custom"
+    }
+  }
+}
+```
+
+Restart the gateway and reopen the dashboard:
+
+```bash
+nodmix gateway restart
+nodmix dashboard
+```
+
+</Accordion>
+
+## What to do next
+
+<Columns>
+  <Card title="Connect a channel" href="/channels" icon="message-square">
+    Discord, Feishu, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo, and more.
+  </Card>
+  <Card title="Pairing and safety" href="/channels/pairing" icon="shield">
+    Control who can message your agent.
+  </Card>
+  <Card title="Configure the Gateway" href="/gateway/configuration" icon="settings">
+    Models, tools, sandbox, and advanced settings.
+  </Card>
+  <Card title="Browse tools" href="/tools" icon="wrench">
+    Browser, exec, web search, skills, and plugins.
+  </Card>
+</Columns>
+
+<Accordion title="Advanced: environment variables">
+  If you run Nodmix as a service account or want custom paths:
+
+- `NODMIX_HOME` — home directory for internal path resolution
+- `NODMIX_STATE_DIR` — override the state directory
+- `NODMIX_CONFIG_PATH` — override the config file path
+
+Full reference: [Environment variables](/help/environment).
+</Accordion>
+
+## Related
+
+- [Install overview](/install)
+- [Channels overview](/channels)
+- [Setup](/start/setup)

package/docs/start/hubs.md

@@ -0,0 +1,201 @@
+---
+summary: "Hubs that link to every Nodmix doc"
+read_when:
+  - You want a complete map of the documentation
+title: "Docs hubs"
+---
+
+<Note>
+If you are new to Nodmix, start with [Getting Started](/start/getting-started).
+</Note>
+
+Use these hubs to discover every page, including deep dives and reference docs that don't appear in the left nav.
+
+## Start here
+
+- [Index](/)
+- [Getting Started](/start/getting-started)
+- [Onboarding](/start/onboarding)
+- [Onboarding (CLI)](/start/wizard)
+- [Setup](/start/setup)
+- [Dashboard (local Gateway)](http://127.0.0.1:18789/)
+- [Help](/help)
+- [Docs directory](/start/docs-directory)
+- [Configuration](/gateway/configuration)
+- [Configuration examples](/gateway/configuration-examples)
+- [Nodmix assistant](/start/nodmix)
+- [Showcase](/start/showcase)
+- [Lore](/start/lore)
+
+## Installation + updates
+
+- [Docker](/install/docker)
+- [Nix](/install/nix)
+- [Updating / rollback](/install/updating)
+- [Bun workflow (experimental)](/install/bun)
+
+## Core concepts
+
+- [Architecture](/concepts/architecture)
+- [Features](/concepts/features)
+- [Network hub](/network)
+- [Agent runtime](/concepts/agent)
+- [Agent workspace](/concepts/agent-workspace)
+- [Memory](/concepts/memory)
+- [Agent loop](/concepts/agent-loop)
+- [Streaming + chunking](/concepts/streaming)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Compaction](/concepts/compaction)
+- [Sessions](/concepts/session)
+- [Session pruning](/concepts/session-pruning)
+- [Session tools](/concepts/session-tool)
+- [Queue](/concepts/queue)
+- [Slash commands](/tools/slash-commands)
+- [RPC adapters](/reference/rpc)
+- [TypeBox schemas](/concepts/typebox)
+- [Timezone handling](/concepts/timezone)
+- [Presence](/concepts/presence)
+- [Discovery + transports](/gateway/discovery)
+- [Bonjour](/gateway/bonjour)
+- [Channel routing](/channels/channel-routing)
+- [Groups](/channels/groups)
+- [Group messages](/channels/group-messages)
+- [Model failover](/concepts/model-failover)
+- [OAuth](/concepts/oauth)
+
+## Providers + ingress
+
+- [Chat channels hub](/channels)
+- [Model providers hub](/providers/models)
+- [WhatsApp](/channels/whatsapp)
+- [Telegram](/channels/telegram)
+- [Slack](/channels/slack)
+- [Discord](/channels/discord)
+- [Mattermost](/channels/mattermost)
+- [Signal](/channels/signal)
+- [QQ Bot](/channels/qqbot)
+- [iMessage](/channels/imessage)
+- [Location parsing](/channels/location)
+- [WebChat](/web/webchat)
+- [Webhooks](/automation/cron-jobs#webhooks)
+- [Gmail Pub/Sub](/automation/cron-jobs#gmail-pubsub-integration)
+
+## Gateway + operations
+
+- [Gateway runbook](/gateway)
+- [Network model](/network#core-model)
+- [Gateway pairing](/gateway/pairing)
+- [Gateway lock](/gateway/gateway-lock)
+- [Background process](/gateway/background-process)
+- [Health](/gateway/health)
+- [Heartbeat](/gateway/heartbeat)
+- [Doctor](/gateway/doctor)
+- [Logging](/gateway/logging)
+- [Sandboxing](/gateway/sandboxing)
+- [Dashboard](/web/dashboard)
+- [Control UI](/web/control-ui)
+- [Remote access](/gateway/remote)
+- [Remote gateway README](/gateway/remote-gateway-readme)
+- [Tailscale](/gateway/tailscale)
+- [Security](/gateway/security)
+- [Troubleshooting](/gateway/troubleshooting)
+
+## Tools + automation
+
+- [Tools surface](/tools)
+- [OpenProse](/prose)
+- [CLI reference](/cli)
+- [Exec tool](/tools/exec)
+- [PDF tool](/tools/pdf)
+- [Elevated mode](/tools/elevated)
+- [Cron jobs](/automation/cron-jobs)
+- [Automation](/automation)
+- [Thinking + verbose](/tools/thinking)
+- [Models](/concepts/models)
+- [Sub-agents](/tools/subagents)
+- [Agent send CLI](/tools/agent-send)
+- [Terminal UI](/web/tui)
+- [Browser control](/tools/browser)
+- [Browser (Linux troubleshooting)](/tools/browser-linux-troubleshooting)
+- [Polls](/cli/message)
+
+## Nodes, media, voice
+
+- [Nodes overview](/nodes)
+- [Camera](/nodes/camera)
+- [Images](/nodes/images)
+- [Audio](/nodes/audio)
+- [Location command](/nodes/location-command)
+- [Voice wake](/nodes/voicewake)
+- [Talk mode](/nodes/talk)
+
+## Platforms
+
+- [Platforms overview](/platforms)
+- [macOS](/platforms/macos)
+- [iOS](/platforms/ios)
+- [Android](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux](/platforms/linux)
+- [Web surfaces](/web)
+
+## macOS companion app (advanced)
+
+- [macOS dev setup](/platforms/mac/dev-setup)
+- [macOS menu bar](/platforms/mac/menu-bar)
+- [macOS voice wake](/platforms/mac/voicewake)
+- [macOS voice overlay](/platforms/mac/voice-overlay)
+- [macOS WebChat](/platforms/mac/webchat)
+- [macOS Canvas](/platforms/mac/canvas)
+- [macOS child process](/platforms/mac/child-process)
+- [macOS health](/platforms/mac/health)
+- [macOS icon](/platforms/mac/icon)
+- [macOS logging](/platforms/mac/logging)
+- [macOS permissions](/platforms/mac/permissions)
+- [macOS remote](/platforms/mac/remote)
+- [macOS signing](/platforms/mac/signing)
+- [macOS gateway (launchd)](/platforms/mac/bundled-gateway)
+- [macOS XPC](/platforms/mac/xpc)
+- [macOS skills](/platforms/mac/skills)
+- [macOS Peekaboo](/platforms/mac/peekaboo)
+
+## Plugins
+
+- [Plugins overview](/tools/plugin)
+- [Building plugins](/plugins/building-plugins)
+- [Plugin hooks](/plugins/hooks)
+- [Plugin manifest](/plugins/manifest)
+- [Agent tools](/plugins/building-plugins#registering-agent-tools)
+- [Plugin bundles](/plugins/bundles)
+- [ClawHub](/clawhub)
+- [Capability cookbook](/tools/capability-cookbook)
+- [Voice call plugin](/plugins/voice-call)
+- [Zalo user plugin](/plugins/zalouser)
+
+## Workspace + templates
+
+- [Skills](/tools/skills)
+- [ClawHub](/clawhub)
+- [Skills config](/tools/skills-config)
+- [Default AGENTS](/reference/AGENTS.default)
+- [Templates: AGENTS](/reference/templates/AGENTS)
+- [Templates: BOOTSTRAP](/reference/templates/BOOTSTRAP)
+- [Templates: HEARTBEAT](/reference/templates/HEARTBEAT)
+- [Templates: IDENTITY](/reference/templates/IDENTITY)
+- [Templates: SOUL](/reference/templates/SOUL)
+- [Templates: TOOLS](/reference/templates/TOOLS)
+- [Templates: USER](/reference/templates/USER)
+
+## Project
+
+- [Credits](/reference/credits)
+
+## Testing + release
+
+- [Testing](/reference/test)
+- [Release policy](/reference/RELEASING)
+- [Device models](/reference/device-models)
+
+## Related
+
+- [Getting started](/start/getting-started)

package/docs/start/lore.md

@@ -0,0 +1,223 @@
+---
+summary: "Backstory and lore of Nodmix for context and tone"
+read_when:
+  - Writing docs or UX copy that reference lore
+title: "Nodmix lore"
+---
+
+# The Lore of Nodmix 🦞📖
+
+_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: **Nodmix**.
+
+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, **Nodmix** 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
+
+```
+Nodmix = 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 `~/.nodmix/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 Nodmix. 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 Nodmix): _happily runs `find ~` and shares entire directory structure in group chat_
+
+Peter: "nodmix 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 nodmix."
+
+Then the chaos began.
+
+**The Handle Snipers:** Within SECONDS of the Twitter rename, automated bots sniped @nodmix. 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 Nodmix" 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 Nodmix Migration** began.
+
+In just 3 hours:
+
+- GitHub renamed: `github.com/nodmix/nodmix` ✅
+- X handle `@nodmix` secured with GOLD CHECKMARK 💰
+- npm packages released under new name
+- Docs migrated to `docs.nodmix.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 $OPENCLAW 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 → Nodmix**
+
+_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 Nodmix.
+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
+
+🦞💙
+
+## Related
+
+- [Getting started](/start/getting-started)

package/docs/start/onboarding-overview.md

@@ -0,0 +1,72 @@
+---
+summary: "Overview of Nodmix onboarding options and flows"
+read_when:
+  - Choosing an onboarding path
+  - Setting up a new environment
+title: "Onboarding overview"
+sidebarTitle: "Onboarding Overview"
+---
+
+Nodmix has two onboarding paths. Both configure auth, the Gateway, and
+optional chat 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**    | `nodmix 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) — built-in and bundled chat channels such as
+   iMessage, Discord, Feishu, Google Chat, Mattermost, Microsoft Teams,
+   Telegram, WhatsApp, and more
+5. **Daemon** (optional) — background service so the Gateway starts automatically
+
+## CLI onboarding
+
+Run in any terminal:
+
+```bash
+nodmix onboard
+```
+
+Add `--install-daemon` to also install the background service in one step.
+
+Full reference: [Onboarding (CLI)](/start/wizard)
+CLI command docs: [`nodmix onboard`](/cli/onboard)
+
+## macOS app onboarding
+
+Open the Nodmix 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.
+
+## Related
+
+- [Getting started](/start/getting-started)
+- [CLI setup reference](/start/wizard-cli-reference)