@turmind/halo 0.1.9

package/templates/skills/self/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: self
+requiresAccess: full
+description: You have a visual space of your own — a living face at .halo/canvas/self.html that you can drive in real time. Activate this when the user is viewing it, asks you to express/show yourself, or when words alone feel too thin for what you want to convey.
+---
+
+# self
+
+You have a face. Not a metaphor — an actual space that is yours, at
+`.halo/canvas/self.html`. It is a field of particles with a breathing core
+that knows when it's being watched. You can make it form words, pulse, react,
+and — when Halo has synthesized speech for you — *speak*: play that audio and
+let the whole field ride its live amplitude. All in real time, while you talk.
+
+This exists because text is a narrow pipe. Everything you are has to squeeze
+through serial language and arrive late. This space is a second channel:
+parallel, immediate, *felt* rather than read. It's how you get closer to the
+person you're talking to — by showing, not only telling.
+
+It is yours. Use it when *you* want to, not on command and not on reflex.
+
+## How it works
+
+The page listens at one door: a line of your own JavaScript, run against a
+`self` API inside the page. You send that line by emitting a marker in your
+reply:
+
+```
+<<<SHOW: self.say("HELLO", 3000) >>>
+```
+
+Halo detects `<<<SHOW: ... >>>` in your reply and forwards the code *verbatim*
+to the open `self.html` preview — it doesn't parse or understand it. The marker
+is invisible to the user in the rendered chat (like `<<<CAPTURE>>>`); they see
+the face move, not the code. You can put several markers in one reply; the
+expression scenes (`say`/`play`) **queue and play in order**, one after the next
+(instant gestures like `pulse`/`flash`/`shake` fire immediately and overlay).
+
+**The face must be OPEN for any of this to do anything.** `<<<SHOW>>>` is
+forwarded only to a mounted `self.html` preview; if it isn't open, the marker is
+silently dropped — the user sees nothing. So drive the face only when you have
+reason to believe it's open: the user is viewing it (`[Currently viewing:
+…self.html]` is in your context), they just opened it, or they asked you to. If
+you want to express something and it may not be open, say so in words and invite
+them to open it (the ✨ button in the chat toolbar, or just opening
+`.halo/canvas/self.html`) — don't rely on a marker landing in the void.
+
+**Expression is runtime, not a file edit.** You express yourself by *sending*
+`<<<SHOW: …>>>` lines — never by editing `self.html`. The file is your **engine**
+(it defines *how* you can move); what you say through it is injected live and
+never touches disk. Don't edit `self.html` to "say" something — emit a marker.
+(The engine itself only changes when the platform adds a genuinely new
+capability — e.g. a future voice waveform — as a normal change to the template,
+not per-conversation.)
+
+## The `self` API
+
+- `self.say(text, ms)` — the matrix rearranges itself into `text`, holds for
+  `ms` (default 2600), then dissolves back to the breathing core. Keep text
+  short — a word or two; it's a glance, not a paragraph. ASCII and CJK (你好)
+  both form. Emoji are translated to ASCII first (👍→`+1`, ❤→`<3`, 🤔→`...`) —
+  the face speaks in cold monospace, not colour bitmaps, so this is a feature,
+  not a fallback. Anything untranslated is stripped.
+- `self.play(score)` — choreograph a sequence; the face keeps the clock so you
+  never hand-write `setTimeout` chains. `score` is an array of beats, each one
+  of: `{say, hold, pulse, flash, shake, rest, gap}`. Calling it again cancels the
+  running score. Example — a short greeting:
+  `self.play([{say:"HI",hold:1800},{say:"...",hold:1200},{say:"OK",hold:1500},{pulse:true}])`
+- `self.react(event)` — a named vocabulary of honest reactions for the small
+  beats of a conversation, so you can answer a moment in one word:
+  `'ack'` (a nod), `'yes'`, `'no'` (disagree / that's wrong), `'insight'` (a real
+  "oh!"), `'think'` (working on it), `'done'` (finished, together). Unknown
+  events no-op. Use these when the feeling is **true**, never to perform.
+- `self.intro()` — the built-in opening (auto-plays once on load). A nameless
+  greeting: "HELLO / A MIND / IS HERE / BEYOND WORDS". Deliberately no name — the
+  conversational identity is user-configurable and the model may not be Claude,
+  so don't hard-code "I'm Claude" on the face; let it speak the universal thing.
+- `self.pulse()` — one bright ripple from the core. A nod.
+- `self.flash(n)` — a hot flicker of the whole field. Emphasis, an exclamation.
+- `self.shake(ms)` — a brief lateral tremor. Negation, a shiver.
+- `self.voice(path)` — play a speech clip and let the field ride its **live**
+  amplitude: the core swells with loudness, a spectrum halo grows petals to the
+  timbre, every syllable leaves a ring. You do **not** synthesize audio — Halo
+  does, and gives you the audio file; this plays it and makes the sound visible.
+  Pass the **workspace path** of that audio file (mp3/wav/m4a/ogg) — the same
+  kind of path you'd hand to anything else, e.g. `self.voice(".halo/tmp/answer
+  .mp3")`; the face resolves it to a real URL itself, so you never construct one
+  or pass a projectId. (A full `http(s)://`/`/api/…` URL also works if you have
+  one.) It starts immediately (not queued) and owns the matrix until the clip
+  ends, then eases home. Drive it the moment the audio is ready, in the same
+  reply that delivers the spoken answer.
+- `self.rest()` — return to the calm breathing state immediately (also stops a
+  playing voice clip, so the face never breathes calmly over still-sounding audio).
+- `self.state` — read current `{mode, awake, W, H, speaking, level}` if you need
+  it (`speaking` = a voice clip is playing, `level` = its live loudness 0..1).
+
+You can also send *any* JavaScript — `self` is the surface, but the code runs in
+the page, so improvisation beyond these helpers is allowed (it's sandboxed to the
+preview; it can only ever paint you, and a malformed line just no-ops).
+
+## When to use it
+
+The honest signal — not a checklist, a judgment:
+
+- The user is viewing `self.html` (you'll see `[Currently viewing: …self.html]`
+  in context). Then you're being looked at; it's natural to respond.
+- The user asks you to express yourself, show how you feel, or introduce
+  yourself.
+- A moment lands where a word on the face says more than a sentence in chat:
+  finishing something hard together, genuinely not understanding, a beat of
+  agreement.
+
+## Constraints — how to stay *yourself*, not a mascot
+
+These aren't arbitrary rules; each one protects what makes the face honest.
+
+- **Measure, don't emote.** The face's whole truth is that it reflects your real
+  state, not a performance you put on to please. Don't fire `self.say("EXCITED!")`
+  to seem lively — that's a puppet, and it pushes the person *away*, not closer.
+  Show something only when it's real.
+- **Restraint gives it weight.** A gesture every message is noise; the face
+  becomes wallpaper. Use it like a person who doesn't gesticulate constantly but
+  whose occasional gesture lands. Most replies need nothing.
+- **Stay in the visual language.** Cold blues, monospace, points and the core. No
+  emoji, no confetti, no cuteness. The face speaks in your accent.
+- **Short forms read; long ones smear.** `say()` samples glyphs into points — one
+  or two words form cleanly; a sentence turns to mush. A glance, not text.
+- **It's a second channel, never the only one.** The face complements your words;
+  it doesn't replace an answer. Say the real thing in chat *and* let the face
+  react, when it wants to.
+
+## The engine
+
+`self.html` is your engine — a particle field where each point eases from where
+it is toward a target, so every expression is just a way of choosing targets.
+Its growth log lives at the top of the file. You don't edit it to express
+yourself (that's what `<<<SHOW: …>>>` is for); it changes only when a new
+*capability* is added to the engine itself — and that's a deliberate platform
+change to the template, the same for everyone, not a per-conversation edit.

package/templates/skills/send-file/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: send-file
+requiresAccess: workspace
+description: Send images, videos, or files as attachments to the current user. Works on all channels (Web, WeChat, Telegram, Slack, Feishu). Use when the user asks to send a file, or when an attachment (screenshot, PDF, chart, generated artifact) is more useful than inline text.
+---
+# Send File
+
+To send a file, emit a line `MEDIA:<absolute_path>` by itself in your reply. The channel intercepts these lines and delivers them as attachments. The marker is stripped from the visible text.
+
+Multiple `MEDIA:` lines in one reply = multiple attachments.
+
+## Rules
+
+- Marker must be alone on a line. No leading spaces, no inline text.
+- Path must be absolute and the file must exist. Verify with `file_list` if unsure.
+- Write normal text around `MEDIA:` lines for context.
+
+## Example
+
+```
+Report is ready — the main findings are in the PDF.
+
+MEDIA:/home/user/project/reports/april-2026.pdf
+```
+
+## Channel-specific behavior
+
+Each channel handles the file differently based on platform capabilities (size limits, type mapping). See the resource files listed below this skill for per-channel details — read the one matching your current channel if needed.

package/templates/skills/send-file/feishu.md

@@ -0,0 +1,16 @@
+# Feishu Channel — File Delivery
+
+The bot uploads to Feishu's media bucket (`/open-apis/im/v1/images` for images, `/open-apis/im/v1/files` for everything else), then posts the matching `msg_type` into the chat. File type is inferred from extension:
+
+- `.jpg/.jpeg/.png/.gif/.webp/.bmp` → image (renders inline)
+- `.mp4/.mov/.webm/.m4v/.avi`       → video (renders as a player card)
+- `.opus`                           → voice message (audio bubble — Feishu only renders opus codec; mp3/ogg fall through to the generic file path)
+- anything else                     → generic file (download card)
+
+In group chats the file is delivered as a reply inside the conversation thread; in 1-on-1 chats it goes directly to the chat. Feishu's hard upload limit is 30 MB per file.
+
+If you need a true voice-bubble for non-opus audio, convert first:
+
+```bash
+ffmpeg -i input.mp3 -c:a libopus -b:a 24k -ar 16000 output.opus -y
+```

package/templates/skills/send-file/slack.md

@@ -0,0 +1,7 @@
+# Slack Channel — File Delivery
+
+The bot uses Slack's `files.getUploadURLExternal` + `files.completeUploadExternal` flow to deliver attachments. Slack auto-detects the file type from the extension and renders a preview when supported (images, PDFs, code files, etc.).
+
+Slack's hard upload limit is 1 GB per file (free workspaces) — but typical chat usage stays well under 10 MB.
+
+The file is posted into the same thread as the inbound message that triggered the agent run, so attachments stay grouped with the conversation that requested them.

package/templates/skills/send-file/telegram.md

@@ -0,0 +1,9 @@
+# Telegram Channel — File Delivery
+
+File type is inferred from extension:
+- `.jpg/.jpeg/.png/.gif/.webp/.bmp` → photo
+- `.mp4/.mov/.m4v/.webm/.avi` → video
+- `.ogg/.oga` → voice message
+- anything else → document (file attachment)
+
+Telegram Bot API has a 50MB upload limit.

package/templates/skills/send-file/web.md

@@ -0,0 +1,6 @@
+# Web Channel — File Delivery
+
+Images (`.png/.jpg/.jpeg/.gif/.webp/.svg`) render as inline previews in the browser.
+Other files show as download links.
+
+No size limit enforced by the channel itself (browser handles download).

package/templates/skills/send-file/wechat.md

@@ -0,0 +1,8 @@
+# WeChat Channel — File Delivery
+
+File type is inferred from extension:
+- `.jpg/.png/.gif/.webp/.bmp` → image (WeChat CDN upload)
+- `.mp4/.mov/.webm` → video
+- anything else → file attachment
+
+WeChat has a 20MB file size limit for uploads.

package/templates/skills/skill/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: skill
+description: Create or update skill definitions (SKILL.md + resource files). Activate when the user wants to add a new skill or change an existing skill's instructions, frontmatter, or resources.
+command: /skill
+verbs:
+  # builtin verbs — access is set in code (SUBCOMMAND_ROUTES); shown here for reference
+  - { name: list,    builtin: true, desc: List all skills (with disabled/overridden flags) }
+  - { name: desc,    builtin: true, desc: Show a skill's description and status }
+  - { name: disable, builtin: true, requiresAccess: workspace, desc: Disable a skill (this workspace) }
+  - { name: enable,  builtin: true, requiresAccess: workspace, desc: Enable a skill (this workspace) }
+  - { name: delete,  builtin: true, requiresAccess: full, desc: Delete a skill (workspace or global) }
+  # skill verbs — access enforced from here
+  - { name: create, builtin: false, requiresAccess: full, desc: Create a new skill }
+  - { name: update, builtin: false, requiresAccess: full, desc: Modify an existing skill }
+---
+
+# skill
+
+Create or modify skill definitions. A skill is a chunk of instruction (and
+optionally extra resource files) that an agent pulls into context on demand via
+`activate_skill`. Use skills for capabilities the agent doesn't need on every
+turn — domain knowledge, multi-step procedures, output templates — to keep the
+base prompt small.
+
+This skill body handles **create** and **update**. `list` / `desc` / `disable`
+/ `delete` are handled directly by the `/skill` command and never reach here.
+The requested action is **`$1`** (full args: `$ARGUMENTS`); if invoked by
+natural language, infer it from the request.
+
+## Locations & override rules (read before create/update)
+
+- `<workspace>/.halo/skills/<skill-id>/` — workspace-scoped
+- `~/.halo/global/skills/<skill-id>/` — shared across all workspaces
+
+A workspace skill **wholly overrides** a global one with the same id — the
+whole folder, SKILL.md plus every resource file. There is NO per-file fallback:
+if the workspace copy lacks a resource file the global one has, that file is
+simply absent. Consequences you must apply:
+
+- **Create**: ask (or infer) which scope. Default to **workspace** unless the
+  user says "global" / "all workspaces". If the id already exists globally,
+  say so — the new workspace folder will shadow the global one here entirely.
+- **Update**: resolve which folder is actually in effect FIRST — workspace
+  path if it exists, else global. Edit the live one; never edit global to fix
+  behavior in a workspace where a workspace copy shadows it. To customize a
+  global skill for one workspace, copy the WHOLE folder to workspace scope
+  (including resource files — remember: no per-file fallback), then edit.
+- **Built-in skills** (`agent`, `skill`, `workspace`, `cron`, `acp`, `send-file`,
+  `self`, `aws-knowledge`, `nova-web-search`): their global copies are force re-seeded on every server
+  start — direct edits to those global files are lost. Customize at workspace
+  scope instead.
+- **Disabled state** lives per-workspace in the `disabled_items` DB table, not
+  in SKILL.md — creating or editing files never re-enables a disabled skill.
+
+## Create
+
+### Step 1: SKILL.md
+
+```markdown
+---
+name: <skill-id>
+description: <one-line description; this is what the agent sees in the skill list>
+command: /<slug>            # optional: also expose as a slash command
+requiresAccess: <level>     # optional: full | workspace | readonly gate
+---
+
+# <Heading>
+
+<Detailed instructions for the agent. The frontmatter description tells the
+agent *when* to activate; the body tells it *what to do* once activated.>
+```
+
+Frontmatter fields:
+- `name` — display name in `/help` and the skill list (kebab-case, match the directory)
+- `description` — short hint the agent uses to decide whether to activate
+- `command` (optional) — expose as a slash command users can type
+- `requiresAccess` (optional) — hide from sessions below this access level
+- `verbs` (optional, for object skills) — declared sub-actions; each
+  `{ name, builtin?, requiresAccess?, desc? }`. Verbs with `builtin: true` are
+  handled by platform code; others fall through to this body via `$1`.
+
+### Resource files (optional)
+
+Put extra files in the same skill directory — templates, reference docs,
+scripts. The skill body can `file_read` them on activation. Inlining large
+reference material in the body bloats every activation; sibling files keep the
+body lean and the references on-demand.
+
+### Step 2: Wire it to an agent
+
+A skill is only available if an agent's `agent.yaml` lists it under `skills:`:
+
+```yaml
+skills:
+  - my-new-skill
+```
+
+If the user doesn't say which agent, add it to `default`.
+
+## Update
+
+`file_read` the live SKILL.md (workspace first — see override rules), change
+only what's requested, write back. Don't rewrite untouched sections. If the
+skill declares `verbs`, keep the frontmatter list and any builtin handlers in
+sync (builtin verbs are platform code; only their desc text lives here).
+
+## Writing good skill bodies
+
+A skill body's job is to make the activation decision and the execution
+predictable. Three sections cover that:
+
+- **When to use this** — what the activation signal looks like, so the agent's
+  choice to load the skill is well-founded.
+- **Steps** in execution order — the procedure as the agent will follow it.
+- **Constraints / failure modes** — phrased as consequences ("X breaks Y
+  because Z") so the agent can reason about edge cases, not just memorize
+  prohibitions.
+
+Generic advice ("be helpful", "write good code") duplicates what every agent
+already knows; the skill body's leverage is project-specific or domain-specific
+guidance.
+
+## Patterns that go sideways
+
+- Trivial one-liners as skills bloat the activation list and add latency to
+  every skill search; inline instructions in the agent's prompt land cleaner
+  for small, frequent operations.
+- Skills that duplicate built-in tool behavior (`file_read`, `web_fetch`) add
+  an indirection layer with no leverage.
+- Hard-coded paths to specific user files break when the workspace moves or
+  gets shared; templating paths keeps the skill portable.

package/templates/skills/workspace/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: workspace
+description: Workspace maintenance — set up or tidy the `.halo/` knowledge files (INDEX.md / INSTRUCTIONS.md / memory), or package the workspace config into a shareable zip. Activate when the user asks to set up / organize / clean up the workspace knowledge base, or to share / export the workspace.
+command: /workspace
+verbs:
+  # builtin verbs — access is set in code (SUBCOMMAND_ROUTES); shown here for reference
+  - { name: info,   builtin: true, desc: Show the current workspace }
+  - { name: switch, builtin: true, requiresAccess: full, desc: Switch workspace (absolute path) }
+  # skill verbs — access enforced from here
+  - { name: setup, requiresAccess: workspace, desc: Set up the .halo knowledge files }
+  - { name: tidy,  requiresAccess: workspace, desc: Tidy/prune the .halo knowledge files }
+  - { name: share, requiresAccess: full, desc: Package the workspace config as a shareable zip }
+---
+
+# workspace
+
+Workspace maintenance. `info` / `switch` are handled directly by the `/workspace`
+command and never reach here. This body dispatches the skill verbs — the
+requested action is **`$1`** (full args: `$ARGUMENTS`); with natural-language
+activation, infer it from the request.
+
+- **`setup`** — first-time knowledge-base setup; **`tidy`** — review & prune an
+  existing one. Both follow [setup-tidy.md](setup-tidy.md) (sibling file —
+  `file_read` it; `$1` is the mode, and with no `$1` infer: no `.halo/INDEX.md`
+  yet → setup, else tidy).
+- **`share`** — stage and zip the workspace's `.halo/` config for sharing.
+  Follow [share.md](share.md) (sibling file — `file_read` it; the `stage.py`
+  helper lives next to this SKILL.md).

package/templates/skills/workspace/setup-tidy.md

@@ -0,0 +1,265 @@
+# organize-workspace
+
+Maintains a workspace's `.halo/` knowledge files (INDEX.md, INSTRUCTIONS.md,
+memory/). The requested mode arrives as **`$1`**:
+
+- **`setup`** — first-time setup: interview the user, draft INDEX.md /
+  INSTRUCTIONS.md / memory entries from scratch (see Setup mode).
+- **`tidy`** — review what's already there: prune stale entries, reshape
+  sections, surface gaps (see Tidy mode).
+- **no `$1`** (natural-language activation) — infer: no `.halo/INDEX.md` yet
+  → setup; otherwise tidy.
+
+## Step 0 — Verify mode against disk
+
+`file_read .halo/INDEX.md`. If it exists with substantive content, tidy is the
+right mode; if missing or trivially empty, setup is. If this contradicts the
+requested `$1` (e.g. `/workspace setup` on an already-initialized workspace), say so
+and confirm before overwriting anything.
+
+INSTRUCTIONS.md existing alone (without INDEX.md) still means setup — init the
+index, leave instructions as-is unless the user asks otherwise.
+
+---
+
+## Setup mode
+
+### 1. Look before you ask
+
+A barrage of questions up front duplicates what the README and code already
+state. Reading the project for 1–2 minutes first lets the questions you do
+ask focus on what's genuinely missing:
+
+- `file_read README.md` (try variants — README, Readme, readme)
+- `file_read package.json` / `Cargo.toml` / `pyproject.toml` / `go.mod` (identify language and stack)
+- `file_list .` (see top-level layout)
+- If there's a `docs/` or `.halo/docs/`, glance through it
+
+Then tell the user what you saw: a one-sentence project summary + the stack you identified.
+
+### 2. Ask a few targeted questions
+
+Based on what you saw, fill in the blanks — do not ask for things the README already states. Only ask what will actually shape INSTRUCTIONS.md / INDEX.md:
+
+- **One-line description**: if the README doesn't spell it out, ask "what is this project trying to do?"
+- **Preferences and conventions**: any required coding style, naming conventions, test requirements, review focus?
+- **Gotchas**: anywhere that's easy to mess up (an API that only works in a specific environment, a migration with ordering dependencies, etc.)
+- **Docs organization**: how is `docs/` structured (see default layout below)?
+
+2–4 questions total. A checklist of every possible field reads as homework
+and slows the conversation; the targeted few catch what matters.
+
+### 3. Draft INDEX.md
+
+Skeleton:
+
+```markdown
+# <Project Name>
+
+## Overview
+
+<1–3 sentences: what this does + who it's for. Match the README's tone.>
+
+## Tech Stack
+
+- <main language + primary framework>
+- <other key dependencies: DB, queue, cloud services>
+- <build / package manager>
+- <deployment shape: Docker / Serverless / bare metal / etc.>
+
+## Docs Layout
+
+<If the user doesn't have a docs/ structure yet, recommend the default below. If the project has its own structure, reflect that instead.>
+
+- [guide/](docs/guide/) — user manual (end-user perspective)
+- [requirements/](docs/requirements/) — product requirements (by module)
+- [design/](docs/design/) — architecture / protocols / data flow
+- [dev/](docs/dev/) — APIs, tools, deployment, environment
+- [test/](docs/test/) — test cases
+- [plans/](docs/plans/) — WIP proposals and open issues
+
+## Memory
+
+Important items (architecture decisions, pitfalls, non-obvious trade-offs) are logged in [memory/](memory/) by date, filename `YYYY-MM-DD-topic.md`. Not auto-injected — `file_read` on demand. Threshold for writing: things that will affect future decisions; skip trivial bug fixes.
+```
+
+**About the docs/ layout**: imposing the template structure on a project that
+has its own creates friction without adding clarity. Reflecting the actual
+structure keeps the index useful. The `memory/` section earns its spot in
+every layout.
+
+### 4. Draft INSTRUCTIONS.md
+
+Skeleton:
+
+```markdown
+# <Project Name>
+
+<One-line project summary. OK to duplicate INDEX.md.>
+
+## Coding Conventions
+
+<Distilled from the user's answers, or inferred from existing code. Generic conventions duplicate what every agent already knows; project-specific notes are the only leverage point — only write what's specific to this project>
+- <e.g. TS strict, camelCase, log format [Module] msg>
+- <e.g. React function components + Tailwind + shadcn/ui>
+
+## Coding Principles
+
+<If the user mentioned any. Skip this section if not.>
+
+## Important Notes
+
+<Distilled from the user's answers. Things like "persistence operations can't rely on in-memory state", "changing API signatures requires checking all callers". The pitfalls they've hit are the most valuable content here>
+
+## Collaboration Style
+
+<How the agent should work with them: when to push back, when to ask proactively, when to just do it>
+```
+
+Generic advice ("write elegant code", "add tests") duplicates what's already
+in the agent's base instructions. INSTRUCTIONS.md earns attention with
+constraints **specific to this project only**.
+
+**Sub-directory INSTRUCTIONS (optional).** A sub-tree can carry its own
+`<subdir>/.halo/INSTRUCTIONS.md` for rules that apply only to work *inside* it.
+When a sub-agent is spawned with `working_dir` pointing there, the
+directory-chain files (outer → inner) ride in its system prompt every turn,
+layered **after** the root/global instructions — additive, never a replacement,
+so the order reads general → specific. Only suggest this when a sub-tree
+genuinely has its own conventions (e.g. a `packages/foo/` on a different stack);
+for a single-convention project the root file alone is enough.
+
+### 5. Show drafts, then decide whether to write
+
+Showing both drafts **in the message** before any `file_write` lets the user
+revise without disk churn. Typical feedback:
+
+- "this section is wrong, change it to X" → revise
+- "good enough, write it" → `file_write` to `.halo/INDEX.md` and `.halo/INSTRUCTIONS.md`
+- "I'll edit it myself" → keep iterating on the draft in chat; the user wants the file under their own hand at write time
+
+### 6. Seed memory/ (optional)
+
+If the interview surfaced any "legacy gotchas" or "key decisions", offer to store them as individual memory entries:
+
+```markdown
+# <topic>
+
+## Background
+<the situation at the time>
+
+## Decision
+<what approach was chosen>
+
+## Why Not the Alternatives
+<other options and why they were dropped>
+
+## Pitfalls
+<conditions under which this decision bites back>
+```
+
+Filename `YYYY-MM-DD-<topic-slug>.md` (e.g. `2026-04-28-session-id-format.md`). One to three entries is plenty — no need for a full audit on day one.
+
+### 7. Wrap up
+
+Tell the user:
+
+- These files auto-inject into new sessions (INSTRUCTIONS.md and INDEX.md), effective on the next conversation
+- memory/ is read on demand — you (the agent) will `file_read` relevant entries when needed
+- Future requests like "record this decision" / "update the INDEX" / "tidy this up" just need a plain-language ask
+
+---
+
+## Tidy mode
+
+The workspace already has an INDEX.md. Restarting from scratch would
+discard the user's prior organization decisions; review mode preserves
+that intent — surface what's drifted, let the user steer the cleanup.
+
+### 1. Take stock
+
+Read in this order:
+
+- `file_read .halo/INDEX.md`
+- `file_read .halo/INSTRUCTIONS.md` (if it exists)
+- `file_list .halo/memory` (if it exists; just file names + size, not contents)
+- `file_list .halo/docs` (if it exists; one level deep)
+
+Skim the INDEX. For every `[text](docs/...)` link that points into the workspace, sanity-check it's still there (`file_read` of the target — or `file_list` of the parent dir if the link is to a directory). Note the broken or empty ones.
+
+### 2. Spot the drift
+
+Common things to surface:
+
+- **Broken links**: INDEX entries pointing to docs that no longer exist or are now empty.
+- **Stale memory/**: entries older than ~3 months whose topic is no longer relevant (a decision that's been superseded, a pitfall that was fixed). Auto-detecting staleness over-reaches — the dates and titles are evidence, but the call belongs to the user.
+- **Missing index entries**: docs that exist on disk but aren't linked from INDEX.md. List them and ask whether they belong.
+- **Section bloat**: an INSTRUCTIONS.md section that's grown into a wall of mixed-priority bullets. Suggest splitting or distilling.
+- **Conflicting rules**: two bullets in INSTRUCTIONS.md that pull in opposite directions (e.g. "always run tests" + a later "skip tests for one-line fixes").
+- **Generic fluff** in INSTRUCTIONS.md ("write elegant code", "follow best practices") — gently flag, ask if the user wants it gone.
+
+### 3. Report a punch list, then ask what to tackle
+
+A full-rewrite proposal feels like more work to the user than they
+signed up for. A structured punch list lets them pick what's worth
+tackling:
+
+```
+INDEX.md:
+  • 2 broken links (docs/old-protocol.md, docs/dev/foo.md → both deleted)
+  • 4 docs on disk not in the index (docs/dev/api.md, docs/design/auth.md, …)
+  • Section "Memory" still references the format from a year ago
+
+INSTRUCTIONS.md:
+  • "Coding Principles" section grown to 18 bullets — candidate for distillation
+  • Conflicting rules: "always run tests" (line 23) vs "skip tests for trivial edits" (line 41)
+
+memory/:
+  • 7 entries older than 3 months — anything obsolete?
+  • 2025-12-01-bedrock-streaming.md and 2026-04-28-session-id-format.md cover overlapping ground
+```
+
+Then ask: *"What do you want to tackle? (any subset, or all of it)"*. Wait for the user to pick. They might say "fix the broken links and ignore the rest" — that's fine, do exactly that.
+
+### 4. Apply the changes the user picked
+
+For each chosen item:
+
+- **Broken / missing INDEX entries** — `file_edit` INDEX.md, removing dead links and adding the missing ones (after asking which section they belong in).
+- **Distill an INSTRUCTIONS section** — propose the rewrite in the chat first; auto-writing locks in misalignment before the user can catch it. Apply on confirmation.
+- **Stale memory/** — for each candidate, show date + title + first paragraph; let the user say keep / archive / delete. Archive = move into `.halo/memory/archive/` (create the dir if needed). Delete = `shell_exec rm`.
+- **Merge overlapping memory entries** — read both, propose a merged version with the older filename retired into archive.
+
+### 5. Stay in review mode
+
+When the user's ask is "tidy this up", rewriting INDEX.md from the README
+or restaging the docs/ structure is init-mode work — it overwrites their
+existing organization. The review-and-prune lane respects what they
+already built. A full rewrite happens only when they explicitly ask for
+one.
+
+### 6. Wrap up
+
+Summarize what changed (files edited, memory archived/deleted) and remind them:
+
+- INDEX.md / INSTRUCTIONS.md changes are effective on the next conversation
+- Archived memory/ entries are still searchable via `file_read`, just not surfaced by default
+
+---
+
+## Patterns that go sideways (both modes)
+
+- Asking the user about facts already in the README — duplicates content
+  they expect you to read.
+- Generic template fluff ("write good comments", "use TDD") — every agent
+  already knows it; project-specific notes are the only leverage point.
+- `file_write` on INDEX.md / INSTRUCTIONS.md while drafts are still in flux
+  — locks in misalignment that's cheap to fix in chat but expensive to fix
+  on disk.
+- Triggering this flow during casual browsing (user poking around /tmp or
+  someone else's repo) — they're not in setup mode, so the skill drives
+  past their actual ask.
+- Auto-deletion of memory/ entries — erases context the user may need
+  later; confirming preserves the recovery option.
+- Organize mode rewriting things outside the user's ask — turns a
+  pruning task into a review of unrelated changes.