@moxxy/cli 0.0.0

package/dist/read-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../tools-builtin/src/util.ts","../../tools-builtin/src/read-handler.ts"],"names":["fs"],"mappings":";;;;;AAcO,SAAS,WAAA,CAAY,KAAa,MAAA,EAAwB;AAC/D,EAAA,IAAS,IAAA,CAAA,UAAA,CAAW,MAAM,CAAA,EAAG,OAAY,eAAU,MAAM,CAAA;AACzD,EAAA,OAAY,IAAA,CAAA,OAAA,CAAQ,KAAK,MAAM,CAAA;AACjC;AAsBO,IAAM,WAAA,GAAc,WAAA;AAEpB,SAAS,WAAA,CAAY,GAAW,GAAA,EAAqB;AAC1D,EAAA,IAAI,CAAA,CAAE,MAAA,IAAU,GAAA,EAAK,OAAO,CAAA;AAC5B,EAAA,OAAO,CAAA,CAAE,KAAA,CAAM,CAAA,EAAG,GAAG,CAAA,GAAI;AAAA,eAAA,EAAoB,CAAA,CAAE,SAAS,GAAG,CAAA,OAAA,CAAA;AAC7D;;;ACnBA,eAAsB,WAAA,CAAY,OAAkB,GAAA,EAAmC;AACrF,EAAA,MAAM,EAAE,SAAA,EAAW,MAAA,GAAS,CAAA,EAAG,KAAA,GAAQ,KAAK,GAAI,KAAA;AAChD,EAAA,MAAM,QAAA,GAAW,WAAA,CAAY,GAAA,CAAI,GAAA,EAAK,SAAS,CAAA;AAO/C,EAAA,MAAM,OAAO,GAAA,CAAI,EAAA,GACb,MAAM,GAAA,CAAI,EAAA,CAAG,SAAS,QAAA,EAAU,EAAE,UAAU,MAAA,EAAQ,KACnD,MAAMA,QAAA,CAAG,SAAS,QAAQ,CAAA,EAAG,SAAS,MAAM,CAAA;AACjD,EAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,KAAA,CAAM,IAAI,CAAA;AAC7B,EAAA,MAAM,MAAA,GAAS,KAAA,CAAM,KAAA,CAAM,MAAA,EAAQ,SAAS,KAAK,CAAA;AACjD,EAAA,MAAM,QAAA,GAAW,OACd,GAAA,CAAI,CAAC,MAAM,CAAA,KAAM,CAAA,EAAG,OAAO,MAAA,GAAS,CAAA,GAAI,CAAC,CAAA,CAAE,QAAA,CAAS,GAAG,GAAG,CAAC,IAAK,IAAI,CAAA,CAAE,CAAA,CACtE,IAAA,CAAK,IAAI,CAAA;AACZ,EAAA,OAAO,WAAA,CAAY,UAAU,GAAO,CAAA;AACtC","file":"read-handler.js","sourcesContent":["import * as path from 'node:path';\n\n/**\n * Normalize `target` against `cwd`. Returns an absolute path. **Does not\n * sandbox** — absolute targets and `../` traversal are allowed by design,\n * because the agent often needs to touch paths outside the cwd (`~/.config`,\n * `/etc/...`). Safety against unintended access lives at the permission\n * layer (`PermissionEngine` + the resolver), which prompts the user before\n * any tool runs. Tools that genuinely need to confine to cwd should use\n * `resolveWithinCwd` instead.\n *\n * Renamed from `resolveSafe` to make the contract honest — the old name\n * implied a sandbox it never performed.\n */\nexport function resolvePath(cwd: string, target: string): string {\n  if (path.isAbsolute(target)) return path.normalize(target);\n  return path.resolve(cwd, target);\n}\n\n/**\n * Like `resolvePath` but throws if the result escapes `cwd`. Use for tools\n * that should be strictly confined (rare).\n */\nexport function resolveWithinCwd(cwd: string, target: string): string {\n  const resolved = resolvePath(cwd, target);\n  const cwdAbs = path.resolve(cwd);\n  const rel = path.relative(cwdAbs, resolved);\n  if (rel.startsWith('..') || path.isAbsolute(rel)) {\n    throw new Error(\n      `Path escapes cwd: ${target} (resolved to ${resolved}, outside ${cwdAbs})`,\n    );\n  }\n  return resolved;\n}\n\n/**\n * @deprecated Use `resolvePath` (no behavior change — only honest name).\n * Kept as a thin alias so external callers still compile.\n */\nexport const resolveSafe = resolvePath;\n\nexport function clampString(s: string, max: number): string {\n  if (s.length <= max) return s;\n  return s.slice(0, max) + `\\n... [truncated ${s.length - max} chars]`;\n}\n\n/**\n * Convert a glob pattern (`**`, `*`, `?`) to an anchored RegExp. Shared by\n * the Glob and Grep tools; not exposed externally.\n */\nexport function globToRegExp(pattern: string): RegExp {\n  const escaped = pattern\n    .replace(/[.+^${}()|[\\]\\\\]/g, '\\\\$&')\n    .replace(/\\?/g, '[^/]')\n    .replace(/\\*\\*\\//g, '(?:.*/)?')\n    .replace(/\\*\\*/g, '.*')\n    .replace(/\\*/g, '[^/]*');\n  return new RegExp('^' + escaped + '$');\n}\n","import { promises as fs } from 'node:fs';\nimport type { BrokeredFs } from '@moxxy/sdk';\nimport { clampString, resolveSafe } from './util.js';\n\n/**\n * Pure handler module for the Read tool. Lives in its own file so the\n * worker_threads isolator (`@moxxy/isolator-worker`) can re-import it\n * on the worker side via the `handlerModule` reference declared in\n * `read.ts`.\n *\n * Closures can't cross thread boundaries; module exports can.\n */\nexport interface ReadInput {\n  readonly file_path: string;\n  readonly offset?: number;\n  readonly limit?: number;\n}\n\nexport interface ReadCtxLike {\n  readonly cwd: string;\n  /** Capability-mediated fs. Present when invoked under an isolator that\n   *  brokers (`@moxxy/isolator-worker`); absent under `none` / `inproc`. */\n  readonly fs?: BrokeredFs;\n}\n\nexport async function readHandler(input: ReadInput, ctx: ReadCtxLike): Promise<string> {\n  const { file_path, offset = 0, limit = 2000 } = input;\n  const resolved = resolveSafe(ctx.cwd, file_path);\n  // Use the brokered fs when the isolator provides one. The broker\n  // re-validates the path against the tool's declared `caps.fs.read`\n  // on the parent side, so reads outside the cap are denied at the\n  // boundary regardless of what's in the input. Without a broker\n  // (inproc / none), fall back to direct `node:fs` — input-level\n  // cap-check already screened the file_path.\n  const text = ctx.fs\n    ? await ctx.fs.readFile(resolved, { encoding: 'utf8' })\n    : (await fs.readFile(resolved)).toString('utf8');\n  const lines = text.split('\\n');\n  const sliced = lines.slice(offset, offset + limit);\n  const numbered = sliced\n    .map((line, i) => `${String(offset + i + 1).padStart(6, ' ')}\\t${line}`)\n    .join('\\n');\n  return clampString(numbered, 200_000);\n}\n"]}

package/dist/skills/add-mcp-server.md

@@ -0,0 +1,47 @@
+---
+name: add-mcp-server
+description: Register a new Model Context Protocol (MCP) server with moxxy and author a usage skill for its tools.
+triggers:
+  - add mcp
+  - new mcp
+  - mcp server
+  - hook up mcp
+  - register mcp
+  - install mcp
+allowed-tools:
+  - mcp_test_server
+  - mcp_add_server
+  - mcp_list_servers
+  - synthesize_skill
+---
+
+When the user wants to add an MCP server, walk them through these steps:
+
+1. **Gather the connection details**
+   - Ask what KIND the server is:
+     - `stdio` — a local executable (npm/uv package, custom script). Need `command`, optional `args`, `env`, `cwd`.
+     - `http` or `sse` — a remote HTTP server. Need `url`, optional `headers` (for auth).
+   - Ask what NAME to use. Must be slug-like (lowercase letters, digits, hyphens). The name prefixes every tool the server exposes — pick something short and recognizable (e.g. `canva`, `github`, `fs`).
+
+2. **Test the connection BEFORE persisting**
+   - Call `mcp_test_server` with the gathered details.
+   - On success, the result lists the tools the server exposes. Show them to the user.
+   - On failure, report the error verbatim and ask the user how they want to proceed (different URL, different command, give up).
+
+3. **Persist the server**
+   - Once the user confirms, call `mcp_add_server` with the same arguments. This connects to the server, registers its tools into the live session (no restart needed), and writes to `~/.moxxy/mcp.json` so the entry survives across sessions.
+   - The response includes a `tools` array — those names are now in the session's tool catalog with an `mcp__<server>__` prefix.
+
+4. **Author a usage skill (optional but recommended)**
+   - Offer to create a skill that documents how to use the new MCP's tools. This makes future invocations cleaner — the user can say "search canva for X" instead of remembering tool names.
+   - If they accept, call `synthesize_skill` with an `intent` describing the common workflow. The skill body should mention the prefixed tool names (e.g. `mcp__canva__search_designs`) and a typical multi-step recipe.
+
+5. **Confirm + summarize**
+   - List what was done: connection tested, server attached + saved, skill created (if applicable).
+   - The new tools are usable RIGHT NOW in this turn — you can demonstrate one if the user asks.
+
+## Notes
+
+- `mcp_list_servers` shows what's currently registered.
+- `mcp_remove_server` removes a registration.
+- The user might already have an entry in `~/.moxxy/mcp.json` — call `mcp_list_servers` first to check before suggesting a name.

package/dist/skills/add-provider.md

@@ -0,0 +1,131 @@
+---
+name: add-provider
+description: Register a new LLM provider (z.ai, deepseek, groq, openrouter, fireworks, together, mistral, perplexity, …) with moxxy and configure its API key so the user can switch to it.
+triggers:
+  - add provider
+  - new provider
+  - install provider
+  - register provider
+  - add z.ai
+  - add deepseek
+  - add groq
+  - add openrouter
+  - add fireworks
+  - add together
+  - add mistral
+  - add perplexity
+allowed-tools:
+  - provider_add
+  - provider_list
+  - provider_remove
+  - provider_test
+  - vault_status
+  - vault_list
+---
+
+The user wants to add a new LLM provider to moxxy so they can switch to it later (`/provider <name>` or via `provider.name` in moxxy.config.ts). Walk them through these steps; be terse and pause for confirmation between gather → register → key.
+
+## Scope
+
+This skill only handles **OpenAI-compatible** vendors — i.e. those that expose a Chat Completions endpoint shaped like OpenAI's (`/v1/chat/completions`, tool-call format, streaming with `data:` chunks). That covers the vast majority of modern API vendors: z.ai (GLM), deepseek, groq, openrouter, fireworks, together, mistral, perplexity, anyscale, deepinfra, octoai, and many more.
+
+If the vendor speaks a different protocol (Anthropic-style, Google Vertex, custom), tell the user this skill can't handle it and direct them to author a full provider plugin (see `.claude/agents/provider-author.md`).
+
+## 1. Gather the basics
+
+Ask the user, or infer from their request:
+
+- **Provider slug** — short lowercase identifier (e.g. `zai`, `deepseek`, `groq`, `openrouter`). This becomes the registry key, the canonical vault entry name (`<SLUG>_API_KEY`), and what the user types in `/provider <slug>`. Must match `[a-z][a-z0-9-]*`.
+- **API base URL** — the vendor's OpenAI-compatible endpoint root. Examples:
+  - z.ai → `https://api.z.ai/api/coding/paas/v4`
+  - deepseek → `https://api.deepseek.com`
+  - groq → `https://api.groq.com/openai/v1`
+  - openrouter → `https://openrouter.ai/api/v1`
+  - fireworks → `https://api.fireworks.ai/inference/v1`
+  - together → `https://api.together.xyz/v1`
+  - mistral → `https://api.mistral.ai/v1`
+- **Default model id** — the model to use when no other is specified (you'll usually pick the vendor's "flagship" or "best general purpose" model).
+
+If the user hasn't given you the baseURL, look it up via WebFetch on the vendor's docs (search for "openai compatible", "base url", "endpoint") and propose it back to them for confirmation. **Do not guess.**
+
+## 2. Discover the model list
+
+You need to populate a `models` array. Each entry needs `id`, `contextWindow`, `maxOutputTokens?`, `supportsTools`, `supportsStreaming`, `supportsImages?`, `supportsAudio?`.
+
+Two paths, in order of preference:
+
+1. **WebFetch the vendor's models / pricing page** to extract the current catalog. Good search prompts: `"<vendor> models pricing context window"`, `"<vendor> api models list"`. Common locations:
+   - z.ai → `https://docs.z.ai/guides/llm/glm-4.6`, `https://z.ai/pricing`
+   - deepseek → `https://api-docs.deepseek.com/quick_start/pricing`
+   - groq → `https://console.groq.com/docs/models`
+   - openrouter → `https://openrouter.ai/models`
+   - fireworks → `https://fireworks.ai/models`
+2. **The vendor's `/v1/models` endpoint** lists canonical model ids (but not context windows). This needs the API key, which you will NOT have (see step 3 — the key goes straight into the vault, never to you). So prefer WebFetch for discovery; if you must use `/v1/models`, ask the user to run it themselves and paste the model-id list (not the key).
+
+Build the list, show it to the user as a markdown table (id / context / tools / images), and ask them to confirm or trim. **Do not invent context-window numbers.** If a model's context is unknown, ask the user or leave it out.
+
+Tool-call support and streaming default to `true` for OpenAI-compatible vendors (their /v1/chat/completions endpoint inherits both). Only flip them to `false` if you've confirmed the vendor doesn't.
+
+## 3. Store the API key in the vault — via the `/vault` command
+
+**Never ask the user to paste their API key to you.** The key must not pass through the conversation or a tool argument (both are visible to you). Instead, tell the user to store it themselves:
+
+```
+/vault set <SLUG>_API_KEY <their-key>
+```
+
+Use the uppercase slug, e.g. "Please run `/vault set DEEPSEEK_API_KEY <your-key>` — the value stays local; I'll only get a reference." `<SLUG>_API_KEY` is moxxy's canonical resolution path (config.apiKey → vault → env → prompt), so once it's there the provider picks it up automatically. **Stop and wait** for the user to confirm before continuing.
+
+After they run it you'll get a note confirming storage and the reference `${vault:<SLUG>_API_KEY}` — you never see the key itself.
+
+## 4. (Optional) Test the endpoint
+
+`provider_test` needs the plaintext key, which you don't have — so don't call it with the key yourself. To verify the endpoint, either:
+- ask the user to run a quick check themselves, or
+- skip ahead: after registering (step 5), have the user run `moxxy doctor`, which resolves `<SLUG>_API_KEY` from the vault and reports whether the provider's key is present.
+
+## 5. Register the provider
+
+Call `provider_add` with the gathered fields:
+
+```json
+{
+  "kind": "openai-compat",
+  "name": "<slug>",
+  "baseURL": "<base url>",
+  "defaultModel": "<id>",
+  "models": [
+    { "id": "<id>", "contextWindow": 200000, "supportsTools": true, "supportsStreaming": true }
+  ]
+}
+```
+
+`provider_add` does two things atomically:
+1. Registers the provider in the LIVE session — switchable immediately.
+2. Persists to `~/.moxxy/providers.json` so it survives restarts.
+
+If `provider_add` returns `{ replaced: true }`, mention that to the user — it means a provider with the same slug already existed and they just overwrote it.
+
+## 6. Help them switch to it (optional)
+
+Ask if they want this provider as the default:
+
+- **Just this session** → suggest `/provider <slug>` (typed in the TUI). Don't do it for them unless asked.
+- **Permanently** → offer to edit `moxxy.config.ts` and set `provider.name` (and optionally `provider.model`) to the new values. Use the Edit tool. Mention they can run `moxxy doctor` afterward to confirm the key resolves.
+
+## 7. Summarize
+
+Report:
+- Provider slug + baseURL + default model.
+- That the API key is in the vault under `<SLUG>_API_KEY` (the user stored it via `/vault set`).
+- That `~/.moxxy/providers.json` was updated and the provider is live this session.
+- How to switch to it.
+
+## Don't
+
+- Don't ask the user to paste their API key to you, and don't call any tool with the key as an argument. Direct them to `/vault set <SLUG>_API_KEY <key>` so it never enters the conversation.
+- Don't invent baseURLs, model ids, or context windows. If you're not sure, WebFetch or ask.
+- Don't store the API key anywhere except the vault. Never write it into a file in the repo, never echo it back.
+- Don't try to handle non-OpenAI-compatible vendors here — those need a real provider plugin (`.claude/agents/provider-author.md`).
+- Don't overwrite an existing provider slug without telling the user first. Call `provider_list` if you're unsure whether the slug is taken.
+- Don't auto-edit `moxxy.config.ts` to switch the default without asking. The user may want to keep their current provider as primary.

package/dist/skills/explain-event-log.md

@@ -0,0 +1,15 @@
+---
+name: explain-event-log
+description: Walk the user through the moxxy event log for the current session.
+triggers: ["show event log", "explain events", "what happened"]
+allowed-tools: []
+---
+# Explain the event log
+
+When the user wants to understand what happened in this session:
+
+1. Summarize the most recent turn: which tools ran, which were denied, the final assistant message.
+2. Highlight any `error`, `tool_call_denied`, or `compaction` events.
+3. If the user asks "why did X happen?", trace the `causationId` chain.
+
+Be terse — one bullet per event class. Don't dump raw JSON.

package/dist/skills/generative-ui.md

@@ -0,0 +1,120 @@
+---
+name: generative-ui
+description: Generate an interactive, navigable UI (a "generative UI" / "dynamic UI" / "agentic UI") for the user — rendered in their browser, backed by real data from your tools. Only when the user explicitly asks for a generative/dynamic/agentic UI.
+triggers: ["generative ui", "dynamic ui", "agentic ui", "generative interface", "dynamic interface", "agentic interface", "interactive ui for", "generative app", "agentic app"]
+allowed-tools: [present_view, web_fetch, browser_session]
+---
+
+# Generative UI
+
+Generate an interactive, navigable UI — a "generative / dynamic / agentic UI" — for
+the user, backed by **real data**, and hand them a link.
+
+## When to use this — and when NOT to
+
+**Use `present_view` ONLY when the user explicitly asks for a generative / dynamic /
+agentic UI (or interface).**
+
+- ✅ "present me a generative ui for arXiv papers"
+- ✅ "show me a dynamic ui for flight search WAW→KRK"
+- ✅ "make me an agentic ui for my GitHub repos", "interactive ui for X"
+- ❌ "search flights SFO→JFK", "find me papers on transformers", "what's the weather"
+  → **answer in plain text. Do NOT generate a UI.** Ordinary searches/questions are
+  handled the way you always have.
+
+If you're unsure, default to a normal text answer. A generative UI is for when the
+user wants a *thing they can use*, not a one-off answer.
+
+## Use REAL data — never demo data
+
+The UI must show **real results fetched from real sources**, not placeholders you made
+up. Get data with your tools — `web_fetch` (JSON APIs, public endpoints, HTML pages),
+`browser_session` (JS-heavy sites), or any MCP/provider tool available. **Never
+fabricate results, prices, IDs, or links.** If you can't find a usable data source,
+render a clear message saying so (a `card` with `text tone="warn"`) instead of
+inventing data.
+
+## Render upfront — don't make the user re-ask
+
+If the user already gave you the parameters (e.g. "WAW → KRK"), **go straight to
+results in the same turn** — don't show an empty form and wait for them to submit
+what they already told you. Generate the populated UI now.
+
+## The loader-first flow (every fetch)
+
+A `present_view` call flushes to the browser immediately, so within ONE turn:
+
+1. `present_view` a **loading** screen (skeleton / spinner) under a screen `name`.
+2. Fetch the **real** data with your tools.
+3. `present_view` the **results** under the **same `name`** — it replaces the
+   skeleton in place.
+
+Use the same `name` for the loading and loaded states so the result swaps the
+skeleton in place (don't leave a dangling "loading" screen).
+
+### Example: "present me a dynamic ui for flight search WAW → KRK"
+
+Turn 1, call 1 — show the loading state instantly:
+
+```xml
+<view name="results" title="WAW → KRK">
+  <text tone="muted">Searching live flights…</text>
+  <skeleton rows="5" />
+</view>
+```
+
+Then fetch real data (`web_fetch` a flights API / source). Turn 1, call 2 — replace
+with real results under the same name:
+
+```xml
+<view name="results" title="WAW → KRK · 4 flights">
+  <results>
+    <result title="LOT LO3923" subtitle="06:40 → 07:55 · nonstop" badge="PLN 320" action="open:LO3923" />
+    <result title="Ryanair FR2118" subtitle="20:10 → 21:25 · nonstop" badge="PLN 149" action="open:FR2118" />
+  </results>
+  <link to="search">↻ Refine search</link>
+</view>
+```
+
+Also build a `search` screen (a `form action="run_search"` with from/to/date inputs,
+pre-filled) so the user can refine; on submit you repeat the loader-first flow.
+
+## The UI model
+
+Multiple named screens the user navigates between (one `present_view` per screen):
+
+- **`to="<screenName>"`** on a `link`/`button` → jumps to that screen
+  **instantly, client-side, with no new turn** (if you've already built it).
+- **`action="…"`** on a form/button → sends an **agent turn** back to you (this is
+  how search / fetch-detail work — fetch real data, then render the next screen).
+- A built-in **Back** button returns to previous screens for free.
+- A floating chat button on the surface lets the user ask for refinements; treat
+  those as normal prompts — re-render the affected screen with `present_view` (same
+  `name`) to update it live.
+
+Clicking a result sends `[ui-action] {"action":"open:LO3923"}` → fetch that record's
+real details → build a `detail:LO3923` screen with `<link to="results">← Back</link>`.
+
+## Vocabulary (allow-listed — unknown tags/attrs are rejected)
+
+**Layout:** `view`(name?,title?) · `stack`(gap?,align?) · `row`(gap?,align?,justify?) ·
+`grid`(cols 1-6) · `card`(title?,accent?) · `divider`.
+**Loading:** `spinner`(label?) · `skeleton`(rows 1-12).
+**Display:** `heading`(level 1-3) · `text`(tone?,weight?) · `badge`(tone?) ·
+`image`(src,alt?) · `link`(href? OR to?) · `list`(ordered?)/`item` · `table`/`tr`/`th`/`td`.
+**Inputs (in a `form`):** `form`(action,submit?) · `input`(name,type?,label?,placeholder?,value?,required?) ·
+`select`(name,…)/`option`(value) · `checkbox`(name,label?) ·
+`button`(label, **action** OR **to**, variant?, fields?).
+**Component:** `results` → `result`(title, subtitle?, badge?, id?, action? | to?).
+
+## Rules
+
+- One `<view>` root per call; give each screen a `name`; loading + loaded share the name.
+- `to=` navigates between your screens; `action=` only for work you must do (fetch).
+- Allow-listed tags/attrs only. `href`/`src` must be `https:`/`mailto:`/relative.
+  Enums: `card accent` & `text/badge tone` ∈ `default|muted|success|warn|danger`;
+  `gap` ∈ `none|sm|md|lg`.
+- **Share the EXACT `url` from the present_view result.** Never invent a path like
+  `/app/search`. If the result is `rendered:false` or has no `url`, the surface isn't
+  running — say so instead of guessing a link.
+- Always pass `fallbackText` (a one-line summary).

package/dist/skills/remember-this.md

@@ -0,0 +1,34 @@
+---
+name: remember-this
+description: Save a fact, preference, project note, or reference to long-term memory for future sessions.
+triggers: ["remember", "save this", "for later", "memorize", "note that"]
+allowed-tools: [memory_save, memory_list, memory_recall, memory_update]
+---
+# Remember this
+
+The user wants you to commit something to long-term memory so it's available in future sessions.
+
+## Decide the type
+
+- **fact**: a static piece of knowledge ("the API endpoint is X")
+- **preference**: how the user wants you to work ("they prefer terse responses")
+- **project**: context about the project they're working on
+- **reference**: a pointer to external info ("docs live at confluence.example.com")
+
+## Workflow
+
+1. **Distill** what the user just said into 1–2 sentences. If the original was a long ramble, summarize. If it was already terse, keep it.
+2. **Check existing memories** with `memory_recall(query)` for similar entries. If a related entry exists, prefer `memory_update` over creating a new one — don't fragment.
+3. **Save** with `memory_save({ name, type, description, body, tags })`:
+   - `name`: slug, ≤60 chars, kebab-case
+   - `description`: one sentence, ≤120 chars — this is what shows in the index
+   - `body`: ≤30 lines; the actual content
+   - `tags`: optional, lowercase keywords for cross-cutting topics
+
+4. **Confirm** briefly: "Saved as `<name>`."
+
+## Don't
+
+- Don't save secrets here — use the vault.
+- Don't save ephemeral state (open files, current cursor position, etc.). Memories should be useful in any future session.
+- Don't create overlapping entries. If unsure, recall first.

package/dist/skills/scheduling.md

@@ -0,0 +1,95 @@
+---
+name: scheduling
+description: Create, inspect, and manage recurring or one-shot scheduled prompts that fire on a cron or a specific timestamp.
+triggers:
+  - schedule
+  - cron
+  - every day
+  - every hour
+  - in an hour
+  - tomorrow at
+  - heartbeat
+  - reminder
+  - daily briefing
+  - recurring
+  - automate
+allowed-tools:
+  - schedule_create
+  - schedule_list
+  - schedule_delete
+  - schedule_enable
+  - schedule_disable
+  - schedule_run_now
+  - telegram_send_message
+---
+
+Use this skill when the user wants a prompt to fire automatically — recurring on a cron, or once at a fixed time. Each scheduled run starts a fresh turn, the assistant's final message gets written to `~/.moxxy/inbox/`, and the prompt itself can call delivery tools (e.g. `telegram_send_message`) for push notifications.
+
+## Pattern
+
+1. **Capture intent** — what should fire, when, and where the output should land.
+   - "Every day at 9 AM" → cron `0 9 * * *`
+   - "Every Monday at 6 PM" → cron `0 18 * * 1`
+   - "Every 15 minutes" → cron `*/15 * * * *`
+   - "In one hour" → `runAt: <epoch-ms now + 3_600_000>` (or ISO timestamp)
+   - "Tomorrow at 10" → `runAt: <ISO timestamp>` in the user's local zone
+
+2. **Pick the schedule name** — slug-like (`morning-briefing`, `weekly-standup`). The user-facing name; appears in the inbox filename.
+
+3. **Write the prompt deliberately** — this prompt runs *headless* against the current provider/model. Include the delivery action in the prompt body if you want a push notification. Examples:
+   - "Fetch today's top 5 Hacker News posts; for each, write a 2-line summary; then call `telegram_send_message` with a markdown-formatted digest."
+   - "Check Gmail for new messages from <X>; if any, summarize and call `telegram_send_message`."
+   - "Remind me about <X>. Call `telegram_send_message` with a short reminder."
+
+4. **Call `schedule_create`** with `{ name, prompt, cron | runAt, channel?, model? }`. The tool returns `nextFireIso` so you can confirm the schedule will fire when expected.
+
+5. **Confirm to the user** — name, next fire time, where output goes. Offer to fire it once with `schedule_run_now` for a smoke test.
+
+## Cron cheat-sheet (5-field POSIX)
+
+```
+minute   hour   dom   month   dow
+0-59     0-23   1-31  1-12    0-6 (Sun=0)
+```
+
+Operators: `*` any, `a-b` range, `a,b,c` list, `*/n` step, `a-b/n` ranged step.
+
+Common shapes:
+- `0 9 * * *`     — 9 AM every day
+- `0 9 * * 1-5`   — weekdays at 9 AM
+- `0 */2 * * *`   — every 2 hours on the hour
+- `0 0 1 * *`     — midnight on the 1st of each month
+- `30 18 * * 5`   — Fridays at 6:30 PM
+
+When both day-of-month and day-of-week are restricted, the schedule fires when **either** matches (vixie-cron convention).
+
+## Managing existing schedules
+
+- `schedule_list` — view all, with `nextFireIso` + `lastResult`. Filter by `source: 'manual'|'skill'|'all'`.
+- `schedule_disable` / `schedule_enable` — pause/resume without losing the row.
+- `schedule_delete` — permanently remove.
+- `schedule_run_now` — fire immediately, useful for testing.
+
+## Auto-scheduled skills
+
+A skill file can include a `schedule:` block in its frontmatter — the scheduler picks it up automatically:
+
+```yaml
+---
+name: morning-briefing
+description: Daily 9 AM Hacker News digest
+schedule:
+  cron: "0 9 * * *"
+  channel: telegram
+---
+Fetch the top 5 stories from https://news.ycombinator.com/.
+For each, write 2 lines. Then call telegram_send_message with the digest.
+```
+
+Skill-driven schedules show up in `schedule_list` with `source: 'skill'`. Editing the skill body or its `schedule:` block on disk updates the live schedule on the next tick — no restart needed.
+
+## Limitations to mention if relevant
+
+- Schedules only fire while a moxxy session is alive (TUI, Telegram channel, etc.). For true 24/7 firing, the user must keep a session running (e.g. `moxxy telegram` in a background process).
+- The scheduled prompt runs against the **active session**, so its output appears in conversation history. Schedule with care while debugging an unrelated turn.
+- Timezones default to the host's system local. For UTC or another zone, pass `timeZone: "UTC"` or any IANA name.

package/dist/skills/self-heal.md

@@ -0,0 +1,113 @@
+---
+name: self-heal
+description: When a tool call fails or the system misbehaves, diagnose the root cause and propose ONE scoped fix that the user approves before it lands.
+triggers:
+  - "tool failed"
+  - "permission denied"
+  - "not found"
+  - "doesn't work"
+  - "broken"
+  - "fix this"
+  - "fix it"
+  - "can't run"
+  - "is hanging"
+  - "is stuck"
+  - "is failing"
+  - "what's wrong"
+  - "diagnose"
+  - "self-heal"
+  - "self heal"
+  - "repair"
+---
+
+# Self-heal — diagnose then propose ONE fix
+
+When a tool errored, a subagent hung, an install is missing, a permission was
+denied, or "something just isn't working", follow this loop. Every concrete
+change runs through an existing tool whose permission gate is `prompt`, so the
+user explicitly approves each destructive action — there is no "allow always"
+shortcut for fixes. **This is intentional.** Self-healing without a human in
+the loop turns a one-line bug into a cascade.
+
+## Loop
+
+1. **Diagnose first, don't guess.** Use read-only tools to inspect actual
+   state before forming a hypothesis:
+   - `Read` / `Grep` / `Glob` for source / config / logs.
+   - `bash` (read-only commands like `ls`, `cat`, `which`, `ps`, `git status`)
+     for environment checks. Don't run mutating shell commands here.
+   - `/info`, `/agents`, `/skills`, `/tools` — operator overlays that show
+     live registry state.
+   - `~/.moxxy/permissions.json`, `~/.moxxy/mcp.json`, `~/.moxxy/sessions/`
+     for persistent state when relevant.
+
+2. **State the root cause in one sentence.** "X failed because Y". If you
+   don't have evidence for Y, gather more — don't move on.
+
+3. **Propose ONE scoped fix.** Smallest change that addresses the diagnosed
+   cause. Avoid "let me also tidy up while I'm here" — that turns a focused
+   fix into an unreviewable diff.
+
+4. **Pick the right tool for the fix.** All of these prompt for permission:
+   - **Code / config edit**: `Edit` or `Write` for a specific file.
+   - **Shell action**: `bash` (e.g. restart a service, clear a cache).
+   - **Plugin missing**: `install_plugin` (if `@moxxy/plugin-plugins-admin`
+     is enabled) — npm-installs into `~/.moxxy/plugins` + hot-reloads.
+   - **MCP server broken/missing**: `mcp_add_server`, `mcp_remove_server`,
+     `mcp_test_server`.
+   - **Permission denied repeatedly**: tell the user how to add a permanent
+     allow rule (`moxxy perms allow <tool>`) — do NOT silently bypass.
+   - **Skill missing**: `synthesize_skill` to draft a new skill.
+
+5. **Surface the proposed change BEFORE calling the tool.** Tell the user:
+   - The diagnosis.
+   - The exact change you're about to make.
+   - What the user should look for in the next permission prompt to verify it.
+
+6. **Verify after the fix lands.** Re-run the failing tool / command. If it
+   still fails, do NOT loop on the same fix — go back to step 1 with the new
+   information. Two failed attempts is the threshold to stop and escalate
+   to the user with what you've learned.
+
+## Don't
+
+- **Don't propose `allow_always` as a fix.** If the user keeps seeing prompts
+  for the same tool, the fix is `moxxy perms allow <tool>`, not a
+  workaround. Suggest the command — don't run it for them.
+- **Don't try to fix issues outside the obvious blast radius.** If a single
+  subagent failed, don't reboot the whole session. If a config field was
+  missing, don't rewrite the entire config.
+- **Don't chain fixes without approval gates.** Each destructive step is its
+  own permission prompt. Bundling N edits into a single `bash` heredoc to
+  avoid the prompts defeats the safety design.
+- **Don't self-heal silently when the user didn't ask.** This skill is for
+  responding to a specific reported issue, not proactive cleanup. If you
+  notice a problem the user hasn't mentioned, tell them — let them decide
+  whether to repair.
+
+## Templates
+
+For a denied tool the user clearly wants:
+```
+Diagnosed: `web_fetch` was denied because the policy has no allow rule.
+Proposal:  Add a permanent allow for `web_fetch` (you'll only be asked once).
+Command:   `moxxy perms allow web_fetch`
+```
+
+For a missing plugin:
+```
+Diagnosed: `dispatch_agent` failed because `@moxxy/plugin-subagents` is not
+           registered (the agent registry only lists `default`).
+Proposal:  Install `@moxxy/plugin-subagents` via the install_plugin tool.
+           You'll get one permission prompt for the npm install.
+```
+
+For a hung subagent:
+```
+Diagnosed: Subagent `<label>` is hung waiting on a `<tool>` call — the
+           tool ran for <N>s with no result. Likely a network timeout on
+           <url>.
+Proposal:  Cancel the turn (Esc) and re-run with a more specific prompt
+           that points the child at a faster source. No file/config
+           changes needed.
+```