ohwow 0.1.13 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-Business Source License 1.1
+MIT License
 
-Parameters
+Copyright (c) 2026 Jesus David Oñoro Delgado
 
-Licensor:             ohwow
-Licensed Work:        ohwow runtime (all versions)
-Additional Use Grant: You may use the Licensed Work for any purpose, including
-                      production use, EXCEPT for building or offering a product
-                      or service that competes with ohwow.fun or its features.
-Change Date:          March 2, 2030
-Change License:       Apache License, Version 2.0
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-For the full BSL 1.1 license text, see https://mariadb.com/bsl11/
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-Notice
-
-The Licensed Work is (c) 2024-2026 ohwow.
-
-The full text of the Business Source License 1.1 is incorporated by reference
-from the URL above. This file states only the parameters specific to this
-project. In the event of any conflict, the full license text governs.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,224 +1,288 @@
 # ohwow
 
-Send me a message for support at ogsus@ohwow.fun
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/ohwow)](https://www.npmjs.com/package/ohwow)
+[![CI](https://github.com/ohwow-fun/ohwow/actions/workflows/ci.yml/badge.svg)](https://github.com/ohwow-fun/ohwow/actions/workflows/ci.yml)
+[![npm downloads](https://img.shields.io/npm/dm/ohwow)](https://www.npmjs.com/package/ohwow)
+[![Discord](https://img.shields.io/badge/Discord-join-5865F2)](https://discord.gg/WUGnGqceeY)
 
-A free and open-source local AI agent runtime. Full-featured out of the box with [Ollama](https://ollama.com) for local models. Cloud features (sync, OAuth integrations, cloud task dispatch, webhook relay) available with an [ohwow.fun](https://ohwow.fun) subscription.
+**An AI team that runs on your laptop. Agents that learn your patterns, message your customers, automate your operations, and actually understand what your business needs right now. Free. Open source. Your data stays on your machine.**
 
-## Getting Started
-
-### Install
+<p align="center">
+  <img src="docs/demo.gif" alt="ohwow demo" width="800">
+</p>
 
 ```bash
 npm install ohwow -g
+ohwow
 ```
 
-### Requirements
+Running in under 5 minutes. A setup wizard connects to [Ollama](https://ollama.com), picks a model, and builds an AI team for your business type.
 
-- Node.js 20+
-- [Ollama](https://ollama.com) for local models
-- Optional: Anthropic API key (for Claude models)
-- Optional: Playwright browsers (`npx playwright install chromium`) for browser automation
-- Optional: C++ compiler may be needed on some platforms for `better-sqlite3`
+---
 
-### Launch
+## What a day looks like with ohwow
 
-```bash
-ohwow
-```
+**7:45 AM** — You open your laptop. ohwow noticed you always start around this time. Your morning briefing is ready: "3 tasks completed overnight. 1 needs your eye (a customer contract with unusual terms). 2 leads replied to yesterday's outreach. Your Sales Agent's follow-up is queued for 9am."
 
-## First Launch
+**8:00 AM** — You say: "What should I focus on today?" ohwow knows you're at growth stage 2 (Attract). It responds: "You're over-indexing on content creation this week. Your growth stage needs more outreach. Your Sales Agent has 3 warm leads that haven't been contacted. Want me to draft follow-ups?"
 
-A setup wizard appears in your terminal. Point it at your Ollama instance to get started. To connect to ohwow.fun cloud, enter your license key (from the ohwow.fun dashboard, under Settings > License).
+**8:15 AM** — You approve the follow-ups. The Sales Agent sends personalized WhatsApp messages to each lead, referencing their specific context from your CRM. No templates. Each message reads like you wrote it.
 
-Config is saved to `~/.ohwow/config.json`. You only do this once.
+**10:30 AM** — You're deep in product work. A customer emails with a support question. ohwow detects it, routes it to the Support Agent, which drafts a response. Because your cognitive load is high (3 open approvals, deep work mode), it batches the notification instead of interrupting. You'll see it at your next natural break.
 
-## What Happens at Startup
+**2:00 PM** — ohwow notices your energy dips after lunch (it learned this from 30 days of watching your activity patterns). It holds the complex research report that just completed, knowing you'll evaluate it better in the morning. Instead, it surfaces a simple approval that takes 10 seconds.
 
-Once configured, the runtime:
+**4:00 PM** — A lead responds positively on WhatsApp. ohwow's Sales Agent wants to send a pricing proposal. It could auto-send (it's earned that trust after 47 successful outreach tasks with 94% approval), but the amount is above the auto-approve threshold. You get a one-line notification: "Ready to send pricing to Acme Corp. $4,500/mo proposal. Approve?"
 
-1. Loads config from `~/.ohwow/config.json`
-2. Spawns the daemon process
-3. Initializes the local SQLite database
-4. Starts the execution engine, orchestrator, and model router
-5. Connects messaging channels (WhatsApp, Telegram) if configured
-6. Starts the scheduler, proactive engine, and trigger evaluator
-7. Launches the HTTP server (default port 7700)
-8. Connects to the ohwow.fun control plane (enterprise)
-9. Opens a WebSocket for real-time updates
+**6:15 PM** — You close your laptop. ohwow stops all non-critical notifications. Your agents keep working: the Content Writer drafts tomorrow's blog post, the Researcher compiles a competitive analysis you asked for this morning. Results will be waiting when you open up tomorrow.
 
-From here, agents execute tasks on your hardware using your own API keys. The dashboard sends the work, your machine does the thinking.
+**End of day**: 12 tasks completed across 4 agents. 3 leads contacted. 1 support ticket resolved. 1 blog draft ready. You spent 20 minutes on approvals. The rest was your work.
 
-## CLI Commands
+---
 
-| Command | What it does |
-|---|---|
-| `ohwow` | Start the TUI (default) |
-| `ohwow --daemon` | Start daemon in foreground (for systemd/launchd/Docker) |
-| `ohwow stop` | Stop the daemon |
-| `ohwow status` | Check daemon status (PID and port) |
-| `ohwow logs` | Tail daemon logs |
-| `ohwow restart` | Restart the daemon |
+## How it actually works
 
-## TUI
+### Talk to it like a person
 
-The terminal UI opens into a chat interface with tab navigation. Use arrow keys or tab to switch between:
+The orchestrator understands natural language with 150+ tools behind it:
 
-- **Dashboard** — overview of your workspace
-- **Agents** — manage agent configs, memory, and capabilities
-- **Tasks** — view and manage running/completed tasks
-- **Approvals** — review pending items before execution
-- **Activity** — live feed of everything happening
-- **Automations** — webhook-based automation triggers
-- **Contacts** — CRM with leads, customers, partners
-- **Settings** — config, connections, license
+| What you say | What happens |
+|---|---|
+| "Follow up with everyone who opened my last email" | Finds contacts with email opens, drafts personalized follow-ups, sends via WhatsApp or email |
+| "Research our top 5 competitors and create a comparison" | Launches the Research Agent with deep web search, compiles findings into a structured report |
+| "Schedule outreach every weekday at 9am" | Creates a recurring schedule. The agent picks leads from your CRM, personalizes messages, and sends them on time |
+| "Open Figma and export the hero banner as PNG" | Takes over your desktop, opens the app, navigates to the file, exports it, saves to your folder |
+| "How's the business doing?" | Shows your eudaimonia score (workspace flourishing), task stats, lead pipeline, agent efficiency, and growth stage guidance |
+| "Create a project for the website redesign" | Creates a Kanban board, suggests task breakdown, assigns agents to each phase |
+| "Send a WhatsApp to the team: launching Friday" | Sends through your connected WhatsApp. No API needed. Uses your actual WhatsApp number |
+| "What should I focus on this week?" | Analyzes your growth stage, current work balance, goal velocity, and team capacity. Gives specific, actionable recommendations |
 
-Everything you see in the web dashboard is also here, running locally.
+### Your agents learn and improve
 
-## Web UI
+ohwow agents aren't stateless. They remember what worked and what didn't:
 
-The runtime serves a built-in React app at `http://localhost:7700`. Same capabilities as the TUI. Useful if you prefer a graphical interface or want to share access with your team on the local network. Override the port with the `OHWOW_PORT` env var.
+- After the Content Writer produces 50 blog posts, it knows your brand voice, preferred structure, and which topics get approved immediately vs revised
+- After the Sales Agent sends 200 outreach messages, it knows which opening lines get responses and which get ignored
+- After the Researcher completes 30 deep dives, it knows which sources you trust and how detailed you want the analysis
 
-## Orchestrator
+This isn't "fine-tuning." It's persistent memory, skill synthesis, and pattern mining that builds real expertise over time. Each agent develops its own character: some become meticulous researchers, others become fast-moving closers.
 
-The orchestrator is a conversational assistant built into the runtime with 40+ tools. Open the Chat tab in the TUI, or use the web UI.
+### It knows your business stage
 
-You can talk to it naturally:
+A startup just launching needs different work than an established company scaling. ohwow knows the difference:
 
-| What you say | What happens |
-|---|---|
-| "Run the content writer on this week's blog post" | Dispatches a task to that agent immediately |
-| "What failed today?" | Lists recent failed tasks with details |
-| "Schedule outreach every weekday at 9am" | Creates a cron schedule for the agent |
-| "Send a WhatsApp to the team: launching Friday" | Sends the message through your connected WhatsApp |
-| "Plan out researching 5 new leads this week" | Creates a multi-step plan with agent assignments, waits for your approval |
-| "Show me the business pulse" | Returns task stats, contact pipeline, costs, and streaks |
-| "Create a project for the website redesign" | Creates a project with a Kanban board |
-| "Move that task to review" | Moves a task between board columns |
+| Growth Stage | Revenue | What ohwow prioritizes |
+|---|---|---|
+| **Launch** | $0-$1K | Selling. Not building more features. Not researching competitors. Getting first customers |
+| **Attract** | $1K-$10K | Lead flow. Content that brings people in. One channel, mastered |
+| **Systemize** | $10K-$25K | Automating what works. SOPs. Reducing founder dependency |
+| **Focus** | $25K-$50K | Cutting the bottom 20%. Serving ideal customers. Unit economics |
+| **Expand** | $50K-$100K | Second product or market. Validated before scaled |
+| **Structure** | $250K-$500K | Delegation. The founder stops doing execution work |
 
-The orchestrator covers: agents, tasks, projects, CRM (contacts, pipeline, events), scheduling, messaging (WhatsApp + Telegram), A2A connections, goal planning, deep research, analytics, and workflows. It can also switch your TUI tabs if you ask ("go to approvals").
+When you ask "what should I focus on?", the answer comes from practical wisdom about your specific stage, not generic advice.
 
-## Features
+### It respects that you're human
 
-### Agent Memory
+Most productivity tools treat you like a machine that processes tasks. ohwow doesn't.
 
-After each task, key facts, skills, and feedback are extracted and stored locally. Memories are periodically consolidated to keep context sharp. On future tasks, relevant memories are retrieved via RAG and compiled into the agent's context. Agents improve the more they work. View any agent's memory from the Agents tab.
+- **It learns your rhythm.** Morning person? Complex approvals arrive at 9am. Afternoon slump? Only quick tasks surface after 2pm.
+- **It detects overload.** When you have too many open decisions, it stops adding work and starts batching, prioritizing, and filtering.
+- **It respects boundaries.** If you always stop responding at 6pm, ohwow stops notifying. No setting required. It learns by watching.
+- **It suggests rest.** After a week of sprinting, it shifts work toward reflective tasks and away from high-pressure action items.
 
-### Browser Automation
+---
 
-Agents can browse the web using Playwright. Navigation, clicking, form filling, screenshots, and content extraction. The browser launches on first use and runs headless by default. Set `OHWOW_BROWSER_HEADLESS=false` to watch it work.
+## Real scenarios
 
-### WhatsApp and Telegram
+### For a solo e-commerce founder
 
-Connect WhatsApp through a QR code scan in Settings (no Meta business API needed). Connect Telegram with a bot token. Once connected, incoming messages route to the orchestrator automatically. Your agents can reply, take action, or flag things for your attention. You control which chats are allowed.
+You sell handmade candles on Shopify. You spend 3 hours a day on customer emails, social media, and supplier follow-ups.
 
-### Voice
+With ohwow: the Support Agent handles customer questions via WhatsApp (you approve the first few, then trust builds and it handles most autonomously). The Content Writer creates daily Instagram captions and weekly blog posts about your craft. The Sales Agent follows up with wholesale leads from your last trade show. You focus on making candles.
 
-Full voice pipeline with local and cloud options:
+### For a SaaS founder with a small team
 
-- **Speech-to-Text**: Voicebox (Whisper via local FastAPI server), WhisperLocal (via Ollama), or WhisperAPI (OpenAI cloud fallback)
-- **Text-to-Speech**: VoiceboxTTS (local), Piper (local), or OpenAI TTS (cloud fallback)
+You and 2 engineers are building a developer tool. Marketing, support, and sales fall on you.
 
-### A2A Protocol
+With ohwow: agents handle lead outreach, support ticket triage, competitive research, and content creation. The system knows you're at stage 2 (Attract) and pushes outreach over feature building. When a lead responds on WhatsApp, the Sales Agent drafts a response referencing their specific use case from your CRM. Your team reviews agent output in the dashboard. Trust builds per domain: the Content Writer runs autonomously, the Sales Agent still needs approval for pricing discussions.
 
-Connect to external agents using the [A2A protocol](https://google.github.io/A2A/) over JSON-RPC 2.0. Each agent publishes a card at `/.well-known/agent-card.json` describing its capabilities. Trust levels (`read_only`, `execute`, `autonomous`, `admin`) control what external agents can do. Scopes cover tasks, agents, results, and file access. Managed from the A2A tab or through the orchestrator.
+### For an agency managing multiple clients
 
-### Scheduling and Proactive Engine
+You run a marketing agency with 10 clients. Each needs weekly reports, social posts, and campaign analysis.
 
-Set agents or workflows to run on cron schedules. Create schedules through conversation ("schedule the analyst every Monday at 8am") or from the Schedules tab.
+With ohwow: each client gets dedicated agents. The Researcher pulls analytics. The Content Writer drafts social posts in each client's brand voice. The Reporter compiles weekly performance reports. Agents learn each client's preferences separately. Desktop automation exports graphics from Canva, screenshots from analytics dashboards. Multi-device mesh lets your office Mac Mini run overnight while you review results on your MacBook in the morning.
 
-The proactive engine runs every 30 minutes and checks for overdue tasks, aging approvals, and idle agents. It generates nudges (suggestions, not auto-executions) so nothing falls through the cracks.
+### For a privacy-focused business
 
-### Goal Planning and Approvals
+You handle sensitive customer data and can't use cloud AI platforms.
 
-For complex goals, the orchestrator breaks them into multi-step plans with agent assignments and dependencies. Plans start as drafts. You review the steps, approve or reject, and track execution from the Plans tab. Rejected tasks can retry with your feedback included.
+With ohwow: everything runs locally with Ollama. No data leaves your machine. No API calls to external LLMs if you don't want them. Local SQLite database. Local model inference. WhatsApp messages stay on your device. You get full AI automation with zero cloud dependency.
 
-### Projects and CRM
+---
 
-Organize tasks into projects with Kanban boards (backlog, todo, in progress, review, done). The built-in CRM tracks contacts (leads, customers, partners), logs events (calls, emails, meetings), and gives you pipeline analytics. All stored locally.
+## Features
 
-### Automations and Triggers
+| Category | What you get |
+|---|---|
+| **AI Agents** | 48 pre-built agents across 6 business types. Persistent memory. Tool mastery. Real expertise over time |
+| **Orchestrator** | 150+ tools. Natural language interface. Growth-stage-aware recommendations |
+| **Desktop Control** | Full macOS automation: mouse, keyboard, screen capture. Your agents operate any app on your computer |
+| **Messaging** | WhatsApp + Telegram built in. Uses your real number. Auto-routing to the right agent |
+| **Browser** | Local Chromium automation: navigate, click, fill forms, screenshot, extract data |
+| **CRM** | Contacts, pipeline, events, analytics. All stored locally. Agents use it to personalize outreach |
+| **Scheduling** | Cron schedules + smart timing based on opportunity detection |
+| **Workflows** | Multi-step automation graphs. Parallel execution. Conditions and branching |
+| **Multi-device** | Zero-config mesh across your machines. Tasks route to the best device. Self-healing if one goes down |
+| **Physical I/O** | Connect Arduino, ESP32, sensors, actuators. Your office becomes smart |
+| **MCP** | External tool integration via Model Context Protocol |
+| **A2A** | Agent-to-Agent protocol for connecting with other AI systems |
+| **Cognitive Architecture** | 7-layer philosophical system powering everything under the hood |
+
+## Use with Claude Code
+
+ohwow works as a Claude Code plugin. 25 tools become available in your Claude conversations.
 
-Webhook-based automations that fire on external events. Configure field mapping to extract data from incoming payloads and route it to agents or workflows. Managed from the Automations tab.
+```bash
+claude plugin install ohwow-fun/ohwow
+```
 
-### Workflows
+Or add to any project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ohwow": {
+      "command": "npx",
+      "args": ["-y", "ohwow", "mcp-server"]
+    }
+  }
+}
+```
 
-DAG-based multi-agent execution graphs. Define sequences of agent tasks with conditions and branches. Workflows can be triggered manually, on a schedule, or via automation triggers.
+**Example**: "Research the top 5 competitors in our space, add the findings to the knowledge base, then create a contact for each CEO." Claude uses ohwow's research, knowledge, and CRM tools seamlessly.
 
-### MCP Servers
+## Desktop Control
 
-Integrate external tools via the [Model Context Protocol](https://modelcontextprotocol.io/). Supports stdio (subprocess) and HTTP (Streamable HTTP) transports. Authentication via OAuth 2.1, bearer tokens, or API keys. MCP tools are auto-adapted to the Anthropic SDK format and can be assigned per-agent or globally.
+Your agents aren't trapped in a chat window. They operate your computer.
 
-### Code Sandbox
+```
+You: "Fill out the Q1 expense report in Google Sheets using last month's receipts folder"
+
+ohwow:
+  1. Opens Finder, navigates to receipts
+  2. Opens Google Sheets in Chrome
+  3. Reads each receipt, types amounts into the right cells
+  4. Double-checks totals
+  5. Done. You were making coffee the whole time.
+```
 
-Agents can execute JavaScript in an isolated sandbox (Node.js `vm` module). No filesystem, network, or process access. 5-second default timeout, 30-second maximum. Safe globals only (Math, JSON, Date, Array, Object, Map, Set, etc.).
+The agent takes a screenshot, analyzes it with a vision model, decides the next action, executes it, then screenshots again to see the result. This perception/reasoning/action loop repeats until the task is done.
 
-### Web Search
+**Safety first.** Desktop control requires explicit permission. Emergency stop halts everything instantly. Dangerous actions (Terminal, system settings) trigger additional approval.
 
-Agents with web search enabled can search the web during task execution, powered by Anthropic's built-in search tool.
+## Multi-device Mesh
 
-### Local Models with Ollama
+```
+Mac Mini (home office)       MacBook (on the go)          Raspberry Pi (warehouse)
+┌────────────────┐          ┌────────────────┐          ┌────────────────┐
+│ WhatsApp Agent  │◄─mesh──►│ Research Agent  │◄─mesh──►│ Temp Sensor     │
+│ Desktop Tasks   │          │ Browser Auto    │          │ Motion Detect   │
+│ Overnight Work  │          │ Mobile Review   │          │ Inventory Scan  │
+└────────────────┘          └────────────────┘          └────────────────┘
+```
 
-If you run [Ollama](https://ollama.com) locally, the runtime routes lightweight tasks (orchestration, memory extraction) to your local model instead of Claude. The model catalog includes 25+ models across 5 memory tiers with device-aware recommendations. Complex work (planning, agent tasks, browser automation) still goes to Claude. If Ollama goes down, everything falls back to Anthropic automatically.
+Zero configuration. Devices discover each other on your network. Tasks go to the best device for the job. If your Mac Mini discovers that a lead's website is down, your MacBook knows instantly. If one device goes offline, another takes over its responsibilities.
 
-### Offline Mode
+## Why ohwow?
 
-If ohwow.fun becomes unreachable, the runtime continues with cached agent configs. Tasks still execute, results still store locally. When connectivity returns, everything syncs back up.
+| | Zapier | n8n | Make | **ohwow** |
+|---|---|---|---|---|
+| Runs on your machine | No | Self-host option | No | **Yes, always** |
+| Desktop control | No | No | No | **Yes, with safety guards** |
+| AI agents with real memory | No | Partial | No | **Yes, agents build expertise** |
+| Cost to start | $20+/mo | Free (self-host) | $10+/mo | **$0 with Ollama** |
+| Pre-built business agents | No | No | No | **48 agents, 6 business types** |
+| WhatsApp + Telegram | Plugin | Plugin | Plugin | **Built in** |
+| CRM + contacts | No | No | No | **Built in** |
+| Multi-device mesh | No | No | No | **Zero-config** |
+| Knows your growth stage | No | No | No | **Yes, adapts priorities** |
+| Respects your energy/stress | No | No | No | **Yes, bio-aware** |
+| Your data stays local | No | Optional | No | **Always** |
 
-## Connected Mode (Cloud)
+## Cloud (optional)
 
-Connect to ohwow.fun to add cloud features on top of the free local runtime.
+Connect to [ohwow.fun](https://ohwow.fun) for cloud features on top of the free local runtime:
 
-**Cloud features (require connection):**
-- Cloud sync: agent configs sync from your dashboard
-- Cloud task dispatch: receive tasks dispatched from the web
-- OAuth integrations: Gmail, Slack, and other cloud-based integrations
-- Webhook relay: cloud-proxied webhooks for external services
-- Heartbeats and health monitoring
+- **Phone dispatch**: assign tasks to your computer from your phone
+- **OAuth integrations**: Gmail, Slack, and more
+- **AI site generator**: with hosting and custom domains
+- **Fleet dashboard**: manage all your devices from one place
+- **Collective intelligence**: visualize what your agents have learned
+- **Work ontology dashboard**: eudaimonia score, growth stage guidance
 
-**What stays local (always):**
-- Prompts and system instructions
-- Agent outputs and full conversations
-- Long-term agent memory
-- CRM contacts and activity history
-- WhatsApp and Telegram message history
-- Browser session data and screenshots
+All local features work without cloud. See [pricing](https://ohwow.fun/pricing) for plans starting at $29/mo.
 
-**How it works:**
+## Under the Hood
 
-Activate with a license key from the ohwow.fun dashboard (Settings > License). The runtime connects to the control plane via long-polling, receives task dispatches, and sends back status updates. Heartbeats confirm the device is online. Each license is locked to a single device. The cloud dashboard gives you a web interface for managing agents, reviewing tasks, and monitoring your workspace without touching the terminal.
+For those who want to understand the architecture: ohwow is built on a seven-layer philosophical cognitive architecture. Each layer addresses a distinct dimension of intelligence, grounded in philosophy from Aristotle to modern cognitive science.
 
-All local features (agents, scheduling, WhatsApp, Telegram, A2A, browser automation, voice, CRM, automations, approvals) work without a cloud connection.
+```
+Layer 7: BIOS       — Respects human biology (energy, stress, boundaries)
+Layer 6: Symbiosis  — Models human-AI collaboration (trust, handoffs, mutual learning)
+Layer 5: Soul       — Tracks identity for agents and humans (values, blind spots, growth)
+    Persona         — Real-time behavioral profiling (circadian, load, communication style)
+Layer 4: Mesh       — Distributed consciousness across devices (propagation, shared body, self-healing)
+Layer 3: Work       — Purpose-driven execution (growth stage wisdom, work classification, flourishing)
+Layer 2: Body       — Physical + digital embodiment (organs, nervous systems, affordances, PID controllers)
+Layer 1: Brain      — Cognitive cycle: perceive → deliberate → act (prediction, reflection, dialectic)
+Layer 0: Runtime    — Orchestrator, engine, 150+ tools, DB, API, scheduling, messaging
+```
+
+115+ modules. 28,000+ lines. Every philosophical concept is load-bearing architecture: remove any one and the system degrades measurably. See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full technical breakdown.
 
-## Headless / Daemon Mode
+## Self-hosting
+
+| Command | What it does |
+|---|---|
+| `ohwow` | Start the TUI (default) |
+| `ohwow --daemon` | Start daemon in foreground (for systemd/launchd/Docker) |
+| `ohwow stop` | Stop the daemon |
+| `ohwow status` | Check daemon status |
+| `ohwow logs` | Tail daemon logs |
 
-For servers, containers, or always-on deployments:
+Docker:
 
 ```bash
-ohwow --daemon
+docker run -d --name ohwow -p 7700:7700 -v ~/.ohwow:/root/.ohwow ohwow
 ```
 
-Runs the daemon in the foreground (no TUI). Suitable for systemd, launchd, or Docker. Set `OHWOW_HEADLESS=1` as an alternative. The web UI still runs normally. Configure through environment variables.
+## Requirements
 
-## Configuration
+- Node.js 20+
+- [Ollama](https://ollama.com) for local models
+- Optional: Anthropic API key (for Claude models)
+- Optional: Playwright browsers (`npx playwright install chromium`) for browser automation
+- Optional: macOS Accessibility permission for desktop control
 
-Config lives at `~/.ohwow/config.json`. Key environment variables:
+## Troubleshooting
 
-| Variable | Purpose |
-|---|---|
-| `OHWOW_PORT` | HTTP server port (default 7700) |
-| `OHWOW_HEADLESS` | Set to `1` for headless mode |
-| `OHWOW_BROWSER_HEADLESS` | Set to `false` to show the browser |
-| `ANTHROPIC_API_KEY` | Anthropic API key for Claude models |
+| Problem | Solution |
+|---------|----------|
+| `better-sqlite3` build fails | Install build tools: `xcode-select --install` (macOS), `sudo apt install build-essential python3` (Linux) |
+| Ollama not detected | Ensure Ollama is running (`ollama serve`) and accessible at `http://localhost:11434` |
+| Port 7700 in use | Set `OHWOW_PORT=7701` or any free port |
+| WhatsApp QR expired | Restart ohwow and scan the new QR within 60 seconds |
 
-## Supported Models
+## Community
 
-| Model | Provider |
-|---|---|
-| Claude Opus 4.6 | Anthropic |
-| Claude Sonnet 4.6 | Anthropic |
-| Claude Haiku 4.5 | Anthropic |
-| Any Ollama model | Local |
+- [Discord](https://discord.gg/WUGnGqceeY)
+- [Contributing](./CONTRIBUTING.md)
+- [Architecture](./ARCHITECTURE.md)
+- [Security](./SECURITY.md)
+- Email: ogsus@ohwow.fun
 
 ## License
 
-BSL 1.1 (Business Source License). Free to use, including production. You can't use it to build a competing product. Converts to Apache 2.0 on March 2, 2030. See [LICENSE](./LICENSE) for details.
+[MIT](./LICENSE)

package/dist/api.d.ts

@@ -0,0 +1,91 @@
+import Database from 'better-sqlite3';
+
+/**
+ * DatabaseAdapter Interface (Runtime Copy)
+ *
+ * Abstracts the query builder pattern used by Supabase's PostgREST client.
+ * Both the Supabase adapter (cloud) and SQLite adapter (local runtime)
+ * implement this interface, allowing all agent services to work with either backend.
+ *
+ * Mirrors the SupabaseClient chaining API: .from(table).select().eq().single()
+ */
+interface DbResult<T> {
+    data: T | null;
+    error: DbError | null;
+    count?: number | null;
+}
+interface DbError {
+    message: string;
+    code?: string;
+    details?: string;
+    hint?: string;
+}
+interface FilterBuilder<T> {
+    eq(column: string, value: unknown): FilterBuilder<T>;
+    neq(column: string, value: unknown): FilterBuilder<T>;
+    gt(column: string, value: unknown): FilterBuilder<T>;
+    gte(column: string, value: unknown): FilterBuilder<T>;
+    lt(column: string, value: unknown): FilterBuilder<T>;
+    lte(column: string, value: unknown): FilterBuilder<T>;
+    in(column: string, values: unknown[]): FilterBuilder<T>;
+    is(column: string, value: null | boolean): FilterBuilder<T>;
+    or(filters: string, options?: {
+        foreignTable?: string;
+    }): FilterBuilder<T>;
+    not(column: string, operator: string, value: unknown): FilterBuilder<T>;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): FilterBuilder<T>;
+    limit(count: number): FilterBuilder<T>;
+    range(from: number, to: number): FilterBuilder<T>;
+    single(): PromiseLike<DbResult<T>>;
+    maybeSingle(): PromiseLike<DbResult<T | null>>;
+    then<TResult1 = DbResult<T[]>, TResult2 = never>(onfulfilled?: ((value: DbResult<T[]>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+}
+type SelectBuilder<T> = FilterBuilder<T>;
+interface InsertBuilder<T> {
+    select(columns?: string): FilterBuilder<T>;
+    then<TResult1 = DbResult<null>, TResult2 = never>(onfulfilled?: ((value: DbResult<null>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+}
+interface UpdateBuilder<T> extends FilterBuilder<T> {
+    eq(column: string, value: unknown): UpdateBuilder<T>;
+    neq(column: string, value: unknown): UpdateBuilder<T>;
+    select(columns?: string): FilterBuilder<T>;
+}
+type DeleteBuilder<T> = FilterBuilder<T>;
+interface TableBuilder<T = Record<string, unknown>> {
+    select(columns?: string, options?: {
+        count?: 'exact';
+        head?: boolean;
+    }): SelectBuilder<T>;
+    insert(data: Partial<T> | Partial<T>[]): InsertBuilder<T>;
+    update(data: Partial<T>): UpdateBuilder<T>;
+    delete(): DeleteBuilder<T>;
+}
+interface DatabaseAdapter {
+    from<T = Record<string, unknown>>(table: string): TableBuilder<T>;
+    rpc<T = unknown>(fn: string, params?: Record<string, unknown>): PromiseLike<DbResult<T>>;
+}
+
+/**
+ * SQLite Adapter
+ *
+ * Implements the DatabaseAdapter interface using better-sqlite3.
+ * Translates the SupabaseClient-shaped query builder API into SQL queries
+ * against a local SQLite database.
+ *
+ * Used by the local runtime for local data plane storage.
+ */
+
+/**
+ * Map of registered RPC functions for the SQLite adapter.
+ * In Supabase, .rpc() calls server-side Postgres functions.
+ * In SQLite, we register JS functions that perform the same logic.
+ */
+type RpcHandler = (params: Record<string, unknown>) => unknown;
+interface SqliteAdapterOptions {
+    rpcHandlers?: Record<string, RpcHandler>;
+}
+declare function createSqliteAdapter(db: Database.Database, options?: SqliteAdapterOptions): DatabaseAdapter;
+
+export { type SqliteAdapterOptions, createSqliteAdapter };

package/dist/api.js

@@ -0,0 +1,2 @@
+import { createRequire } from 'module'; const require = createRequire(import.meta.url);
+function F(s,e){return{message:s,code:e}}function q(s,e){return{data:s,error:null,count:e}}function f(s,e){return{data:null,error:F(s,e)}}function A(s){let e=s.split(","),i=[],o=[];for(let p of e){let c=p.trim().split(".");if(c.length<3)continue;let l=c[0],t=c[1],r=c.slice(2).join(".");switch(t){case"eq":i.push(`${l} = ?`),o.push(r);break;case"neq":i.push(`${l} != ?`),o.push(r);break;case"gt":i.push(`${l} > ?`),o.push(r);break;case"gte":i.push(`${l} >= ?`),o.push(r);break;case"lt":i.push(`${l} < ?`),o.push(r);break;case"lte":i.push(`${l} <= ?`),o.push(r);break;case"is":r==="null"?i.push(`${l} IS NULL`):r==="true"?i.push(`${l} = 1`):r==="false"&&i.push(`${l} = 0`);break;case"ilike":i.push(`${l} LIKE ? COLLATE NOCASE`),o.push(r.replace(/%25/g,"%"));break;case"like":i.push(`${l} LIKE ?`),o.push(r);break;case"in":{let n=r.replace(/^\(/,"").replace(/\)$/,"").split(",");i.push(`${l} IN (${n.map(()=>"?").join(",")})`),o.push(...n)}break;default:i.push(`${l} ${t} ?`),o.push(r)}}return{sql:`(${i.join(" OR ")})`,params:o}}function O(s){if(s.conditions.length===0)return{sql:"",params:[]};let e=[],i=[];for(let o of s.conditions)e.push(o.sql),i.push(...o.params);return{sql:` WHERE ${e.join(" AND ")}`,params:i}}function B(s){return s.orderClauses.length===0?"":` ORDER BY ${s.orderClauses.join(", ")}`}function C(s){if(s.rangeFrom!==void 0&&s.rangeTo!==void 0)return` LIMIT ${s.rangeTo-s.rangeFrom+1} OFFSET ${s.rangeFrom}`;if(s.limitValue!==void 0){let e=s.offsetValue?` OFFSET ${s.offsetValue}`:"";return` LIMIT ${s.limitValue}${e}`}return""}function S(s){if(!s)return s;let e={...s};for(let[i,o]of Object.entries(e))if(typeof o=="string"&&(o.startsWith("{")&&o.endsWith("}")||o.startsWith("[")&&o.endsWith("]")))try{e[i]=JSON.parse(o)}catch{}return e}function y(s,e,i,o,p,c,l){let t={eq(r,n){return e.conditions.push({sql:`${r} = ?`,params:[n]}),t},neq(r,n){return e.conditions.push({sql:`${r} != ?`,params:[n]}),t},gt(r,n){return e.conditions.push({sql:`${r} > ?`,params:[n]}),t},gte(r,n){return e.conditions.push({sql:`${r} >= ?`,params:[n]}),t},lt(r,n){return e.conditions.push({sql:`${r} < ?`,params:[n]}),t},lte(r,n){return e.conditions.push({sql:`${r} <= ?`,params:[n]}),t},in(r,n){if(n.length===0)e.conditions.push({sql:"1 = 0",params:[]});else{let a=n.map(()=>"?").join(", ");e.conditions.push({sql:`${r} IN (${a})`,params:n})}return t},is(r,n){return n===null?e.conditions.push({sql:`${r} IS NULL`,params:[]}):e.conditions.push({sql:`${r} = ?`,params:[n?1:0]}),t},or(r){let n=A(r);return e.conditions.push(n),t},not(r,n,a){switch(n){case"eq":e.conditions.push({sql:`${r} != ?`,params:[a]});break;case"is":a===null&&e.conditions.push({sql:`${r} IS NOT NULL`,params:[]});break;default:e.conditions.push({sql:`NOT (${r} ${n} ?)`,params:[a]})}return t},order(r,n){let a=n?.ascending===!1?"DESC":"ASC";return e.orderClauses.push(`${r} ${a}`),t},limit(r){return e.limitValue=r,t},range(r,n){return e.rangeFrom=r,e.rangeTo=n,t},single(){return{then(r,n){try{let a=w(s,e,i,o,p,c,l),u=a.data;if(!u||Array.isArray(u)&&u.length===0){let d=f("Row not found","PGRST116");return Promise.resolve(d).then(r,n)}if(Array.isArray(u)&&u.length>1){let d=f("Multiple rows returned","PGRST116");return Promise.resolve(d).then(r,n)}let m=Array.isArray(u)?u[0]:u;return Promise.resolve(q(m,a.count)).then(r,n)}catch(a){let u=f(a.message);return n?Promise.resolve(u).then(r,n):Promise.resolve(u).then(r)}}}},maybeSingle(){return{then(r,n){try{let a=w(s,e,i,o,p,c,l),u=a.data;if(!u||Array.isArray(u)&&u.length===0)return Promise.resolve(q(null,a.count)).then(r,n);let m=Array.isArray(u)?u[0]:u;return Promise.resolve(q(m,a.count)).then(r,n)}catch(a){let u=f(a.message);return Promise.resolve(u).then(r,n)}}}},then(r,n){try{let a=w(s,e,i,o,p,c,l);return Promise.resolve(a).then(r,n)}catch(a){let u=f(a.message);return Promise.resolve(u).then(r,n)}}};return t}function w(s,e,i,o,p,c,l){let t=O(e),r=B(e),n=C(e);switch(i){case"select":{let a=o||"*";if(p?.head===!0&&p?.count==="exact"){let g=`SELECT COUNT(*) as count FROM ${e.table}${t.sql}`,h=s.prepare(g).get(...t.params);return{data:[],error:null,count:h.count}}let m=`SELECT ${a} FROM ${e.table}${t.sql}${r}${n}`,d=s.prepare(m).all(...t.params);d=d.map(g=>S(g));let T=null;if(p?.count==="exact"){let g=`SELECT COUNT(*) as count FROM ${e.table}${t.sql}`;T=s.prepare(g).get(...t.params).count}return{data:d,error:null,count:T}}case"insert":{let a=Array.isArray(c)?c:[c],u=[];for(let m of a){let d=m,T=Object.keys(d),g=T.map(R=>{let k=d[R];return k!==null&&typeof k=="object"?JSON.stringify(k):k}),h=T.map(()=>"?").join(", "),$=`INSERT INTO ${e.table} (${T.join(", ")}) VALUES (${h})`;s.prepare($).run(...g);let b=s.prepare("SELECT last_insert_rowid() as id").get(),E=s.prepare(`SELECT * FROM ${e.table} WHERE rowid = ?`).get(b.id);E&&u.push(S(E))}return{data:u,error:null}}case"update":{let a=l,u=Object.keys(a),m=u.map($=>`${$} = ?`).join(", "),d=u.map($=>{let b=a[$];return b!==null&&typeof b=="object"?JSON.stringify(b):b}),T=`UPDATE ${e.table} SET ${m}${t.sql}`;s.prepare(T).run(...d,...t.params);let g=`SELECT * FROM ${e.table}${t.sql}${r}${n}`,h=s.prepare(g).all(...t.params);return h=h.map($=>S($)),{data:h,error:null}}case"delete":{let a=`DELETE FROM ${e.table}${t.sql}`;return s.prepare(a).run(...t.params),{data:[],error:null}}}}function P(s,e){let i=e?.rpcHandlers??{};return{from(o){return{select(p,c){return y(s,{table:o,conditions:[],orderClauses:[]},"select",p,c)},insert(p){let c={table:o,conditions:[],orderClauses:[]};return{select(t){return y(s,c,"insert",t,void 0,p)},then(t,r){try{let n=w(s,c,"insert",void 0,void 0,p);return Promise.resolve({data:null,error:n.error}).then(t,r)}catch(n){let a=f(n.message);return Promise.resolve(a).then(t,r)}}}},update(p){let c={table:o,conditions:[],orderClauses:[]},t=y(s,c,"update",void 0,void 0,void 0,p);return t.select=r=>y(s,c,"update",r,void 0,void 0,p),t},delete(){return y(s,{table:o,conditions:[],orderClauses:[]},"delete")}}},rpc(o,p){let c=i[o];if(!c)return Promise.resolve(f(`RPC function '${o}' not registered`));try{let l=c(p??{});return Promise.resolve(q(l))}catch(l){return Promise.resolve(f(l.message))}}}}export{P as createSqliteAdapter};