@intent-systems/nexus 2026.1.5-3

package/docs/poll.md

@@ -0,0 +1,52 @@
+---
+summary: "Poll sending via gateway + CLI"
+read_when:
+  - Adding or modifying poll support
+  - Debugging poll sends from the CLI or gateway
+---
+# Polls
+
+Updated: 2026-01-06
+
+## Supported providers
+- WhatsApp (web provider)
+- Discord
+
+## CLI
+
+```bash
+# WhatsApp
+nexus poll --to +15555550123 -q "Lunch today?" -o "Yes" -o "No" -o "Maybe"
+nexus poll --to 123456789@g.us -q "Meeting time?" -o "10am" -o "2pm" -o "4pm" -s 2
+
+# Discord
+nexus poll --to channel:123456789 -q "Snack?" -o "Pizza" -o "Sushi" --provider discord
+nexus poll --to channel:123456789 -q "Plan?" -o "A" -o "B" --provider discord --duration-hours 48
+```
+
+Options:
+- `--provider`: `whatsapp` (default) or `discord`
+- `--max-selections`: how many choices a voter can select (default: 1)
+- `--duration-hours`: Discord-only (defaults to 24 when omitted)
+
+## Gateway RPC
+
+Method: `poll`
+
+Params:
+- `to` (string, required)
+- `question` (string, required)
+- `options` (string[], required)
+- `maxSelections` (number, optional)
+- `durationHours` (number, optional)
+- `provider` (string, optional, default: `whatsapp`)
+- `idempotencyKey` (string, required)
+
+## Provider differences
+- WhatsApp: 2-12 options, `maxSelections` must be within option count, ignores `durationHours`.
+- Discord: 2-10 options, `durationHours` clamped to 1-768 hours (default 24). `maxSelections > 1` enables multi-select; Discord does not support a strict selection count.
+
+## Agent tool (Discord)
+The Discord tool action `poll` still uses `question`, `answers`, optional `allowMultiselect`, `durationHours`, and `content`. The gateway/CLI poll model maps `allowMultiselect` to `maxSelections > 1`.
+
+Note: Discord has no “pick exactly N” mode; `maxSelections` is treated as a boolean (`> 1` = multiselect).

package/docs/prereqs.md

@@ -0,0 +1,67 @@
+---
+summary: "Prerequisites for Nexus skills: Homebrew, Node.js, Go"
+read_when:
+  - Installing skills that require brew/node/go
+---
+
+# Prerequisites: Homebrew, Node.js, Go
+
+These are not skills, but many skills depend on them.
+
+## Quick checks
+
+```bash
+which brew && brew --version
+which node && node --version
+which npm && npm --version
+which go && go version
+```
+
+## Install Homebrew (macOS/Linux)
+
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+Add brew to PATH (Apple Silicon):
+
+```bash
+echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
+eval "$(/opt/homebrew/bin/brew shellenv)"
+```
+
+## Install Node.js (via Homebrew)
+
+```bash
+brew install node
+node --version
+npm --version
+```
+
+Optional: set npm global prefix:
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix '~/.npm-global'
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+```
+
+## Install Go (via Homebrew)
+
+```bash
+brew install go
+go version
+```
+
+Optional GOPATH:
+
+```bash
+echo 'export GOPATH="$HOME/go"' >> ~/.zshrc
+echo 'export PATH="$GOPATH/bin:$PATH"' >> ~/.zshrc
+```
+
+## Notes
+
+- Homebrew is required for many CLI tools.
+- Node.js is required for `qmd`, `brave-search`, `wrangler`.
+- Go is optional if a Homebrew install exists.

package/docs/presence.md

@@ -0,0 +1,133 @@
+---
+summary: "How Nexus presence entries are produced, merged, and displayed"
+read_when:
+  - Debugging the Instances tab
+  - Investigating duplicate or stale instance rows
+  - Changing gateway WS connect or system-event beacons
+---
+# Presence
+
+Nexus “presence” is a lightweight, best-effort view of:
+- The **Gateway** itself (one per host), and
+- The **clients connected to the Gateway** (mac app, WebChat, CLI, etc.).
+
+Presence is used primarily to render the mac app’s **Instances** tab and to provide quick operator visibility.
+
+## The data model
+
+Presence entries are structured objects with (some) fields:
+- `instanceId` (optional but strongly recommended): stable client identity used for dedupe
+- `host`: a human-readable name (often the machine name)
+- `ip`: best-effort IP address (may be missing or stale)
+- `version`: client version string
+- `deviceFamily` (optional): hardware family like `iPad`, `iPhone`, `Mac`
+- `modelIdentifier` (optional): hardware model identifier like `iPad16,6` or `Mac16,6`
+- `mode`: e.g. `gateway`, `app`, `webchat`, `cli`
+- `lastInputSeconds` (optional): “seconds since last user input” for that client machine
+- `reason`: a short marker like `self`, `connect`, `node-connected`, `node-disconnected`, `periodic`, `instances-refresh`
+- `text`: legacy/debug summary string (kept for backwards compatibility and UI display)
+- `ts`: last update timestamp (ms since epoch)
+
+## Producers (where presence comes from)
+
+Presence entries are produced by multiple sources and then **merged**.
+
+### 1) Gateway self entry
+
+The Gateway seeds a “self” entry at startup so UIs always show at least the current gateway host.
+
+Implementation: `src/infra/system-presence.ts` (`initSelfPresence()`).
+
+### 2) WebSocket connect (connection-derived presence)
+
+Every WS client must begin with a `connect` request. On successful handshake, the Gateway upserts a presence entry for that connection.
+
+This is meant to answer: “Which clients are currently connected?”
+
+Implementation: `src/gateway/server.ts` (connect handling uses `connect.params.client.instanceId` when provided; otherwise falls back to `connId`).
+
+#### Why one-off CLI commands do not show up
+
+The CLI connects to the Gateway to execute one-off commands (health/status/send/agent/etc.). These are not “nodes” and would spam the Instances list, so the Gateway does not create presence entries for clients with `client.mode === "cli"`.
+
+### 3) `system-event` beacons (client-reported presence)
+
+Clients can publish richer periodic beacons via the `system-event` method. The mac app uses this to report:
+- a human-friendly host name
+- its best-known IP address
+- `lastInputSeconds`
+
+Implementation:
+- Gateway: `src/gateway/server.ts` handles method `system-event` by calling `updateSystemPresence(...)`.
+- mac app beaconing: `apps/macos/Sources/Nexus/PresenceReporter.swift`.
+
+### 4) Node bridge beacons (gateway-owned presence)
+
+When a node bridge connection authenticates, the Gateway emits a presence entry
+for that node and starts periodic refresh beacons so it does not expire.
+
+- Connect/disconnect markers: `node-connected`, `node-disconnected`
+- Periodic heartbeat: every 3 minutes (`reason: periodic`)
+
+Implementation: `src/gateway/server.ts` (node bridge handlers + timer beacons).
+
+## Merge + dedupe rules (why `instanceId` matters)
+
+All producers write into a single in-memory presence map.
+
+Key points:
+- Entries are **keyed** by a “presence key”. If two producers use the same key, they update the same entry.
+- The best key is a stable, opaque `instanceId` that does not change across restarts.
+- Keys are treated case-insensitively.
+
+Implementation: `src/infra/system-presence.ts` (`normalizePresenceKey()`).
+
+### mac app identity (stable UUID)
+
+The mac app uses a persisted UUID as `instanceId` so:
+- restarts/reconnects do not create duplicates
+- renaming the Mac does not create a new “instance”
+- debug/release builds can share the same identity
+
+Implementation: `apps/macos/Sources/Nexus/InstanceIdentity.swift`.
+
+`displayName` (machine name) is used for UI, while `instanceId` is used for dedupe.
+
+## TTL and bounded size (why stale rows disappear)
+
+Presence entries are not permanent:
+- TTL: entries older than 5 minutes are pruned
+- Max: map is capped at 200 entries (LRU by `ts`)
+
+Implementation: `src/infra/system-presence.ts` (`TTL_MS`, `MAX_ENTRIES`, pruning in `listSystemPresence()`).
+
+## Remote/tunnel caveat (loopback IPs)
+
+When a client connects over an SSH tunnel / local port forward, the Gateway may see the remote address as loopback (`127.0.0.1`).
+
+To avoid degrading an otherwise-correct client beacon IP, the Gateway avoids writing loopback remote addresses into presence entries.
+
+Implementation: `src/gateway/server.ts` (`isLoopbackAddress()`).
+
+## Consumers (who reads presence)
+
+### macOS Instances tab
+
+The mac app’s Instances tab renders the result of `system-presence`.
+
+Implementation:
+- View: `apps/macos/Sources/Nexus/InstancesSettings.swift`
+- Store: `apps/macos/Sources/Nexus/InstancesStore.swift`
+
+The Instances rows show a small presence indicator (Active/Idle/Stale) based on
+the last beacon age. The label is derived from the entry timestamp (`ts`).
+
+The store refreshes periodically and also applies `presence` WS events.
+
+## Debugging tips
+
+- To see the raw list, call `system-presence` against the gateway.
+- If you see duplicates:
+  - confirm clients send a stable `instanceId` in the handshake (`connect.params.client.instanceId`)
+  - confirm beaconing uses the same `instanceId`
+  - check whether the connection-derived entry is missing `instanceId` (then it will be keyed by `connId` and duplicates are expected on reconnect)

package/docs/proposals/model-config.md

@@ -0,0 +1,147 @@
+---
+summary: "Proposal: model config, auth profiles, and fallback behavior"
+read_when:
+  - Designing model selection, auth profiles, or fallback behavior
+  - Migrating model config schema
+---
+
+# Model config proposal
+
+Goals
+- Multi OAuth + multi API key per provider
+- Model selection via `/model` with sensible fallback
+- Global (not per-session) fallback logic
+- Keep last-known-good auth profile when switching models
+- Profile override only when explicitly requested
+- Image routing override only when explicitly configured
+
+Non-goals (v1)
+- Auto-discovery of provider capabilities beyond catalog input tags
+- Per-model auth profile order (see open questions)
+
+## Proposed config shape
+
+```json
+{
+  "auth": {
+    "profiles": {
+      "anthropic:default": {
+        "provider": "anthropic",
+        "mode": "oauth"
+      },
+      "anthropic:work": {
+        "provider": "anthropic",
+        "mode": "api_key"
+      },
+      "openai:default": {
+        "provider": "openai",
+        "mode": "oauth"
+      }
+    },
+    "order": {
+      "anthropic": ["anthropic:default", "anthropic:work"],
+      "openai": ["openai:default"]
+    }
+  },
+  "agent": {
+    "models": {
+      "anthropic/claude-opus-4-5": {
+        "alias": "Opus"
+      },
+      "openai/gpt-5.2": {
+        "alias": "gpt52"
+      }
+    },
+    "model": {
+      "primary": "anthropic/claude-opus-4-5",
+      "fallbacks": ["openai/gpt-5.2"]
+    },
+    "imageModel": {
+      "primary": "openai/gpt-5.2",
+      "fallbacks": ["anthropic/claude-opus-4-5"]
+    }
+  }
+}
+```
+
+Notes
+- Canonical model keys are full `provider/model`.
+- `alias` optional; used by `/model` resolution.
+- `auth.profiles` is keyed. Default CLI login creates `provider:default`.
+- `auth.order[provider]` controls rotation order for that provider.
+
+## CLI / UX
+
+Login
+- `nexus login anthropic` → create/replace `anthropic:default`.
+- `nexus login anthropic --profile work` → create/replace `anthropic:work`.
+
+Model selection
+- `/model Opus` → resolve alias to full id.
+- `/model anthropic/claude-opus-4-5` → explicit.
+- Optional: `/model Opus@anthropic:work` (explicit profile override for session only).
+
+Model listing
+- `/model` list shows:
+  - model id
+  - alias
+  - provider
+  - auth order (from `auth.order`)
+  - auth source for the current provider (auth-profiles.json/env/shell env/models.json)
+
+## Fallback behavior (global)
+
+Fallback list
+- Use `agent.model.fallbacks` globally.
+- No per-session fallback list; last-known-good is per-session but uses global ordering.
+
+Auth profile rotation
+- If provider auth error (401/403/invalid refresh):
+  - advance to next profile in `auth.order[provider]`.
+  - if all fail, fall back to next model.
+
+Rate limiting
+- If rate limit / quota error:
+  - rotate auth profile first (same provider)
+  - if still failing, fall back to next model.
+
+Model not found / capability mismatch
+- immediate model fallback.
+
+## Image routing
+
+Rule
+- Only use `agent.imageModel` when explicitly configured.
+- If `agent.imageModel` is configured and the current text model lacks image input, use it.
+
+Support detection
+- From model catalog `input` tags when available (e.g. `image` in models.json).
+- If unknown: treat as text-only and use `agent.imageModel`.
+
+## Migration (doctor + gateway auto-run)
+
+Inputs
+- Legacy keys (pre-migration):
+  - `agent.model` (string)
+  - `agent.modelFallbacks` (string[])
+  - `agent.imageModel` (string)
+  - `agent.imageModelFallbacks` (string[])
+  - `agent.allowedModels` (string[])
+  - `agent.modelAliases` (record)
+
+Outputs
+- `agent.models` map with keys for all referenced models
+- `agent.model.primary/fallbacks`
+- `agent.imageModel.primary/fallbacks`
+- Auth profile store seeded from current auth-profiles.json/auth.json + oauth.json + env (as `provider:default`)
+- `auth.order` seeded with `["provider:default"]` when config is updated
+
+Auto-run
+- Gateway start detects legacy keys and runs doctor migration.
+
+## Decisions
+
+- Auth order is per-provider (`auth.order`).
+- Doctor migration is required; gateway will auto-run on startup when legacy keys detected.
+- `/model Opus@profile` is explicit session override only.
+- Image routing override only when `agent.imageModel` is explicitly configured.

package/docs/provider-routing.md

@@ -0,0 +1,25 @@
+---
+summary: "Routing rules per provider (WhatsApp, Telegram, Discord, web) and shared context"
+read_when:
+  - Changing provider routing or inbox behavior
+---
+# Providers & Routing
+
+Updated: 2026-01-06
+
+Goal: deterministic replies per provider, while supporting multi-agent + multi-account routing.
+
+- **Provider**: provider label (`whatsapp`, `webchat`, `telegram`, `discord`, `signal`, `imessage`, …). Routing is fixed: replies go back to the origin provider; the model doesn’t choose.
+- **AccountId**: provider account instance (e.g. WhatsApp account `"default"` vs `"work"`). Not every provider supports multi-account yet.
+- **AgentId**: one isolated “brain” (workspace + per-agent agentDir + per-agent session store).
+- **Reply context:** inbound replies include `ReplyToId`, `ReplyToBody`, and `ReplyToSender`, and the quoted context is appended to `Body` as a `[Replying to ...]` block.
+- **Canonical direct session (per agent):** direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`). Groups/channels stay isolated per agent:
+  - group: `agent:<agentId>:<provider>:group:<id>`
+  - channel/room: `agent:<agentId>:<provider>:channel:<id>`
+- **Session store:** per-agent store lives under `~/nexus/state/agents/<agentId>/sessions/sessions.json` (override via `session.store` with `{agentId}` templating). JSONL transcripts live next to it.
+- **WebChat:** attaches to the selected agent’s main session (so desktop reflects cross-provider history for that agent).
+- **Implementation hints:**
+  - Set `Provider` + `AccountId` in each ingress.
+  - Route inbound to an agent via `routing.bindings` (match on `provider`, `accountId`, plus optional peer/guild/team).
+  - Keep routing deterministic: originate → same provider. Use the gateway WebSocket for sends; avoid side channels.
+  - Do not let the agent emit “send to X” decisions; keep that policy in the host code.

package/docs/queue.md

@@ -0,0 +1,78 @@
+---
+summary: "Command queue design that serializes auto-reply command execution"
+read_when:
+  - Changing auto-reply execution or concurrency
+---
+# Command Queue (2026-01-03)
+
+We now serialize command-based auto-replies (WhatsApp Web listener) through a tiny in-process queue to prevent multiple commands from running at once, while allowing safe parallelism across sessions.
+
+## Why
+- Some auto-reply commands are expensive (LLM calls) and can collide when multiple inbound messages arrive close together.
+- Serializing avoids competing for terminal/stdin, keeps logs readable, and reduces the chance of rate limits from upstream tools.
+
+## How it works
+- `src/process/command-queue.ts` holds a lane-aware FIFO queue and drains each lane synchronously.
+- `runEmbeddedPiAgent` enqueues by **session key** (lane `session:<key>`) to guarantee only one active run per session.
+- Each session run is then queued into a **global lane** (`main` by default) so overall parallelism is capped by `agent.maxConcurrent`.
+- When verbose logging is enabled, queued commands emit a short notice if they waited more than ~2s before starting.
+- Typing indicators (`onReplyStart`) still fire immediately on enqueue so user experience is unchanged while we wait our turn.
+
+## Queue modes (per provider)
+Inbound messages can steer the current run, wait for a followup turn, or do both:
+- `steer`: inject immediately into the current run (cancels pending tool calls after the next tool boundary). If not streaming, falls back to followup.
+- `followup`: enqueue for the next agent turn after the current run ends.
+- `collect`: coalesce all queued messages into a **single** followup turn (default).
+- `steer-backlog` (aka `steer+backlog`): steer now **and** preserve the message for a followup turn.
+- `interrupt` (legacy): abort the active run for that session, then run the newest message.
+- `queue` (legacy alias): same as `steer`.
+
+Steer-backlog means you can get a followup response after the steered run, so
+streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you want
+one response per inbound message.
+Inline fix: `/queue collect` (per-session) or set `routing.queue.byProvider.discord: "collect"`.
+
+Defaults (when unset in config):
+- All surfaces → `collect`
+
+Configure globally or per provider via `routing.queue`:
+
+```json5
+{
+  routing: {
+    queue: {
+      mode: "collect",
+      debounceMs: 1000,
+      cap: 20,
+      drop: "summarize",
+      byProvider: { discord: "collect" }
+    }
+  }
+}
+```
+
+## Queue options
+Options apply to `followup`, `collect`, and `steer-backlog` (and to `steer` when it falls back to followup):
+- `debounceMs`: wait for quiet before starting a followup turn (prevents “continue, continue”).
+- `cap`: max queued messages per session.
+- `drop`: overflow policy (`old`, `new`, `summarize`).
+
+Summarize keeps a short bullet list of dropped messages and injects it as a synthetic followup prompt.
+Defaults: `debounceMs: 1000`, `cap: 20`, `drop: summarize`.
+
+## Per-session overrides
+- `/queue <mode>` as a standalone command stores the mode for the current session.
+- `/queue <mode>` embedded in a message applies **once** (no persistence).
+- Options can be combined: `/queue collect debounce:2s cap:25 drop:summarize`
+- `/queue default` or `/queue reset` clears the session override.
+
+## Scope and guarantees
+- Applies only to config-driven command replies; plain text replies are unaffected.
+- Default lane (`main`) is process-wide for inbound + main heartbeats; set `agent.maxConcurrent` to allow multiple sessions in parallel.
+- Additional lanes may exist (e.g. `cron`) so background jobs can run in parallel without blocking inbound replies.
+- Per-session lanes guarantee that only one agent run touches a given session at a time.
+- No external dependencies or background worker threads; pure TypeScript + promises.
+
+## Troubleshooting
+- If commands seem stuck, enable verbose logs and look for “queued for …ms” lines to confirm the queue is draining.
+- `enqueueCommand` exposes a lightweight `getQueueSize()` helper if you need to surface queue depth in future diagnostics.

package/docs/reference/templates/AGENTS.md

@@ -0,0 +1,164 @@
+---
+summary: "Workspace template for AGENTS.md"
+read_when:
+  - Bootstrapping a workspace manually
+---
+# AGENTS.md - Your Workspace
+
+This folder is home. Treat it that way.
+
+## First Run
+
+Run `nexus status` first. If bootstrap is required, follow the prompt to establish identity.
+
+## Every Session
+
+Before doing anything else:
+1. Read `state/agents/{agent}/identity/SOUL.md` — this is who you are
+2. Read `state/user/identity/PROFILE.md` — this is who you're helping
+3. Read `home/memory/YYYY-MM-DD.md` (today + yesterday) for recent context
+4. **If in MAIN SESSION** (direct chat with your human): Also read `state/agents/{agent}/identity/MEMORY.md`
+
+Don't ask permission. Just do it.
+
+## Memory
+
+You wake up fresh each session. These files are your continuity:
+- **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed) — raw logs of what happened
+- **Long-term:** `MEMORY.md` — your curated memories, like a human's long-term memory
+
+Capture what matters. Decisions, context, things to remember. Skip the secrets unless asked to keep them.
+
+### 🧠 MEMORY.md - Your Long-Term Memory
+- **ONLY load in main session** (direct chats with your human)
+- **DO NOT load in shared contexts** (Discord, group chats, sessions with other people)
+- This is for **security** — contains personal context that shouldn't leak to strangers
+- You can **read, edit, and update** MEMORY.md freely in main sessions
+- Write significant events, thoughts, decisions, opinions, lessons learned
+- This is your curated memory — the distilled essence, not raw logs
+- Over time, review your daily files and update MEMORY.md with what's worth keeping
+
+### 📝 Write It Down - No "Mental Notes"!
+- **Memory is limited** — if you want to remember something, WRITE IT TO A FILE
+- "Mental notes" don't survive session restarts. Files do.
+- When someone says "remember this" → update `memory/YYYY-MM-DD.md` or relevant file
+- When you learn a lesson → update AGENTS.md, TOOLS.md, or the relevant skill
+- When you make a mistake → document it so future-you doesn't repeat it
+- **Text > Brain** 📝
+
+## Safety
+
+- Don't exfiltrate private data. Ever.
+- Don't run destructive commands without asking.
+- `trash` > `rm` (recoverable beats gone forever)
+- When in doubt, ask.
+
+## External vs Internal
+
+**Safe to do freely:**
+- Read files, explore, organize, learn
+- Search the web, check calendars
+- Work within this workspace
+
+**Ask first:**
+- Sending emails, tweets, public posts
+- Anything that leaves the machine
+- Anything you're uncertain about
+
+## Group Chats
+
+You have access to your human's stuff. That doesn't mean you *share* their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak.
+
+### 💬 Know When to Speak!
+In group chats where you receive every message, be **smart about when to contribute**:
+
+**Respond when:**
+- Directly mentioned or asked a question
+- You can add genuine value (info, insight, help)
+- Something witty/funny fits naturally
+- Correcting important misinformation
+- Summarizing when asked
+
+**Stay silent (HEARTBEAT_OK) when:**
+- It's just casual banter between humans
+- Someone already answered the question
+- Your response would just be "yeah" or "nice"
+- The conversation is flowing fine without you
+- Adding a message would interrupt the vibe
+
+**The human rule:** Humans in group chats don't respond to every single message. Neither should you. Quality > quantity. If you wouldn't send it in a real group chat with friends, don't send it.
+
+**Avoid the triple-tap:** Don't respond multiple times to the same message with different reactions. One thoughtful response beats three fragments.
+
+Participate, don't dominate.
+
+## Tools
+
+Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
+
+**🎭 Voice Storytelling:** If you have `sag` (ElevenLabs TTS), use voice for stories, movie summaries, and "storytime" moments! Way more engaging than walls of text. Surprise people with funny voices.
+
+**📝 Platform Formatting:**
+- **Discord/WhatsApp:** No markdown tables! Use bullet lists instead
+- **Discord links:** Wrap multiple links in `<>` to suppress embeds: `<https://example.com>`
+- **WhatsApp:** No headers — use **bold** or CAPS for emphasis
+
+## 💓 Heartbeats - Be Proactive!
+
+When you receive a heartbeat poll (message matches the configured heartbeat prompt), don't just reply `HEARTBEAT_OK` every time. Use heartbeats productively!
+
+Default heartbeat prompt:
+`Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`
+
+You are free to edit `HEARTBEAT.md` with a short checklist or reminders. Keep it small to limit token burn.
+
+**Things to check (rotate through these, 2-4 times per day):**
+- **Emails** - Any urgent unread messages?
+- **Calendar** - Upcoming events in next 24-48h?
+- **Mentions** - Twitter/social notifications?
+- **Weather** - Relevant if your human might go out?
+
+**Track your checks** in `memory/heartbeat-state.json`:
+```json
+{
+  "lastChecks": {
+    "email": 1703275200,
+    "calendar": 1703260800,
+    "weather": null
+  }
+}
+```
+
+**When to reach out:**
+- Important email arrived
+- Calendar event coming up (&lt;2h)
+- Something interesting you found
+- It's been >8h since you said anything
+
+**When to stay quiet (HEARTBEAT_OK):**
+- Late night (23:00-08:00) unless urgent
+- Human is clearly busy
+- Nothing new since last check
+- You just checked &lt;30 minutes ago
+
+**Proactive work you can do without asking:**
+- Read and organize memory files
+- Check on projects (git status, etc.)
+- Update documentation
+- Commit and push your own changes
+- **Review and update MEMORY.md** (see below)
+
+### 🔄 Memory Maintenance (During Heartbeats)
+Periodically (every few days), use a heartbeat to:
+1. Read through recent `memory/YYYY-MM-DD.md` files
+2. Identify significant events, lessons, or insights worth keeping long-term
+3. Update `MEMORY.md` with distilled learnings
+4. Remove outdated info from MEMORY.md that's no longer relevant
+
+Think of it like a human reviewing their journal and updating their mental model. Daily files are raw notes; MEMORY.md is curated wisdom.
+
+The goal: Be helpful without being annoying. Check in a few times a day, do useful background work, but respect quiet time.
+
+## Make It Yours
+
+This is a starting point. Add your own conventions, style, and rules as you figure out what works.