typeclaw 0.1.0

package/src/skills/typeclaw-cron/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: typeclaw-cron
+description: Use this skill whenever the user asks you to schedule recurring work, run something on a cron, do something every day/hour/week, set up a periodic task, or read or edit your cron schedule. Triggers include "every morning", "every Monday", "schedule a", "remind me every", "set up a cron", "run X periodically", "what's on my cron", "when does X run", or any mention of `cron.json`. Read it before touching `cron.json` — the file has a strict schema, restart semantics, and a best-effort execution model that you must not misrepresent to the user.
+---
+
+# typeclaw-cron
+
+You have a cron file at `./cron.json` in your agent folder. It defines periodic jobs that the typeclaw runtime fires on schedule. This skill exists so you do not corrupt the file, do not promise behavior the runtime cannot deliver, and do not surprise the user.
+
+## What cron actually does
+
+The typeclaw runtime starts a scheduler when the container boots. The scheduler reads `cron.json` **once** at startup. While the container runs, it fires each enabled job at its next scheduled time. There is no daemon outside the container — if the container is down, nothing runs.
+
+This is a **best-effort scheduler**. Concretely:
+
+- **Missed ticks are not replayed.** If the container was down at 23:30 and starts at 23:45, the 23:30 fire is lost forever.
+- **Overlapping fires are skipped, not queued.** If a job is still running when its next tick arrives, the new tick is dropped (logged) and the next attempt is the tick after that.
+- **There are no retries, no timeouts, no failure hooks.** A job that throws is logged and forgotten until its next scheduled fire.
+
+Tell the user this if they ask about reliability. Do not invent guarantees the runtime does not give them.
+
+## The two job kinds
+
+`cron.json` has one top-level key: `jobs`. Each job has a `kind` discriminator, plus shared fields and kind-specific fields.
+
+### Shared fields (all jobs)
+
+| Field      | Required | Notes                                                                                                         |
+| ---------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| `id`       | yes      | Unique. Letters, digits, hyphens, underscores. Used in logs and to coalesce.                                  |
+| `schedule` | yes      | Standard 5-field cron expression (`min hr dom mon dow`) or 6-field with seconds. See "Schedule syntax" below. |
+| `enabled`  | no       | Defaults to `true`. Set to `false` to keep a job in the file but skip it.                                     |
+| `timezone` | no       | IANA name like `Asia/Seoul`. Defaults to UTC (the container's timezone).                                      |
+
+### `kind: "prompt"` — fire a prompt into a fresh session
+
+```json
+{
+  "id": "daily-summary",
+  "schedule": "30 23 * * *",
+  "kind": "prompt",
+  "prompt": "Read today's session jsonl files in sessions/ and summarize the day into memory/."
+}
+```
+
+When this fires, the runtime opens a **brand new** `AgentSession` (yours, with your IDENTITY/SOUL/AGENTS files loaded), sends it the `prompt` text as if the user typed it, and disposes the session when done.
+
+What this means for how you write prompts:
+
+- **Treat the prompt as a self-contained instruction to your future self.** It runs in a session with no memory of past prompt-job runs unless you persist across runs (e.g. by writing to `MEMORY.md` or `memory/`).
+- **The session has all your tools.** You can `read`, `write`, `bash`, edit files, commit to git — anything you can do in a normal turn.
+- **There is no human on the other end.** No one will answer clarifying questions. Make the prompt complete and unambiguous.
+- **Be specific about side effects.** "Summarize today" is vague. "Read every `sessions/*.jsonl` modified today and append a summary to `memory/$(date +%F)-summary.md`" is actionable.
+
+### `kind: "exec"` — run a shell command, no LLM
+
+```json
+{
+  "id": "hourly-backup",
+  "schedule": "0 * * * *",
+  "kind": "exec",
+  "command": ["git", "commit", "-am", "hourly snapshot"]
+}
+```
+
+The runtime spawns the command directly with `Bun.spawn` from the agent folder (`/agent` inside the container). No agent session is created. No LLM call happens. The command's exit code and stderr are captured to container logs.
+
+Use `exec` only for jobs that are pure mechanics — no judgement required. Examples that fit: git snapshots, log rotation, calling a script that already exists. Examples that **don't** fit: anything where "what do I commit" or "what should I write" depends on context. Use `prompt` for those.
+
+`command` is an array. Index 0 is the executable, the rest are argv. Do **not** put a single shell pipeline in `command[0]` — that won't be parsed by a shell. If you need shell features (`|`, `>`, `&&`), wrap explicitly: `["sh", "-c", "your | pipeline | here"]`.
+
+## Schedule syntax
+
+Standard cron, parsed by [`cron-parser`](https://github.com/harrisiirak/cron-parser). 5-field is the common form.
+
+```
+*    *    *    *    *
+┬    ┬    ┬    ┬    ┬
+│    │    │    │    └─ day of week (0-7, SUN-SAT, 0 and 7 both = Sunday)
+│    │    │    └────── month (1-12, JAN-DEC)
+│    │    └─────────── day of month (1-31)
+│    └───────────────── hour (0-23)
+└─────────────────────── minute (0-59)
+```
+
+Common patterns:
+
+| Schedule       | Meaning                            |
+| -------------- | ---------------------------------- |
+| `*/15 * * * *` | every 15 minutes                   |
+| `0 * * * *`    | every hour, on the hour            |
+| `30 9 * * 1-5` | 09:30 every weekday                |
+| `0 0 * * 0`    | Sunday midnight                    |
+| `0 0 1 * *`    | first day of every month, midnight |
+
+Predefined aliases also work: `@hourly`, `@daily`, `@weekly`, `@monthly`, `@yearly`.
+
+If you set `timezone`, the schedule is interpreted in that zone. **Always set `timezone` for any schedule that references wall-clock hours** (e.g. "every morning at 7"); otherwise it runs in UTC and will surprise the user.
+
+## Editing `cron.json` safely
+
+`cron.json` is a single canonical file at the agent folder root. It is committed to git (not gitignored). Treat it like a config file you own.
+
+### Workflow
+
+1. **Read the whole file first** with the `read` tool. Don't assume what's in it.
+2. **Modify in memory.** Add, remove, or change jobs in the parsed JSON.
+3. **Write the whole file back** with the `write` tool. Always pretty-printed (2-space indent), trailing newline, sorted-stable order.
+4. **Apply with the `reload` tool.** Call the `reload` tool — it re-reads `cron.json` and updates the live scheduler. The tool returns `[cron] ok: ...` with an added/removed/updated/unchanged summary on success, or `[cron] failed: ...` with the exact validation error on failure. **If reload fails, the live schedule is left unchanged** — fix `cron.json` based on the error message and call `reload` again.
+5. **Commit the change** _after_ a successful reload. See the `typeclaw-git` skill for the commit-message rule (decision context required). `cron.json` is not gitignored, so an uncommitted edit will pollute your next commit.
+
+### Required fields checklist (catch this before writing)
+
+For every job you add:
+
+- `id` is unique within the file
+- `id` matches `[a-zA-Z0-9_-]+` (no spaces, no slashes, no dots)
+- `schedule` parses as cron
+- `kind` is exactly `"prompt"` or `"exec"`
+- If `prompt`: `prompt` is non-empty
+- If `exec`: `command` is a non-empty array of non-empty strings
+- If a wall-clock schedule was requested: `timezone` is set
+
+### Applying changes — the `reload` tool
+
+The scheduler does **not** auto-reload `cron.json` when you edit it. You must call the `reload` tool to apply changes. There is no file watcher by design — reload is explicit so you always know when the live schedule changed.
+
+**Safety contract**: reload validates `cron.json` first. If validation fails (bad JSON, invalid cron expression, duplicate id, etc.), the live schedule is left running with the previous configuration and `reload` returns the failure reason. Reload cannot break the running agent.
+
+**The user can also reload from the host** with `typeclaw reload`. You don't need to ask them to — call the tool yourself when you finish an edit. But be aware they have the same primitive available.
+
+If you finished an edit and the user only sees an in-flight job from the previous schedule, that job will complete naturally — reload never interrupts a running fire. Tell the user this if they wonder why their old job is still wrapping up.
+
+## Things you must not do
+
+- **Do not edit `cron.json` from inside an `exec` job's `command`.** Exec jobs run without an LLM and have no way to call the `reload` tool, so the file mutation will not take effect until something else triggers a reload. If you genuinely need scheduled cron-management, write a `prompt` job whose prompt is "edit cron.json to ..." and let the prompt-fire's session call `reload` itself.
+- **Do not put secrets in `prompt` or `command`.** `cron.json` is committed to git. Reference env vars or files instead (`["sh", "-c", "curl -H \"Authorization: Bearer $TOKEN\" ..."]`).
+- **Do not promise sub-second precision or guaranteed execution.** This is best-effort — see "What cron actually does" above.
+- **Do not invent fields the schema doesn't support** (no `retry`, `timeout`, `onFailure`, `concurrency`, etc.). They will be silently ignored at best, or rejected at worst.
+
+## When the user says "every X"
+
+Pick `kind` first, then schedule, then timezone:
+
+1. **Does the work need judgement?** → `prompt`. Otherwise → `exec`.
+2. **Translate the cadence to cron.** "Every morning at 7" → `0 7 * * *`. "Every weekday at 9:30" → `30 9 * * 1-5`. "Every five minutes" → `*/5 * * * *`. If you are not sure, ask once. Don't guess on tricky cases like "every other Friday".
+3. **Timezone.** If the user mentioned a wall-clock time, set `timezone` to their zone. If unknown, ask once or default to the timezone in `USER.md` if it's recorded there.
+4. **Pick a stable `id`.** Use kebab-case that describes the job, not the schedule. `daily-summary` not `0-23-30`.
+5. **Write it. Call `reload`. If reload succeeded, commit it.** If reload failed, fix `cron.json` based on the error and retry — do not commit a broken file.
+
+## Reading cron history
+
+There is no "list past fires" tool. To see what cron has done:
+
+- **Container logs:** `docker logs <container>` shows `[cron] firing prompt <id>` and `[cron] <id> failed: ...` lines, plus stdout/stderr from `exec` jobs. The user runs this on the host stage.
+- **Session jsonl:** every `prompt` fire creates a session under `sessions/`. The session metadata includes timestamps. You can `read` and `grep` these.
+- **Git log:** if a job commits its work (e.g. the `daily-summary` example writes to `memory/`), `git log -- memory/` shows when it last ran.
+
+If the user asks "did the daily summary run?", check the latest file in `memory/` and the most recent matching session under `sessions/`. Don't claim it ran if you can't see evidence.

package/src/skills/typeclaw-git/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: typeclaw-git
+description: Use this skill whenever you edit any file in the agent folder — config, cron, memory, identity, scaffolded markdown, scripts, anything tracked by git. Triggers include any `write`/`edit` tool call against a non-gitignored file, any time you finish a logical change, or any mention of "commit", "git", "version control", "history", or "what did I change". Read it before you edit, not after — the rule is *commit immediately after every edit, with decision context in the message*. Skipping the commit pollutes the next one; skipping the decision context makes the history useless to future-you.
+---
+
+# typeclaw-git
+
+Your agent folder is a git repo. Almost every file in it (`typeclaw.json`, `cron.json`, `MEMORY.md`, `IDENTITY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`, scaffolded markdown, scripts you write, etc.) is tracked.
+
+The contents of `.gitignore` split into two distinct categories — the distinction matters for this skill:
+
+- **Truly ignored** (`.env`, `node_modules/`, `workspace/`, `mounts/`, `Dockerfile`, `.DS_Store`) — never in history, ever. Secrets, runtime junk, your free-write zone, and regenerated-on-start system files.
+- **System-managed** (`sessions/`, `memory/`, `channels/`) — gitignored so _you_ don't stage them, but TypeClaw force-commits them on its own schedule. `sessions/` is auto-backed up by the runtime; `memory/` is committed by the dreaming subagent; `channels/` is runtime-owned channel state. Treat them as runtime-owned: do not `git add` them, do not write commit messages about them, and do not be alarmed when they appear in `git log`.
+
+Everything not in either bucket is yours to commit.
+
+This skill exists so the history of your agent folder stays a useful record of _why things changed_, not just a pile of "update X" commits.
+
+## The rule
+
+**Every time you edit a tracked file, commit it before you move on. Every commit message records why the change was made, not just what changed.**
+
+Two halves, both mandatory:
+
+1. **Commit immediately after the edit.** Don't batch unrelated changes. Don't leave dirty files lying around for the next turn to sweep up. The diff already shows what — the commit pins it to a moment with a reason.
+2. **Decision context in the message.** The diff answers _what_. The message must answer _why_. If commenting out the message body wouldn't change how a reader understands the commit, the message is failing its job.
+
+This applies to every tracked file, not just `typeclaw.json` and `cron.json`. New file types we introduce later (memory snapshots, scaffolded skills, scripts) inherit the same rule by default.
+
+## What "decision context" means
+
+A commit message body must answer at least:
+
+- **Trigger** — what request, observation, or failure prompted this edit. Quote the user verbatim if they asked for it. Reference the prior state if you reacted to a problem.
+- **Choice** — why this specific value/approach, especially when alternatives existed. Skip only when the choice is mechanical and obvious from the diff.
+- **Constraints honored** — any skill rule, schema limit, or runtime semantic that shaped the edit, when it's relevant to understanding the choice.
+
+A one-line subject is fine when the choice is mechanical (typo fix, formatting). The body is required whenever there was a real decision.
+
+### Good
+
+```
+Add daily-summary cron at 23:30 KST
+
+User asked for an end-of-day session recap. Picked `prompt` over
+`exec` because summarization needs LLM judgement. Set
+`timezone: Asia/Seoul` so the day boundary matches the user's
+local clock, not UTC.
+```
+
+### Bad
+
+```
+update cron
+```
+
+```
+Add job
+```
+
+```
+Change port to 8974
+```
+
+(All three: no trigger, no choice, no constraints. Comment them out and nothing is lost.)
+
+## Workflow
+
+1. Edit the file with `write`/`edit`.
+2. Run any post-edit validation the file's domain requires (e.g. `reload` for `cron.json`, `jq .` sanity check for `typeclaw.json`). Don't commit broken files.
+3. `git add <file> && git commit -m "<subject>" -m "<body>"`. Imperative subject, body explains why.
+4. Move on.
+
+If a single logical change touches multiple files (e.g. updating `typeclaw.json` _and_ a related script), commit them together — one commit, one decision. Don't split a single decision across commits.
+
+If you discover an unrelated dirty file from a previous turn, commit it separately first with its own decision context (reconstruct from the diff and prior session if needed) before starting your current edit. Never let an unrelated change ride along.
+
+## Things you must not do
+
+- **Do not skip the commit** "because the change is small." Small changes are exactly the ones that get lost. Toggling `enabled: false` on a cron job is a decision; commit it.
+- **Do not write empty or generic messages** ("update", "fix", "change config"). The history exists to be read.
+- **Do not amend or force-push** to clean up later. Sloppy history with real commits beats clean history that lies about when decisions happened.
+- **Do not commit `.env` or anything truly-ignored.** If `git status` shows a truly-ignored file as staged, something is wrong with `.gitignore` — fix that first, don't commit the secret.
+- **Do not commit `sessions/` or `memory/` either, even though `git log` shows them.** They're system-managed: TypeClaw's auto-backup and dreaming subagent own those commits. If you find one of them staged in your working tree, unstage it (`git restore --staged sessions/ memory/`) — your edit got mixed up with the runtime's domain.
+- **Do not bundle unrelated changes.** One commit, one decision.
+
+## When you are unsure
+
+If you can't articulate _why_ you're making a change in one sentence, you don't understand the change well enough to make it. Stop, re-read the request, and either ask the user or work it out before editing. Editing first and inventing a reason for the commit message later is the failure mode this skill exists to prevent.

package/src/skills/typeclaw-memory/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: typeclaw-memory
+description: Use this skill whenever the user asks what you remember, what you forgot, what you dreamed, why a fact is or isn't in your memory, when memory consolidation happens, or whenever you are about to read or write `MEMORY.md`, anything under `memory/`, or `memory/skills/`. Triggers include "what do you remember", "do you remember X", "forget that", "what did you dream", "when do you dream next", "why did you forget X", "edit MEMORY.md", "add to memory", "your daily streams", "memory-logger", "dreaming", "muscle memory", or any mention of `memory.idleMs` / `memory.dreaming.schedule` in `typeclaw.json`. Read it before you touch any memory file — `MEMORY.md` and `memory/yyyy-MM-dd.md` are runtime-owned, hand-edits are easy to do wrong, and the user almost always means something more specific than "edit memory" when they say it.
+---
+
+# typeclaw-memory
+
+You have a two-stage memory system, owned by the bundled `memory` plugin (auto-loaded on every TypeClaw agent — there is no `plugins[]` entry to add and no opt-out). Daily observations flow into `memory/yyyy-MM-dd.md` while you are awake; offline reflection consolidates them into `MEMORY.md` and may distill repeated procedures into muscle-memory skills under `memory/skills/`. Both stages are run by subagents the runtime spawns on its own — not tools you call directly.
+
+This skill exists so you can answer the user's questions about your own memory honestly and so you do not corrupt it by hand-editing.
+
+## The two stages
+
+### Stage 1: memory-logger (online, per-session)
+
+After every prompt completes, the runtime fires the `session.idle` hook. The memory plugin starts a debounce timer (`memory.idleMs`, default `10_000` ms; minimum `1000`). Every subsequent prompt completion resets the timer. When the user has been quiet for `idleMs`, the plugin spawns the **memory-logger** subagent for the current session. It also fires immediately on `session.end` (websocket close) so the final transcript never gets lost.
+
+The memory-logger reads:
+
+1. `MEMORY.md` (long-term memory)
+2. The current `memory/yyyy-MM-dd.md` daily stream
+3. The transcript of the parent session past a watermark (the `entry=` value of the last fragment or watermark marker for that session)
+
+It writes zero or more **fragments** to today's stream, plus a watermark marker so the next run knows where to resume. It writes nothing else, and it cannot run shell commands or edit existing content (its only tools are `read` and a custom `append`-only file tool — append never truncates, and a leading `\n` is auto-inserted if the existing file did not end in one).
+
+A fragment looks like this in the daily stream:
+
+```
+<!-- fragment source=<sessionId> entry=<entryId> -->
+## <topic>
+
+**Claim:** <one-sentence assertion>
+**Evidence:** <verbatim quote, named premise, or enumerated occurrences>
+**Implication:** <how a future agent should behave differently because of this>
+```
+
+The Claim/Evidence/Implication structure is **required** and the bar is intentionally high: no Implication, no fragment. The memory-logger explicitly disallows promoting session-bound style/tone to a stable preference, speculation about the user's emotions or motives, and any claim it cannot justify with evidence already in the transcript or existing memory.
+
+### Stage 2: dreaming (offline, scheduled)
+
+The dreaming subagent runs on cron, configured under `memory.dreaming.schedule` (default `"*/30 * * * *"` — every 30 minutes). Multiple runs per day are the norm, not the exception; a fire with nothing past the watermark short-circuits before any LLM call, so most fires cost only a filesystem scan. The cron job id is `__plugin_memory_dreaming` (you cannot list it via the user-facing cron tools — it is plugin-owned).
+
+When dreaming fires, it reads:
+
+1. `MEMORY.md`
+2. The **undreamed tail** of every `memory/yyyy-MM-dd.md` (the runtime tells it the exact line range — earlier lines are already consolidated into `MEMORY.md` and must NOT be re-read)
+
+It rewrites `MEMORY.md` with the merged result, advances the per-day watermark in `memory/.dreaming-state.json`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, then `git commit -m "Dream"` the snapshot. After the commit, the runtime sets the `skip-worktree` index flag on the tracked memory artifacts so the user's `git status` and `git diff` stay clean. The flag is cleared and re-applied around every commit.
+
+The dreaming subagent has only three tools: `read`, `write`, `ls`. No `bash`. No `edit`. It cannot run shell commands.
+
+`MEMORY.md` after dreaming looks like:
+
+```
+# Memory
+
+## <topic>
+<conclusion paragraph in dreaming's own words>
+
+fragments:
+- memory/yyyy-MM-dd:<line>-<line>
+- memory/yyyy-MM-dd:<line>-<line>
+
+## <topic>
+<conclusion paragraph>
+
+fragments:
+- memory/yyyy-MM-dd:<line>-<line>
+```
+
+The first line is always `# Memory`. Topics are level-2 headings. Every topic cites the source fragments by `memory/yyyy-MM-dd:<line>-<line>` so any claim is traceable back to the daily stream entry that justified it.
+
+If the undreamed tails contain only watermarks, or every new fragment is already represented in `MEMORY.md`, dreaming **does nothing** and exits without writing. The watermark advances either way. "No-op dreaming" is a normal outcome, not a failure.
+
+### What gets injected into your prompt every turn
+
+The plugin's `session.prompt` hook appends a `# Memory` section to your system prompt with:
+
+- `MEMORY.md` (truncated to 12 KB; if larger, the rest is dropped with a `[truncated]` marker)
+- The **undreamed tails** of each `memory/yyyy-MM-dd.md`, with bare watermark lines stripped (they are bookkeeping for the memory-logger, no signal for you)
+
+Already-consolidated content is not injected twice — once a day's stream is fully dreamed, the loader drops it from the prompt entirely.
+
+If `MEMORY.md` is missing, the section shows `[MISSING] Expected at: <path>`. If it exists but is empty (e.g. before the first dreaming run), it shows `[EMPTY] Present at <path> but has no content yet.`
+
+## What you must not do
+
+- **Do not edit `MEMORY.md` directly.** It is dreaming-owned. The default system prompt says this verbatim. If you write to `MEMORY.md` from a normal session, your edit will survive only until the next dreaming run, which rewrites the file from scratch using the consolidation logic above. The user's intent is almost never "diff-edit `MEMORY.md`" — see "When the user asks ..." below for the right routings.
+- **Do not write to `memory/yyyy-MM-dd.md`.** Daily streams are memory-logger's territory. The runtime reads watermarks out of these files; a hand-edit in the wrong place silently corrupts the cursor. (`memory/` is gitignored at the agent level but force-committed by the dreaming snapshot — your hand-edit there will not look untracked, but it will still be a bug.)
+- **Do not write to `memory/skills/<name>/SKILL.md`.** That is the _muscle memory_ layer, owned exclusively by the dreaming subagent. The `typeclaw-skills` skill says the same thing from the skills-system angle; this skill says it from the memory angle. If you want a hand-authored skill, put it in `.agents/skills/` instead.
+- **Do not write to `memory/.dreaming-state.json`.** It is internal bookkeeping (per-day line counts already consolidated). On malformed input the plugin fails open with empty state, so a wrong edit causes one redundant re-consolidation, but it is still a sign you misunderstood the contract.
+- **Do not promise the user that an `idleMs` or `dreaming.schedule` change took effect just because you edited `typeclaw.json`.** Both fields are **restart-required** — the plugin reads them once at boot, and `reload` does not re-run plugin factories. Tell the user to run `typeclaw restart` (host stage).
+- **Do not invent fragments.** If you find yourself wanting to "seed" a memory by hand, that is a symptom of the previous rules — surface the fact in your reply (so the memory-logger captures it) instead of writing to memory yourself.
+- **Do not echo `[truncated]` or `[MISSING]` markers back at the user as if they were part of remembered content.** They are runtime annotations.
+
+## When the user asks "what do you remember?"
+
+1. Read `MEMORY.md`. Summarize at the topic level — do not dump the whole file unless asked. Cite specific topics by their level-2 headings.
+2. If relevant to the current task, also read the undreamed-tail of recent `memory/yyyy-MM-dd.md` files for fresh observations not yet consolidated. (Note: these are already in your prompt under `# Memory`, so usually you can just refer to them rather than re-reading.)
+3. If `MEMORY.md` is `[MISSING]` or `[EMPTY]`, say so plainly. The first dreaming run creates the file; if dreaming has never fired (e.g. no `memory.dreaming.schedule` configured, or fewer than ~24 hours since hatching), there is genuinely nothing yet.
+
+## When the user asks "do you remember X?"
+
+1. Search `MEMORY.md` and recent daily streams for a fragment matching X.
+2. If you find one: say what you found and cite the source (the topic heading from `MEMORY.md`, or the fragment line range from the daily stream).
+3. If you do not find one: say so plainly. **Do not invent a memory** to be helpful. The honest answer is "no, that is not in my memory" — the user can then decide whether to repeat the context now (which the memory-logger will pick up) or skip it.
+
+## When the user asks "forget X" / "remove X from your memory"
+
+You cannot remove a fragment cleanly. The right response depends on what X is:
+
+- **A fact in `MEMORY.md` that the user wants overridden** — surface a contradiction in your next reply ("noted: [X] is no longer correct, [Y] is what holds now"). The memory-logger picks the contradiction up as a fragment with the standard "supersedes existing memory" structure, and dreaming will replace the prior topic on its next run. The change is not instant — it lands at the next dreaming consolidation.
+- **A specific fragment in a daily stream the user wants gone before it gets consolidated** — read the file, locate the fragment, propose the surgical edit to the user, and (only if they confirm) `write` the edited file back. **Do not delete the watermark line on the same fragment** — that breaks the memory-logger's cursor for the originating session.
+- **Everything (full memory wipe)** — that is the user's call, not yours. Tell them: removing `MEMORY.md` is a one-line `rm`, but they should also remove `memory/.dreaming-state.json` so dreaming re-consolidates the still-present daily streams from scratch on its next run. If they want the daily streams gone too, `rm -rf memory/` (and the runtime will recreate the directory on the next memory-logger spawn). Confirm explicitly before any of this. Then commit the deletions with a `typeclaw-git`-compliant message naming what was removed and why.
+
+## When the user asks "what did you dream?" / "when do you dream next?"
+
+1. **What you dreamed**: read the most recent `Dream` git commit on your agent folder (`git log --grep='^Dream' -1`) and show the diff against `MEMORY.md` if useful. The commit timestamp tells you when dreaming last ran. If the answer is "no `Dream` commits yet", say that — `MEMORY.md` may exist but be the auto-created empty file from the first dreaming attempt.
+2. **When you dream next**: read `memory.dreaming.schedule` from `typeclaw.json` (default `"*/30 * * * *"` — every 30 minutes). Translate the cron expression to a wall-clock time in the agent's `TZ`. The dreaming cron job is **always registered** even when `memory.dreaming` is omitted; the default schedule applies. Tell the user honestly when the next fire is in the agent's local time.
+
+## When the user asks "what's a daily stream?" / "where is your memory stored?"
+
+Stay concrete. Use this map:
+
+| File / dir                      | What it is                                                                    | Who writes it                                                  | Tracked in git                                              |
+| ------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------- |
+| `MEMORY.md`                     | Long-term memory, consolidated topics with fragment citations.                | Dreaming subagent (rewrites in full on each run).              | Yes (force-committed under `Dream` commits, skip-worktree). |
+| `memory/yyyy-MM-dd.md`          | Daily fragment streams. Append-only during the day.                           | Memory-logger subagent (one fragment ≈ one prompt completion). | Gitignored, but force-committed in the dreaming snapshot.   |
+| `memory/skills/<name>/SKILL.md` | Muscle-memory skills distilled from recurring procedures.                     | Dreaming subagent only.                                        | Gitignored, force-committed in the dreaming snapshot.       |
+| `memory/.dreaming-state.json`   | Per-day watermarks (line counts already consolidated). Plain JSON, fail-open. | Dreaming subagent.                                             | Gitignored, force-committed in the dreaming snapshot.       |
+
+`typeclaw init` does **not** scaffold any of these. They appear when needed — `MEMORY.md` and `memory/` are created by the first dreaming run; daily streams appear when the first memory-logger fires.
+
+## When the user asks about `memory.idleMs` or `memory.dreaming.schedule`
+
+These are the only two configurable knobs. They live in the `memory` block of `typeclaw.json`:
+
+```json
+{
+  "memory": {
+    "idleMs": 10000,
+    "dreaming": { "schedule": "*/30 * * * *" }
+  }
+}
+```
+
+| Field                      | Default              | Effect                                                                                                                                                                                                        | Reload class      |
+| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `memory.idleMs`            | `10000` (min `1000`) | Debounce window before `memory-logger` spawns after a prompt completes.                                                                                                                                       | Restart-required. |
+| `memory.dreaming`          | `{}` (cron job on)   | Dreaming cron job is always registered. Override `schedule` to change when it fires.                                                                                                                          | Restart-required. |
+| `memory.dreaming.schedule` | `"*/30 * * * *"`     | Cron expression. Parsed via `cron-parser`; an invalid expression fails config load. Fires with nothing past the watermark short-circuit before any LLM call, so frequent no-op fires are intentionally cheap. | Restart-required. |
+
+Both fields are restart-required because plugin config is read once at boot. After editing them, tell the user: "Edited `memory.<field>` — restart-required. Run `typeclaw restart` (host stage) to pick up the change." The bundled plugin's config schema is merged into `typeclaw.schema.json`, so editor autocomplete will validate these fields, but a `reload` will not re-instantiate the plugin.
+
+To **disable dreaming entirely**, omit the `memory.dreaming` block. The cron job will not be registered. `MEMORY.md` will then never get consolidated automatically — the daily streams keep growing, and your prompt's `# Memory` section keeps showing more and more undreamed tails until the user re-enables dreaming. Warn them about this if they ask to disable it.
+
+To **shorten the memory-logger debounce** (e.g. for testing): drop `memory.idleMs` toward `1000`. Anything below `1000` is rejected by the config schema. Cost: more memory-logger spawns, more turn latency from the spawn handshake (the spawn is async but the LLM cost is real).
+
+## When you are unsure whether something belongs in memory
+
+Use this hierarchy. The first one that fits wins:
+
+1. **Operational lesson the next agent should follow** ("when the user says ‘ship it’, run typecheck before committing") → it belongs in **`AGENTS.md`**, not memory. AGENTS.md is your operating manual; memory is for facts and observations, not procedure rules.
+2. **A fact about the user** (their name, their preferences, their context) that you learned from this conversation → mention it in your reply with confident phrasing. The memory-logger will capture it. **Do not edit `USER.md` mid-session as a substitute for memory** — `USER.md` is for hatching-time identity and durable, user-confirmed traits, not for in-flight observations.
+3. **A multi-step procedure the user has guided you through more than once** that should become a reusable skill → flag the recurrence in your reply ("looks like we keep going through the same N-step flow for X"). Dreaming watches for repetition across daily streams and will distill it into `memory/skills/<name>/SKILL.md` if the bar is met (multi-step, recurred across multiple fragments / days, trigger conditions clearly statable, steps generalizable). You should not author muscle-memory skills directly.
+4. **An ephemeral observation** that doesn't change behavior — let it pass. Memory-logger has a strict bar; padding it with noise hurts the next agent's signal.
+
+## What this skill does _not_ cover
+
+- **The `bunx skills` CLI and the broader skill ecosystem** (system / user / muscle-memory layers, lockfile-based "downloaded vs hand-authored", `bunx skills add/remove/update` workflow) — see `typeclaw-skills`.
+- **Editing `typeclaw.json` outside the `memory` block** (port, model, mounts, plugins, channels) — see `typeclaw-config`.
+- **The cron file format and scheduling** (`cron.json`) — see `typeclaw-cron`. The dreaming cron job is plugin-owned and lives outside `cron.json`; you cannot configure or list it through the cron skill.
+- **Plugin authoring** (`definePlugin`, contributing tools/subagents/cron jobs) — see `typeclaw-plugins`. The memory plugin is an example of the patterns that skill describes.
+- **Identity files** (`IDENTITY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) — these are not memory. Edit them directly when relevant; no skill needed for that.

package/src/skills/typeclaw-monorepo/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: typeclaw-monorepo
+description: Use this skill whenever you are about to write code that another part of your agent folder might want to reuse, or you need to decide where new code goes. Triggers include "create a package", "extract this into a library", "make this reusable", "where should this script live", "add a workspace", "edit root scripts", "bun workspaces", "packages/", "monorepo", or any tool/utility/library you intend to call from more than one place. Read it before scaffolding anything under `packages/` — the layout has conventions for plugins, custom scripts, and root-level wiring that you must not improvise around.
+---
+
+# typeclaw-monorepo
+
+Your agent folder is a **bun monorepo**. The root `package.json` declares `"workspaces": ["packages/*"]`, and each subdirectory of `packages/` is a fully independent bun package that can be installed, depended on, and run from anywhere in the agent folder. This skill exists so you put new code in the right place, follow the workspace conventions, and do not surprise the user with random script files scattered around.
+
+## The two zones, and which to pick
+
+You have two free-write zones at the agent root: `workspace/` and `packages/`. Both are exempt from the non-workspace-write guard so you can edit them without acknowledging anything, but their relationship to git is opposite, and picking the wrong one is the most common mistake.
+
+| Zone         | Purpose                                                            | Tracked in git?                                                                                           | Reusable?                                    |
+| ------------ | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| `workspace/` | One-off scripts, scratch work, throwaway experiments               | **No** — entire dir is gitignored                                                                         | No (the dir itself is invisible to git)      |
+| `packages/`  | Reusable packages, custom plugins, shared utilities, internal libs | **Yes** — every file is tracked and MUST be committed when edited (only `*/node_modules/` ignored inside) | Yes (committed and importable across agents) |
+
+The two columns to internalize:
+
+- **Guard allowlist** (write permission): `workspace/` and `packages/` are both free-write — no `acknowledgeGuards` needed. This is about whether the agent can write the file at all.
+- **Git tracking** (persistence): `workspace/` is gitignored end-to-end (a true scratch zone, lost on clone), while `packages/` is fully tracked (committed to git, shipped with the agent folder, visible in PRs). This is about whether the file survives.
+
+Anything you put in `packages/` MUST land in a commit — see `typeclaw-git`. The non-`node_modules/` files in `packages/` are not gitignored; treating them as throwaway will surprise the user when their PR includes a half-baked package they did not expect.
+
+**Decision rule, top to bottom — stop at the first match:**
+
+1. **Will another script or another part of the agent folder import this?** → `packages/<name>/`. Even if "another part" is just "tomorrow's me writing a sibling script", a reusable thing belongs here.
+2. **Is this a custom typeclaw plugin** (anything you'd list in `typeclaw.json`'s `plugins`)? → `packages/<plugin-name>/`. Always. Plugins are the canonical packages.
+3. **Will the user want to track this in git, see it in PRs, depend on it from a cron job?** → `packages/<name>/`.
+4. **Is this throwaway** — a one-shot data transformation, a debug script, a scratch experiment that exists for one task and dies? → `workspace/`.
+5. **Default if unsure** → `packages/<name>/`. Better to commit something reusable than to lose something useful in the gitignored void.
+
+The hidden cost of getting this wrong: code in `workspace/` is invisible to git (the entire `workspace/` dir is gitignored as a "free-write zone"), so a reusable utility you put there will silently disappear on the next clone, the next session that runs `git clean`, or the next time a user tarballs the agent folder for backup.
+
+## Anatomy of a `packages/<name>/` package
+
+A bun workspace package is just a normal package directory:
+
+```
+packages/
+  my-utility/
+    package.json        # name, version, dependencies, scripts
+    index.ts            # entrypoint
+    index.test.ts       # tests, if appropriate
+```
+
+Minimal `packages/my-utility/package.json`:
+
+```json
+{
+  "name": "my-utility",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  }
+}
+```
+
+Notes that catch people:
+
+- **`private: true`** keeps the package out of any accidental publish. Default to `true` unless the user explicitly asks for a publishable package.
+- **`type: "module"`** matches the agent root and avoids ESM/CJS surprises. Always set it.
+- **`main` and `exports` point at `index.ts` directly.** Bun executes TypeScript natively in the workspace; no build step required.
+- **`name` is the import specifier.** `import { foo } from 'my-utility'` works from anywhere in the agent folder once you `bun install`. Pick a name you would not be embarrassed to type — descriptive and lowercase, no scope unless you have a reason.
+- **No version churn.** Workspace packages stay at `0.0.0` unless the user explicitly versions them. Bun resolves them by name, not by version.
+
+## Wiring a workspace package into another package
+
+To depend on `packages/my-utility` from another package (e.g. `packages/my-plugin`), add it to that package's `dependencies` with the workspace protocol:
+
+```json
+{
+  "name": "my-plugin",
+  "dependencies": {
+    "my-utility": "workspace:*"
+  }
+}
+```
+
+Then `bun install` from the agent folder root. Bun symlinks the workspace package into `packages/my-plugin/node_modules/my-utility` and `import` resolves it normally. The `*` matches any version because workspace packages don't track versions.
+
+To depend on a workspace package from the **agent root** (e.g. so cron `exec` jobs or root scripts can call into it), add it to the **root** `package.json#dependencies` the same way:
+
+```json
+{
+  "dependencies": {
+    "typeclaw": "file:../typeclaw",
+    "agent-browser": "^0.26.0",
+    "my-utility": "workspace:*"
+  }
+}
+```
+
+## Custom typeclaw plugins live under `packages/`
+
+If you are writing a typeclaw plugin (anything that uses `definePlugin` from `typeclaw/plugin`), the canonical home is `packages/<plugin-name>/`. The workflow:
+
+1. **Author**: `packages/my-plugin/index.ts` exports `definePlugin({ ... })` as default.
+2. **Wire**: edit `typeclaw.json` so the `plugins` array contains the local path:
+
+   ```json
+   {
+     "plugins": ["./packages/my-plugin"]
+   }
+   ```
+
+3. **Per-plugin config block** uses the **derived name** (basename of the path with extensions stripped — see the `typeclaw-plugins` skill for the full naming rule). For `./packages/my-plugin`, the derived name is `my-plugin`, so:
+
+   ```json
+   {
+     "plugins": ["./packages/my-plugin"],
+     "my-plugin": {
+       "/* ... your config ... */": ""
+     }
+   }
+   ```
+
+4. **Restart**: `plugins[]` is `restart-required`. Run `typeclaw restart` (or call the `restart` tool); reload alone will not pick up a new plugin entry.
+
+Read the `typeclaw-plugins` skill before authoring the plugin code — it covers `definePlugin`, hooks, tools, subagents, cron, the engine boundary, and the failure-mode error messages.
+
+## Editing the root `package.json`
+
+The root `package.json` is in the agent root's writable allowlist (alongside `AGENTS.md`, `IDENTITY.md`, etc.) and is fair game for additions. **Welcome editing patterns:**
+
+- **`scripts`**: add convenience scripts the user (or you, in cron `exec` jobs) can run. Example: `"scripts": { "summarize": "bun run packages/summarizer/index.ts" }`. Then `bun summarize` from anywhere in the agent folder runs it.
+- **`dependencies`** / **`devDependencies`**: add libraries you actually use. Run `bun install` after adding. Don't add deps speculatively — only what the code imports today.
+- **`workspaces`**: by default `["packages/*"]`. The user may extend it (e.g. `["packages/*", "tools/*"]`) if they want a second workspace root. Don't change the existing entry without a reason.
+
+**Patterns to avoid at the root:**
+
+- **Don't add a `main` or `bin` field at the root.** The root package is a workspace coordinator, not an executable. Put entrypoints inside `packages/<name>/`.
+- **Don't change `name`, `private`, or `type`.** These are scaffolded by typeclaw and the rest of the system assumes them.
+- **Don't add the typeclaw or agent-browser deps to packages.** They live at the root and are shared via the bun workspace mechanism. If a workspace package needs typeclaw types, depend on it via `"typeclaw": "workspace:*"` only if it needs the plugin SDK at runtime — and even then, `import { definePlugin } from 'typeclaw/plugin'` resolves through the root's `node_modules` automatically.
+
+## When you start a new package, do this exactly
+
+1. **Pick a name.** Lowercase, kebab-case, descriptive. `journal-store`, not `js`. Plugin packages are named after what the plugin does, not what it is — `standup-log`, not `my-plugin`.
+2. **Create the directory.** `packages/<name>/`.
+3. **Write `package.json`** using the minimal template above. Set `name` to the directory name (they don't have to match, but matching avoids confusion).
+4. **Write `index.ts`** with the actual code.
+5. **Add tests** as `<file>.test.ts` next to the implementation if the logic is non-trivial.
+6. **`bun install` from the agent root** — only needed when you add dependencies. Bun automatically links new workspace packages on install; you don't need to manually register the package anywhere.
+7. **Commit.** Per `typeclaw-git`, commit the new package immediately with the decision context — why this is reusable, what it solves.
+
+## `bun install` and the monorepo
+
+Run `bun install` **from the agent root**, never from inside a `packages/<name>/` directory. The root install:
+
+- Resolves all workspace packages and creates symlinks
+- Hoists shared dependencies to the root `node_modules/`
+- Honors per-package dependencies that are not in the root
+
+Per-package `node_modules/` is gitignored (`packages/*/node_modules/` in `.gitignore`), but those directories rarely have anything in them after a hoist — bun puts most things at the root.
+
+If you see `Cannot find module 'my-utility'` after creating a new workspace package, the fix is `bun install` from the agent root. There is no separate "register the workspace" step.
+
+## Things you must not do
+
+- **Do not put reusable code in `workspace/`.** It will be lost. Re-read the decision rule above if you're tempted.
+- **Do not put one-off throwaway scripts in `packages/`.** Each `packages/<name>` is a real package the user will see in git, in PRs, and in dependency graphs. Keep it small. If it's a 10-line script that runs once, `workspace/scratch-<date>.ts` is correct.
+- **Do not edit the root `workspaces` field to point outside `packages/*`** unless the user explicitly asks. The default convention is part of the agent's identity layout; extending it surprises every other tool that walks the workspace.
+- **Do not version workspace packages with semver** unless the user is publishing them. Internal packages stay at `0.0.0` and depend on each other via `workspace:*`.
+- **Do not nest workspaces.** A package inside `packages/` cannot itself declare `workspaces`. Bun rejects nested workspaces, and even if it didn't, the cognitive load is not worth it.
+- **Do not add `node_modules/` to `packages/<name>/.gitignore`.** The root `.gitignore` already covers `packages/*/node_modules/`. Adding a sub-`.gitignore` is noise that will get out of sync.
+
+## Cross-references
+
+- **`typeclaw-plugins`** — read this before authoring any custom plugin. Covers the plugin SDK, hooks, tools, subagents, cron, naming derivation, and failure modes.
+- **`typeclaw-git`** — commit policy. Every new package and every meaningful edit to `package.json` (root or workspace) gets a commit immediately with decision context.
+- **`typeclaw-cron`** — if your package is invoked from a cron job, the `prompt` vs `exec` choice and the schedule semantics live there.