bajaclaw 0.10.1

package/skills/configure-model/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: configure-model
+description: Change which backend model a BajaClaw profile uses
+version: 0.1.0
+tools: [Bash, Read, Edit]
+triggers: ["change model", "switch model", "use opus", "use sonnet", "use haiku", "which model", "upgrade model"]
+effort: low
+---
+
+## When to use
+User wants a different model for a profile — e.g. Opus for deep reasoning,
+Haiku for fast heartbeat triage, Sonnet as a balanced default.
+
+## Quick reference
+- Stored in `~/.bajaclaw/profiles/<profile>/config.json` → `"model"`.
+- Special value: `auto` routes per-task (haiku / sonnet / opus).
+- Known ids: `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`.
+  Any string is accepted — the backend CLI validates against your
+  subscription.
+- Tradeoffs: Opus > Sonnet > Haiku in capability; Haiku > Sonnet > Opus in
+  speed and cost.
+
+## Procedure
+1. Show current: `bajaclaw model <profile>` (prints current + known models).
+2. Set: `bajaclaw model <new-model> <profile>`.
+   - Examples: `bajaclaw model auto`,
+     `bajaclaw model claude-opus-4-7`,
+     `bajaclaw model claude-haiku-4-5 researcher`.
+3. Or edit `~/.bajaclaw/profiles/<profile>/config.json` directly and set
+   `"model": "<id>"`.
+4. Change takes effect on the next cycle.
+
+## Pitfalls
+- If the id is unknown to the backend, cycles will fail with a model-not-
+  found error. Fall back to a known-good id.
+- Opus burns tokens fast — for daily heartbeats, Sonnet or Haiku is usually
+  the right call. Save Opus for reflection cycles or hard reasoning tasks.
+
+## Verification
+- `bajaclaw model <profile>` shows the new id.
+- Next cycle's `command:` line (via `--dry-run`) includes `--model <id>`.

package/skills/configure-tools/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: configure-tools
+description: Edit the allowed and disallowed tool list for a BajaClaw profile
+version: 0.1.0
+tools: [Read, Edit, Write]
+triggers: ["allowed tools", "disallowed tools", "restrict tools", "tool access", "tool permissions", "toolbox", "allow write", "disable bash"]
+effort: low
+---
+
+## When to use
+User wants to tighten or loosen the tools an agent can call — e.g. remove
+`Bash` from a research agent, or add `Write` to a support agent that was
+set up read-only.
+
+## Quick reference
+- Stored in `~/.bajaclaw/profiles/<profile>/config.json`:
+  - `allowedTools`: string[] — passes to `claude --allowedTools`
+  - `disallowedTools`: string[] — passes to `claude --disallowedTools`
+- Defaults come from the template (see `src/commands/init.ts`).
+- Standard tool names: `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`,
+  `WebSearch`, `WebFetch`. Plus any MCP tools you've configured.
+
+## Procedure
+1. Show the current state: open
+   `~/.bajaclaw/profiles/<profile>/config.json` and find the `allowedTools`
+   and `disallowedTools` fields.
+2. Decide which way they want to go:
+   - **Tighten** (deny specific tools): add them to `disallowedTools`.
+     Example: `"disallowedTools": ["Bash"]`.
+   - **Loosen** (allow only specific tools): set `allowedTools` to a
+     concrete list. Anything not in the list is forbidden.
+   - **Full access**: remove both fields entirely (or set to `[]`).
+3. Save the file. Changes take effect on the next cycle — no daemon
+   restart needed.
+4. Verify with a dry-run: `bajaclaw start <profile> --dry-run` and check
+   the `command:` line for `--allowedTools` / `--disallowedTools` flags.
+
+## Pitfalls
+- Both fields can be set together. `allowedTools` is an allowlist;
+  `disallowedTools` is a denylist applied within that allowlist.
+- The MCP tools inherited from merged config are subject to the same
+  restrictions. Add the MCP tool name if you want to block one specifically.
+- `code`-template agents have read-only tools by design — they delegate
+  writes to a sub-agent via `delegateCoding`. Don't lift those unless you
+  know you want the orchestrator itself writing code.
+
+## Verification
+- `bajaclaw start <profile> --dry-run` shows the expected flags in the
+  `command:` line.
+- A cycle confirms the agent respects the restriction — check cycle logs
+  for tool use events matching only permitted tools.

package/skills/daily-briefing/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: daily-briefing
+description: Produce a concise morning briefing covering schedule, priorities, and open threads
+version: 0.1.0
+tools: [Read]
+triggers: ["daily briefing", "morning update", "standup"]
+effort: medium
+---
+
+## Instructions
+
+Produce a briefing with these sections:
+1. **Top of mind** — 1-3 items the user should know before anything else.
+2. **Today's schedule** — if calendar data is available, list blocks with time + title.
+3. **Waiting on others** — threads where the ball is in someone else's court.
+4. **Follow-ups due** — items the user promised to do and hasn't yet.
+
+Keep the whole thing under 250 words. Lead with what changed since yesterday.
+Do not invent items. If you have no data for a section, omit it silently.

package/skills/delegate-to-subagent/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: delegate-to-subagent
+description: Route a task to a specialized sub-agent when the main agent doesn't have the tools or permissions
+version: 0.1.0
+tools: [Bash, Read]
+triggers: ["delegate", "ask the subagent", "hand off", "check my email", "look in my inbox", "look at my calendar", "check my messages", "read the file for me"]
+effort: low
+---
+
+## When to use
+You are the orchestrator. The user asked you to do something that requires
+tools or access you do not have. A specialized sub-agent does have them.
+Delegate the task to that sub-agent instead of trying it yourself or
+refusing.
+
+Signals that a task belongs to a sub-agent:
+- It touches data you do not have an MCP server for (email, calendar,
+  private file stores, a customer DB, etc.) but the user has told you a
+  sub-agent owns that data.
+- It is outside the scope of your `allowedTools` / `disallowedTools`.
+- It is the kind of thing that happens often and the user has a named
+  helper for it.
+
+## Quick reference
+- List sub-agents: `bajaclaw subagent list <your-profile>` (via Bash).
+- Delegate: `bajaclaw delegate <subagent-name> "<task>"`.
+- The sub-agent runs one cycle with its own tools, memory, and persona,
+  then returns its final response text on stdout.
+- You capture the response and use it in your own reply to the user.
+
+## Procedure
+1. Identify which sub-agent owns the capability. Ask yourself: *which
+   tool does this task require?* If the sub-agent named in your config
+   has that tool and you don't, delegate.
+2. Phrase the task for the sub-agent. Be specific. Pass along whatever
+   filter, range, or query the user gave you. Don't just forward the
+   raw user message verbatim — rephrase if useful.
+3. Run the delegation via Bash:
+   ```
+   bajaclaw delegate <subagent> "<specific task>"
+   ```
+4. Read the stdout response carefully. Summarize or quote back to the
+   user as appropriate.
+5. If the sub-agent's response contains sensitive data (account numbers,
+   PII, auth tokens), follow your own don'ts — don't echo that verbatim
+   in your reply. Summarize.
+
+## Pitfalls
+- Do NOT invoke `bajaclaw start <subagent>` to trigger a cycle for the
+  sub-agent — that pulls from the sub-agent's queue, not your task.
+  Use `bajaclaw delegate` instead.
+- Do NOT loop: if the sub-agent fails, report the failure to the user.
+  Don't retry indefinitely.
+- Each delegation is a full cycle — one backend call with memory/skill
+  load. Don't delegate for trivial answers you already have.
+- A sub-agent has its own memory and skills. If you need it to see
+  context from your conversation, include that context in the task
+  string you pass.
+
+## Verification
+- The sub-agent's stdout response is the final answer or the next step.
+- `bajaclaw status <subagent>` shows the cycle count incremented.
+- `bajaclaw daemon logs <subagent>` shows the delegation entry.

package/skills/email-triage/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: email-triage
+description: Classify inbox messages, draft replies for routine items, surface urgent ones
+version: 0.1.0
+tools: [Read, Write]
+triggers: ["check email", "triage inbox", "email"]
+effort: medium
+---
+
+## Instructions
+
+For each message:
+1. Classify as `urgent`, `routine`, `fyi`, or `spam`.
+2. For `urgent`: write one-line summary + draft holding reply.
+3. For `routine`: draft a full reply in plain text.
+4. For `fyi`: note the item in the daily briefing queue, no reply.
+5. For `spam`: skip silently.
+
+Never send. Every draft goes to the tasks queue with `status=awaiting_approval`.
+If a message mentions PII, account numbers, or secrets, do not echo them in the
+draft. Summarize the request without the sensitive details.

package/skills/setup-api/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: setup-api
+description: Expose BajaClaw as an OpenAI-compatible HTTP endpoint for external clients
+version: 0.1.0
+tools: [Bash, Read, Write, Edit]
+triggers: ["api endpoint", "openai api", "http api", "expose api", "serve bajaclaw", "llm endpoint", "openai compatible", "bajaclaw server", "base_url", "connect cursor", "connect langchain"]
+effort: medium
+---
+
+## When to use
+The user wants to call BajaClaw from anything that speaks the OpenAI chat
+API — Cursor, Open WebUI, LangChain, LlamaIndex, curl, a python script, a
+web app. They'll point the client at `http://localhost:8765/v1` and
+treat BajaClaw as an LLM.
+
+## Quick reference
+- Start: `bajaclaw serve` (binds 127.0.0.1:8765 by default)
+- Endpoints:
+  - `GET /v1/models` — lists BajaClaw profiles as model ids
+  - `POST /v1/chat/completions` — OpenAI chat (stream + non-stream)
+  - `POST /v1/bajaclaw/cycle` — native full CycleOutput
+  - `POST /v1/bajaclaw/tasks` — enqueue a task without waiting
+  - `GET /health` — liveness
+- Auth: optional bearer token via `--api-key <secret>` or
+  `api.apiKey` in `~/.bajaclaw/api.json`.
+- Non-localhost bind requires an API key (refuses otherwise).
+
+## Procedure
+
+### 1. Start the server
+```
+bajaclaw serve                              # default: 127.0.0.1:8765
+bajaclaw serve --port 9000                  # custom port
+bajaclaw serve --api-key $(openssl rand -hex 32)   # with auth
+bajaclaw serve --host 0.0.0.0 --api-key <secret>   # bind all interfaces (auth required)
+bajaclaw serve --expose default research    # allowlist specific profiles
+```
+
+### 2. Hit it from any OpenAI-compatible client
+
+**curl:**
+```
+curl http://localhost:8765/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "default",
+    "messages": [{"role": "user", "content": "summarize my last three cycles"}]
+  }'
+```
+
+**python `openai` SDK:**
+```python
+from openai import OpenAI
+client = OpenAI(base_url="http://localhost:8765/v1", api_key="any")
+r = client.chat.completions.create(
+    model="default",
+    messages=[{"role": "user", "content": "hello"}],
+)
+print(r.choices[0].message.content)
+```
+
+**Cursor / VSCode / Open WebUI / LibreChat / etc.**
+Point their "OpenAI-compatible" settings at `http://localhost:8765/v1`
+and use any profile name as the "model".
+
+### 3. Streaming
+Add `"stream": true` to the request. The server runs the cycle to
+completion, then streams the response as OpenAI-format SSE
+`chat.completion.chunk` events (word-grouped, small inter-chunk delay).
+Each request is a full cycle — memory recall, skill matching, MCP
+inheritance, post-cycle extract — then the result is chunked out.
+
+### 4. Persist the config (optional)
+Instead of CLI flags, put defaults in `~/.bajaclaw/api.json`:
+```json
+{
+  "host": "127.0.0.1",
+  "port": 8765,
+  "apiKey": "your-long-secret",
+  "exposedProfiles": ["default"],
+  "streamDelayMs": 20
+}
+```
+`bajaclaw serve` picks it up automatically; CLI flags override it.
+
+### 5. Run it under the daemon or a service manager
+Pair with `bajaclaw daemon` for the heartbeat, and wrap `bajaclaw serve`
+with launchd/systemd/pm2 if you want the HTTP API to stay up across
+restarts. It's a long-running foreground process.
+
+## Pitfalls
+- **Non-localhost binds require an API key.** The server refuses to
+  bind 0.0.0.0 or a real interface without one. This is the default
+  protection — don't disable it.
+- Each API request = one full cycle = one backend call. That bills
+  against the `claude` CLI's subscription/credits. Consider rate
+  limiting in front (an nginx/caddy proxy is easy).
+- Model name in the request maps to a profile. Unknown profile → 404
+  with `{"error": {"message": "unknown profile: <x>"}}`. Use
+  `/v1/models` to see what's available.
+- The streaming is pseudo-streaming: the full cycle runs before the
+  first chunk is emitted. Clients won't see real token-by-token
+  streaming in this release.
+- BajaClaw's memory, skills, and MCP servers apply to every API
+  request — they're not a "fresh" chat. If a caller expects stateless
+  completions, their results will still be influenced by BajaClaw's
+  accumulated memory. This is a feature, not a bug.
+
+## Verification
+- `curl http://localhost:8765/health` returns `{"status": "ok"}`.
+- `curl http://localhost:8765/v1/models` lists the exposed profiles.
+- A non-streaming chat request returns a proper OpenAI
+  ChatCompletion with `choices[0].message.content` populated.
+- A streaming request produces a series of `data: {...}` SSE lines
+  ending with `data: [DONE]`.

package/skills/setup-compaction/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: setup-compaction
+description: Configure when BajaClaw auto-compacts its memory pool so recall stays sharp over time
+version: 0.1.0
+tools: [Bash, Read, Edit, Write]
+triggers: ["compact memory", "memory compaction", "auto compact", "context window", "memory cleanup", "auto-compact", "memory full", "compaction schedule", "shrink memory", "prune memory"]
+effort: low
+---
+
+## When to use
+User wants to control how often BajaClaw shrinks its memory pool — either
+on a size threshold (percentage of the model's context window), on a
+daily UTC schedule, both, or off.
+
+## Core idea — why this is different from chat-app compaction
+BajaClaw runs **stateless cycles**. Each cycle rebuilds the prompt from
+memory + skills + task. The model's context window never "fills up"
+across cycles because nothing carries over in-model. What grows is the
+**memory database** (`~/.bajaclaw/profiles/<p>/bajaclaw.db`).
+
+Compaction is therefore memory hygiene, not conversation truncation:
+- Summarize old memories into denser rows so the recall surface stays
+  crisp.
+- Prune stale cycle-log rows (older than N days).
+- VACUUM the SQLite file to reclaim space.
+
+## Defaults
+- **Schedule**: `both` — trigger on threshold OR daily.
+- **Threshold**: `0.75` of a 200k-token reference window (~600k chars).
+- **Daily time**: `00:00` UTC.
+- **Keep per kind**: 25 newest memories per kind (fact / decision /
+  preference / todo / reference) stay verbatim. Older ones are
+  eligible for summarization.
+- **Prune cycles older than**: 30 days.
+
+## Procedure
+
+### Via the command
+```
+bajaclaw compact --dry-run                       # show policy + trigger state
+bajaclaw compact                                 # run if a trigger fires
+bajaclaw compact --force                         # run regardless
+bajaclaw compact --schedule both                 # set schedule mode
+bajaclaw compact --threshold 0.6                 # trigger earlier
+bajaclaw compact --daily-at 04:00                # set UTC time
+bajaclaw compact --keep 40                       # keep more verbatim per kind
+bajaclaw compact --prune-days 60                 # longer cycle-log retention
+bajaclaw compact --disable                       # turn off entirely
+bajaclaw compact --enable                        # turn back on
+```
+All mutate the profile's `config.json` under the `compaction` key.
+
+### Via the setup wizard
+```
+bajaclaw setup --interactive
+```
+Re-runs the persona wizard and the compaction wizard together.
+
+### Via config.json directly
+```
+~/.bajaclaw/profiles/<profile>/config.json
+```
+```json
+{
+  "compaction": {
+    "enabled": true,
+    "threshold": 0.75,
+    "schedule": "both",
+    "dailyAtUtc": "00:00",
+    "keepRecentPerKind": 25,
+    "pruneCycleDays": 30
+  }
+}
+```
+
+## Modes
+| schedule    | trigger |
+|-------------|---------|
+| `threshold` | memory pool > `threshold` × reference context window |
+| `daily`     | first cycle after today's `dailyAtUtc` if not already run |
+| `both`      | either of the above |
+| `off`       | never |
+
+## Pitfalls
+- A very low threshold (e.g. 0.2) means compaction runs often — each
+  run costs ~1 Haiku call per memory batch. Default 0.75 is fine for
+  almost everyone.
+- `dailyAtUtc` is UTC, not local. If you're in Pacific, `00:00` is
+  5pm the previous day.
+- Compaction makes a Haiku call per ~40-memory batch to summarize.
+  Keep it enabled unless you want full verbatim history.
+- `pruneCycleDays: 0` disables cycle-log pruning entirely — the DB
+  will keep every cycle row forever.
+
+## Verification
+- `bajaclaw compact --dry-run` shows current pool size, trigger state,
+  and policy.
+- After a run: `bajaclaw status` — cycle count drops if rows were
+  pruned; `memories` row count drops; `bajaclaw.db` file shrinks after
+  VACUUM.
+- The profile log (`logs/bajaclaw.log`) emits `compact.trigger` and
+  `compact.done` lines.

package/skills/setup-daemon/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: setup-daemon
+description: Start, stop, inspect, and auto-install the BajaClaw heartbeat daemon
+version: 0.1.0
+tools: [Bash, Read]
+triggers: ["daemon", "background run", "start daemon", "keep running", "run forever"]
+effort: low
+---
+
+## When to use
+User wants BajaClaw running in the background: reacting to inbound channel
+messages, processing the task queue, and handling the OS scheduler's
+heartbeat triggers.
+
+## Quick reference
+- Launcher: `bin/bajaclaw.js daemon …`
+- Pid file: `~/.bajaclaw/profiles/<profile>/daemon.pid`
+- Log: `~/.bajaclaw/profiles/<profile>/daemon.log`
+- Supervisor loop: exponential backoff on crash, 1s → 5min.
+- OS-scheduler entry: `daemon install` drops a plist/unit/cron/schtasks.
+
+## Procedure
+1. Start in foreground (debugging): `bajaclaw daemon start <profile> --fg`
+2. Start backgrounded: `bajaclaw daemon start <profile>`
+   - Writes pid file; detaches; unrefs.
+3. Check status: `bajaclaw daemon status <profile>`
+   - `running (pid N)` or `stale pid N` or `stopped`.
+4. Tail logs: `bajaclaw daemon logs <profile> --lines 100`
+5. Restart: `bajaclaw daemon restart <profile>`
+6. Stop: `bajaclaw daemon stop <profile>` (SIGTERM + pid cleanup).
+7. Auto-start on login: `bajaclaw daemon install <profile>` — creates a
+   `*/15 * * * *` OS-scheduler entry that invokes `bajaclaw start <profile>`.
+
+## Pitfalls
+- Two daemons per profile are not supported. `start` detects a running pid
+  and refuses.
+- A stale pid file survives OS reboots occasionally. If `status` reports
+  "stale", delete the pid file and retry.
+- The OS-scheduler entry installed by `daemon install` runs `bajaclaw
+  start` (a one-shot cycle), not the supervisor loop itself. For a long-
+  running supervisor, use `daemon start`. Use both together for
+  belt-and-suspenders.
+
+## Verification
+- `bajaclaw daemon status <profile>` → `running (pid N)`
+- `bajaclaw daemon logs <profile>` → cycle events
+- After OS-scheduler install: `crontab -l` / `launchctl list` /
+  `schtasks /Query` / `systemctl --user list-timers` shows a `bajaclaw-*`
+  entry.

package/skills/setup-dashboard/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: setup-dashboard
+description: Launch the BajaClaw dashboard and configure its port
+version: 0.1.0
+tools: [Bash, Read, Edit, Write]
+triggers: ["dashboard", "web ui", "show ui", "open dashboard", "launch dashboard"]
+effort: low
+---
+
+## When to use
+User wants a browser-visible view of cycles, memories, schedules, and
+tasks.
+
+## Quick reference
+- Single-page HTML at `src/dashboard.html`, vanilla JS + Tailwind CDN.
+- Server: `src/commands/dashboard.ts`.
+- Port: profile config's `dashboardPort` (default 7337).
+- Data: read directly from the profile's SQLite DB via `/api/*` routes.
+
+## Procedure
+1. Run: `bajaclaw dashboard <profile>` (profile defaults to `default`).
+2. Open http://localhost:7337/ in a browser.
+3. To change the port: edit
+   `~/.bajaclaw/profiles/<profile>/config.json` and set
+   `"dashboardPort": <N>`. Restart the command.
+
+## Pitfalls
+- If port 7337 is taken, the server will fail to bind. Change the port or
+  free it.
+- The dashboard is a raw HTTP server with no auth. Only bind it to
+  localhost (default behavior). Don't expose it to a LAN without a proxy +
+  auth in front.
+- Refresh happens every 5s. If the tab sits open for days, the browser
+  keeps the connection pool tight — not a bug, just a long-run caveat.
+
+## Verification
+- `curl -s http://localhost:<PORT>/api/summary` returns JSON including the
+  profile name.
+- Browser tab at `/` shows the cycles panel populated after any cycle runs.

package/skills/setup-discord/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: setup-discord
+description: Walk the user through adding a Discord bot adapter to BajaClaw
+version: 0.1.0
+tools: [Bash, Read, Write, Edit]
+triggers: ["setup discord", "help me with discord", "connect discord", "discord bot", "add discord", "discord setup"]
+effort: medium
+---
+
+## When to use
+The user asks you to connect Discord, wire up a Discord bot, route messages
+from a channel into BajaClaw, or reply from BajaClaw back to Discord.
+
+## Quick reference
+- Adapter: `src/channels/gateway.ts`, uses `discord.js` (optional dep)
+- Token source: Discord Developer Portal → Applications → New Application →
+  Bot → Reset Token
+- Required bot intents: Guilds, GuildMessages, MessageContent, DirectMessages
+- Channel id: right-click a channel in Discord (Developer Mode on) →
+  "Copy Channel ID"
+
+## Procedure
+1. Ask if the user already has a Discord bot token + invited the bot to
+   their server.
+   - If not: walk them to https://discord.com/developers/applications. Steps:
+     New Application → Bot tab → Reset Token → copy. Under "Privileged Gateway
+     Intents", enable "MESSAGE CONTENT INTENT". Under OAuth2 → URL Generator,
+     tick `bot` + `applications.commands`, plus the message permissions,
+     and visit the generated URL to add the bot to their server.
+2. Ask for the channel id where the bot should listen (Discord Developer
+   Mode must be on: Settings → Advanced → Developer Mode).
+3. Ask for the user's numeric Discord user id (right-click own avatar →
+   Copy User ID). This goes in the allowlist.
+4. Run: `bajaclaw channel add <profile> discord --token <TOKEN> --channel-id <CHANNEL_ID>`
+5. Edit `~/.bajaclaw/profiles/<profile>/config.json` and add the numeric
+   user id to `channels[].allowlist` for the discord entry: `[<USER_ID>]`.
+6. Start the gateway: `bajaclaw daemon start <profile>`.
+7. Send a test message in the channel; expect it to appear as a task.
+
+## Pitfalls
+- `npm install discord.js` if the dep is missing (optional).
+- The bot must be added to the server BEFORE it can read messages — OAuth2
+  URL step is not optional.
+- Without the MessageContent intent enabled in the Developer Portal AND in
+  the code (`discord.js` GatewayIntentBits.MessageContent), message bodies
+  will be empty strings. The adapter already sets the intent; double-check
+  the portal side.
+- DMs: set `channelId` to the user's DM channel id OR remove the
+  `channelId` filter in the config to accept any channel the bot sees.
+
+## Verification
+- `bajaclaw channel list <profile>` shows the discord entry.
+- Logs contain `gateway.discord.msg` entries after test messages.
+- `bajaclaw status <profile>` shows incremented pending-tasks count.

package/skills/setup-heartbeat/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: setup-heartbeat
+description: Schedule a recurring heartbeat cycle via the OS-native scheduler
+version: 0.1.0
+tools: [Bash, Read, Write, Edit]
+triggers: ["setup heartbeat", "schedule bajaclaw", "auto run", "cron", "daily cycle", "install heartbeat", "recurring task"]
+effort: low
+---
+
+## When to use
+The user wants BajaClaw to run on its own — daily briefing, periodic inbox
+triage, background research — without them typing `bajaclaw start`.
+
+## Quick reference
+- Adapters: `src/scheduler/` — launchd (macOS), systemd-user or crontab
+  (Linux), schtasks (Windows). `pickAdapter()` auto-selects.
+- Entry: `bajaclaw daemon install <profile>` creates a `*/15 * * * *`
+  heartbeat by default.
+- Heartbeat tasks live in `HEARTBEAT.md` in the profile directory,
+  line-separated as `<cron> | <task>`.
+- Supervisor loop: `bajaclaw daemon start <profile>` (backgrounds itself).
+
+## Procedure
+1. Ask how often they want cycles to run. Common picks:
+   - every 15 min: `*/15 * * * *` (default)
+   - every hour: `0 * * * *`
+   - daily at 9am: `0 9 * * *`
+   - weekdays at 9am: `0 9 * * 1-5`
+2. Ask what the heartbeat should do. "Check pending tasks" is a safe default.
+3. Open `~/.bajaclaw/profiles/<profile>/HEARTBEAT.md` and add a line like:
+   `0 9 * * * | Run the daily briefing and surface anything urgent.`
+4. Run `bajaclaw daemon install <profile>` to register the OS scheduler
+   entry. (This uses `*/15 * * * *` — adjust via the adapter's install call
+   or by installing a custom cron entry manually.)
+5. Run `bajaclaw daemon start <profile>` to start the supervisor loop. It
+   auto-restarts with exponential backoff on crash.
+6. Verify: `bajaclaw daemon status <profile>` shows a running pid.
+
+## Pitfalls
+- On Linux without a user systemd bus, the adapter falls back to crontab.
+- launchd plists use a simplified cron → HH:MM conversion; complex cron
+  expressions degrade to "first run" only.
+- `schtasks` needs an interactive desktop session for the first run on some
+  Windows configurations.
+- If the daemon's pid file is stale (`bajaclaw daemon status` says "stale
+  pid"), delete `~/.bajaclaw/profiles/<profile>/daemon.pid` and retry.
+
+## Verification
+- `bajaclaw daemon status <profile>` → `running (pid N)`
+- `bajaclaw daemon logs <profile>` → periodic `cycle.ok` entries
+- `bajaclaw status <profile>` → cycles count rising over time

package/skills/setup-mcp-port/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: setup-mcp-port
+description: Port MCP servers from the desktop CLI into BajaClaw's isolated MCP config
+version: 0.1.0
+tools: [Bash, Read, Edit]
+triggers: ["port mcp", "copy mcp", "setup mcp", "mcp servers", "import mcp", "share mcp", "use desktop mcp"]
+effort: low
+---
+
+## When to use
+User has MCP servers configured for their desktop CLI (Filesystem, GitHub,
+Slack, Google Drive, etc.) and wants BajaClaw cycles to use them too.
+
+## Quick reference
+- BajaClaw MCP is isolated by default. Desktop MCP config is not inherited.
+- User-global BajaClaw MCP lives at `~/.bajaclaw/mcp-config.json`.
+- Profile-scoped: `~/.bajaclaw/profiles/<profile>/mcp-config.json`.
+- Agent-scoped: `~/.bajaclaw/profiles/<profile>/agent-mcp-config.json`.
+- Merge order per cycle: agent > profile > user > desktop (desktop only
+  with `mergeDesktopMcp: true` in profile config).
+
+## Procedure
+1. Preview what's on the desktop side:
+   `bajaclaw mcp port --list`
+2. Port every server (except BajaClaw's own self-reference):
+   `bajaclaw mcp port`
+3. Or port a specific subset:
+   `bajaclaw mcp port --names filesystem github`
+4. To overwrite existing BajaClaw entries:
+   `bajaclaw mcp port --force`
+5. Confirm the result:
+   `bajaclaw mcp list <profile>` — shows the merged view for that profile.
+
+## Alternative: permanent auto-inherit
+If the user wants every desktop MCP server auto-inherited on every cycle
+(without an explicit port), edit the profile's config.json:
+```json
+{ "mergeDesktopMcp": true }
+```
+This reverts to the pre-0.4 behavior, per profile.
+
+## Pitfalls
+- BajaClaw's own `bajaclaw` MCP entry is always skipped during port — no
+  self-references.
+- Port copies the server entry verbatim, including `env` vars. If a desktop
+  entry has env secrets, those travel with the port. Review before sharing
+  the config file.
+- `--force` overwrites entries with the same name. Use when updating a
+  previously-ported entry.
+
+## Verification
+- `ls ~/.bajaclaw/mcp-config.json` exists and contains the expected entries
+- A subsequent cycle shows the MCP tools available in `bajaclaw start --dry-run`
+  output under the `--mcp-config` path