# Mahana Devices — Vocabulary
*Words that work for Stephen Hawking AND Tony Stark. 2026-04-22.*

---

## The criterion

A word works if, when a non-technical human reads it, they know what it does for them, **and** when an agent reads it (in system prompts, API responses, observability), it knows what to do with it. If only one side understands it, it's cruft.

---

## `daemon` — "sounds like evil / background Linux plumbing"

**The problem**: scares users, tells agents nothing about identity, collides with CS-101 preconceptions.

**Proposals (ranked):**

1. **Service** — "Mahana Service" / "Mahana Runtime Service". Honest, industry-neutral, boring in the right way. Users know "service" from "printer service" / "iCloud service". Agents read `GET /service/health` and know exactly what it means. **Recommend.**
2. **Core** — "Mahana Core". Feels inner/essential. Less accurate (it's actually a background HTTP server, not "the core"), but more evocative. Marketing-friendly.
3. **Runtime** — "Mahana Runtime". Most technically accurate for what it does. Slightly dry.

**Runner-up considered and rejected**: "engine" (overloaded — think/engine already means the cascade), "agent" (already means something specific).

**Recommendation**: **Service** for user-facing surfaces (status bar, installer, error messages). Keep `daemon` in code identifiers (file names, plist names like `cc.mahana.daemon`) because changing those is a three-way-drift nightmare and the code never reaches the user.

---

## `sidecar` — "motorcycle metaphor no one asked for"

**The problem**: The only people who know this term are people who've read Istio/Envoy docs. Everyone else pictures a Harley.

**Proposals (ranked):**

1. **Capture** — literally what `mahana-capture` does: captures audio, screen, video from the OS. "Mahana Capture is what lets Mahana see and hear." **Recommend.** (This aligns with the existing repo name `~/mahana-ecosystem/mahana-capture/` — zero drift.)
2. **Senses** — "Mahana Senses". More evocative for the non-technical user ("it's how Mahana senses the world"). Slightly poetic.
3. **Bridge** — "Mahana Bridge". But "bridge" is already used in `src/main/bridge/electron-bridge.ts` for something else. Conflict → reject.

**Runner-up considered and rejected**: "ears + eyes" (two words = two parts; users need one noun), "recorder" (implies only recording).

**Recommendation**: **Capture** for code + CLI. **Senses** for marketing copy where it shows up alongside "Mahana Capture" as a subtitle.

---

## `substrate` — "chemistry-class word"

**The problem**: Zero intuition for what it does. The chemist user thinks it's a growth medium. The biologist thinks it's an enzyme target. The user thinks "I have no idea what this is."

**Proposals (ranked):**

1. **Fleet** — "Mahana Fleet". Already used extensively internally (mahana-fleet space, fleet-lead role, `mahana_fleet_tasks` table). Describes what substrate actually does: it is the coordinator for the fleet of agents across devices. Intuitive: user says "my fleet is doing X" naturally. **Recommend.**
2. **Exchange** — "Mahana Exchange". What substrate actually does technically is a task + heartbeat exchange. But it sounds financial.
3. **Mesh** — "Mahana Mesh". Captures the cross-device peer nature, but "mesh" is still dev-y.

**Runner-up considered and rejected**: "hub" (implies centralization — substrate is intentionally peer), "coordinator" (too dry).

**Recommendation**: **Fleet** for everything user-facing and for new code identifiers. Keep `substrate` in existing file names / service plists (three-way-drift avoidance), but stop using the word in user-visible prose.

---

## `session` — "database word. Tentative: Room. Validate or beat."

**The problem**: "Session" tells the user nothing about what it *is*. Databases have sessions. Browsers have sessions. The word has eroded.

**Proposal accepted: Room.** Validated against the criterion:

- **Human read**: "Alice's Room" / "the video editing room" / "my work room" — immediately means "a place I go to do a thing with someone in it". Aligns with the council-as-first-contact principle.
- **Agent read**: `GET /rooms?user_id=X` returns `[{id, name, capabilities, participants: [{agent_id, role}]}]`. Every API surface reads cleanly.
- **Metaphor extension**: "this room has camera" / "invite another agent to the room" / "leave this room" — all natural.

**Two acceptable alternates if "Room" gets pushback**:

1. **Workbench** — "my workbench". Good for builder/craftsman persona. Weaker for chat-only use.
2. **Space** — "my space". **BUT** "space" is already the top-level org primitive (mahana-core, mahana-cloud, etc. — 7 Spaces table in CLAUDE.md). Using "space" for session-level granularity would collide catastrophically. **Reject.**

**Recommendation**: **Room** in the UI and in all new code. Keep `session` in internal DB columns and type names (`SessionId`, `sessionId`) because migration is painful and the developer surface is different from the user surface. Write a vocab-mapping rule in a new `.claude/rules/room-is-the-ui-session.md` to prevent drift.

---

## `task queue` — "developer word"

**The problem**: "Task queue" makes users picture Trello or Jira. Neither is what we have. What we have is "things the fleet is currently doing, with a name each" — closer to a to-do list than a queue.

**Proposals (ranked):**

1. **Work** — "What work is Mahana doing?" Most natural English. Users say "the work" / "all the work" / "my work". Agents read `GET /work?status=pending` cleanly. **Recommend.**
2. **Errand** — "What errands did you send agents on?" Charming, but implies outside-the-house, which is wrong (fleet is inside).
3. **Run** — "Current runs" (borrowed from GitHub Actions / Temporal workflow). Accurate but jargon-adjacent.
4. **Drop** (suggested in task brief) — "drop" implies file transfer / handoff, not "in-progress work". Doesn't fit this slot; might fit elsewhere (file-drop folder already uses it).

**Recommendation**: **Work** for user-facing. Keep `tasks`/`taskQueue` in the DB/code (three-way-drift avoidance). "The fleet is working on 3 things" / "Work in progress: 2".

---

## `agent` — "loaded term. Keep or replace?"

**Argument to keep**: "agent" is now a mainstream term (ChatGPT agents, Claude agents, AI agents everywhere). Users know it means "an AI that does things for me". It's not scary anymore.

**Argument to replace**: it's so overloaded now that it's losing meaning. Also it doesn't say *what kind* of agent.

**Proposals:**

1. **Keep "agent"** as the generic term, but differentiate with role prefixes when the role matters: "Council agent", "Worker agent", "Brain agent", "Scribe agent". When the role doesn't matter, just "agent". **Recommend.**
2. **Teammate** — warmer, implies collaboration. But "teammate" is two agents' worth of anthropomorphism, which makes the Stephen-Hawking user who just wants the thing to type for them feel like they're being talked-at.
3. **Helper** — safe and accurate. Diminutive.

**Recommendation**: **Keep "agent"**, add role qualifiers when useful. Do NOT switch to a new term — the cost of vocab migration outweighs the (low) gain.

---

## `plugin` — "fine for devs. Keep."

**Agreed with brief.** Plugin is universal, understood, and accurate for what we mean (a module that adds capability to an existing system). No change.

**One note**: when a plugin is user-installable (not just dev-installable), call it an **"extension"** — matches Chrome/VSCode mental model. `Extensions` folder in the user's devices directory.

---

## Additional cruft identified in the sweep

Beyond the terms in the brief, the grep sweep surfaced a few more user-facing words that break the criterion:

### `notch` → **Dock** (or keep `Notch` macOS-specifically)

- "Notch" works on MacBook with-notch models and is charmingly specific. It fails on MacBook Air M2 (older, no physical notch), on Linux (no notch), on Windows.
- Recommendation: call the feature **Dock** (or "Mahana Dock") generically. Keep "notch" only when referring to the specific MacBook-Pro-with-notch positioning.

### `kappa (κ)` → **Coherence** (user-facing) / keep `κ` (internal)

- Greek letter works inside the fleet. Zero meaning to a new user.
- Recommendation: `κ` stays in code, receipts, neuropackets. User-visible dashboards show "Coherence: 0.71" with "κ" in small grey as attribution.

### `neuropacket` → **Note** (user-facing) / keep `neuropacket` (internal)

- Neuropacket is a technical artifact type. Users see it as "the thing Mahana remembers".
- Recommendation: in UI, `neuro_items` tagged `type=finding` show as "Notes". In code/API, keep `neuropacket` (three-way-drift avoidance — too many routes reference the name).

### `fleet-lead`, `backend-lead`, `frontend-lead`, etc. → **Lead** roles

- Already fine — user reads "Frontend Lead" and understands it's the specialist for UI work.

### `scar` → **Lesson** (user) / keep `scar` (internal)

- "Scar" is the project's internal culture word for "we burned ourselves, wrote it down". Users don't need to see the word. Show the body of scars as "Lessons" / "What we've learned".

### `harness` → **Runtime** or drop entirely

- "Harness" has no user-facing utility. Either use "Claude runtime" / "Agent runtime" or just don't mention it.

---

## Migration policy

**Change in UI prose and new code.** Do not rename files or DB columns — per `three-way-drift.md`, those migrations are painful and error-prone.

**Mapping table** (rule of thumb for future docs / UI work):

| Internal / code | User-facing |
|---|---|
| daemon | Service |
| substrate | Fleet |
| sidecar / mahana-capture | Capture (senses in copy) |
| session | Room |
| tasks / taskQueue | Work |
| agent | Agent (keep) |
| plugin | Plugin (keep) / Extension (user-installable) |
| notch | Dock (generic) / Notch (macOS-specific) |
| kappa (κ) | Coherence |
| neuropacket | Note |
| scar | Lesson |
| harness | Runtime |

**Enforcement**: add this table to `.claude/rules/vocabulary-canonical.md` so drift-sweepers pattern-match. New PRs that add daemon/substrate/session/task-queue/kappa in user-facing copy get bounced.

---

## Self-check: does this pass the Stephen Hawking / Tony Stark test?

**Stephen Hawking (cannot type)**: opens Mahana Devices, hears "I'm here. What do you want to do?" through speakers. Says (via eye-gaze keyboard or mic): "write an email". Council agent: "okay, to whom?" — user doesn't need to know what a daemon, a session, a task queue is. They're in a **room** with an **agent**, getting **work** done through their **senses**. Every user-facing word in that chain is plain English. **Passes.**

**Tony Stark (superbuilder)**: opens Mahana Desktop, looks at notch + island + editor + dashboard. Sees "Fleet: κ=0.71 · 12 agents · 4 working on edits". Drills into `GET /fleet/status` → same info with `kappa`, `agents`, `tasks` (internal terms). Runs `m kappa status` in terminal. Superbuilder has both surfaces: user prose when acting as a user, internal vocab when acting as a dev. **Passes.**

The split is: **prose uses user terms, code uses internal terms, documentation maps them.**