Detailed internals for `src/core/`. For architecture overview, see project `CLAUDE.md`.

Every visible model reply goes through `web/src/utils/markdown.ts`. Rich (HTML) replies additionally go through `web/src/utils/rich-blocks.ts` before rendering. Both files are incident-dense: each rule below is a shipped bug.

The Walnut web console and the iOS app both render raw HTML in an assistant reply as real DOM, streaming it like markdown. You do not need a special syntax or a wrapper: write `<div>`, `<style>`, `<svg>`, `<details>` in the reply and they render. Markdown still works alongside, so use HTML only wher

The cloud companion is a small always-on VM the user owns. It receives the Mac's data repo over git-smart-HTTP, serves the phone over HTTPS from anywhere, and relays live session traffic. Setting one up means: provision a VM → point a hostname at it → wait for first boot → claim it → verify

The Walnut web console renders `<suggest>` blocks in assistant messages as cards with clickable buttons. A click executes the named op with the given args, under the user's authorization. Every other surface (phone v1 projection, plain-text notifications) shows the raw tags, so the surrounding prose

For testing philosophy, run commands, and anti-patterns, see project `CLAUDE.md`. For the layered pipeline (which tier to run when), see [docs/reference/testing-pipeline.md](../../../docs/reference/testing-pipeline.md).

This skill explains the Walnut web UI so you can operate it confidently via Playwright MCP tools, acting as a human user.

Read and edit the user's real calendars (macOS Calendar: iCloud, Google, Exchange accounts) through Walnut's /api/calendar REST endpoints. Use when asked about the user's schedule, meetings, or availability, or to create, move, retime, or delete calendar events, or to hide one event in Walnut only. Covers listing events in a date range, enumerating calendars, and write-back that syncs to the cloud provider via macOS.

Report on the user's recent sleep from Apple Health: the last 7 nights against their own 28-night baseline, with plain flags and the prior day's context. Use when the user asks "how did I sleep", "sleep report", "am I sleeping enough", or wants their sleep compared with their work.

Import coding-agent sessions a person started outside Walnut (terminal `claude`, Claude Desktop, the VS Code extension, codex TUI) into Walnut as tasks. Use when the user says "import my sessions", "find sessions opened outside Walnut", asks why a session id isn't in Walnut (a script's `claude -p` runs are left out on purpose), asks what the "Imported" pill means or why an imported task completed itself, or wants the external-session scan run NOW instead of waiting for the background tick.

One Inbox Triage batch: reads, notes, decisions. Only for the Inbox Triage agent. Not for single messages, mail/Slack questions or task triage (the `walnut-triage` skill).

Use a password, API key, one-time code or card from the user's Walnut password vault for a step you are doing: sign in to a site, call an API, run a CLI that needs a token, enter a 2FA code. Use it whenever a step needs a credential the user keeps, instead of asking them to paste it. `walnut pass run` gives a command its secrets as env vars without them entering your context; `password_use` returns values when you must type them yourself. The user picks whether agents use items at once (Any, the default), ask each time (Ask) or not at all (Off); a sensitive item always asks.

Answer questions about where the user has been, from the visits Walnut on the iPhone records once the user turns Places on: "where was I on Tuesday", "how long was I at the office this week", "when did I get home", "have I been to the gym lately". Use when the user asks about places they went or time spent at one.

Build, verify, and package an Open Walnut Plugin with the public plugin API and author CLI. Use when creating a Plugin, adding a native App or server automation, converting a legacy integration, debugging Plugin lifecycle cleanup, or preparing a Plugin release.

Deep-explore current codebase and register it as a Walnut repository. Produces a rich profile: what the project does, architecture overview, key components, tech stack, and common workflows. Use when user says "register repo", "add this repo", "/walnut-register-repo", or wants to create a Walnut repository profile for the current project.

Understand Walnut's task, project, messaging, and lifecycle rules. Read when deciding whether to work directly, create a task (which also starts it), start a task that is only a placeholder, message work that is already running, resolve cwd, or hand work back to the user.

Talk to the user's OTHER Walnut work: discover it with `task_list` and its `scope`, send a task a message with `task_send`, ask for a result with `expect_reply`, answer a request with `in_reply_to`, and block with `walnut wait` only when you cannot continue without the answer. Use when you need to hand off findings, tell sibling work that shared work is ready, ask another task a question and get its answer back, or see what else is running, and instead of the built-in ListAgents / SendMessage or any other cross-session messaging. Works on any host that runs a Walnut daemon, inside a Walnut-launched session or a plain terminal.

For architecture overview and routes, see project `CLAUDE.md`.