@pencil-agent/nano-pencil 2.0.1 → 2.0.3

package/dist/extensions/builtin/link-world/network-routing/network-routing.md

@@ -1,67 +1,67 @@
----
-name: network-routing
-description: Decide whether a task should use NanoPencil's web_search, link_world tools, or browser automation.
----
-
-# Network Routing
-
-NanoPencil has two different network paths:
-
-- `web_search` and `web_fetch` when those high-level tools are actually available in the current session
-- `link_world_*` as the durable lower-level integration path
-- `browser` and `browser_admin` for direct browser control and page interaction
-
-Choose the path by task shape, not by habit.
-
-## Use `web_search` First
-
-Use `web_search` when it is available and the user needs:
-
-- current facts
-- recent news
-- API/library documentation lookup
-- general web research
-- "what is", "find", "latest", "look up", "compare", or "summarize" style requests
-
-If setup is uncertain, call `link_world_admin` with `status` or `doctor` first.
-
-## Use `web_fetch` When The URL Is Known
-
-Use `web_fetch` when it is available and:
-
-- the user already gave a URL
-- a prior search step found the exact page you need
-- you need page content, not browser interaction
-- the task is fetch-and-read rather than click-and-drive
-
-## Use `browser` First
-
-Use `browser` when the user needs:
-
-- login-gated pages
-- clicking, typing, uploads, downloads, tabs, screenshots
-- form submission
-- navigating a live web app
-- inspecting visible UI state
-- browser-based verification
-
-If setup is uncertain, call `browser_admin` with `status` or `setup` first.
-
-## Fallback Order
-
-1. If `web_search` is available, use it for current knowledge discovery.
-2. If `web_fetch` is available and the target URL is already known, use it.
-3. If the answer requires interacting with a page, switch to `browser`.
-4. If high-level link-world tools are unavailable but internet runtime is present, use `link_world_exec`.
-5. Only fall back to `bash` for external CLIs when the dedicated tools are unavailable.
-
-## Working Rule
-
-Prefer NanoPencil's named tools over raw shell commands. The integration boundary should stay inside:
-
-- `link_world_admin`
-- `web_search`
-- `web_fetch`
-- `link_world_exec`
-- `browser_admin`
-- `browser`
+---
+name: network-routing
+description: Decide whether a task should use NanoPencil's web_search, link_world tools, or browser automation.
+---
+
+# Network Routing
+
+NanoPencil has two different network paths:
+
+- `web_search` and `web_fetch` when those high-level tools are actually available in the current session
+- `link_world_*` as the durable lower-level integration path
+- `browser` and `browser_admin` for direct browser control and page interaction
+
+Choose the path by task shape, not by habit.
+
+## Use `web_search` First
+
+Use `web_search` when it is available and the user needs:
+
+- current facts
+- recent news
+- API/library documentation lookup
+- general web research
+- "what is", "find", "latest", "look up", "compare", or "summarize" style requests
+
+If setup is uncertain, call `link_world_admin` with `status` or `doctor` first.
+
+## Use `web_fetch` When The URL Is Known
+
+Use `web_fetch` when it is available and:
+
+- the user already gave a URL
+- a prior search step found the exact page you need
+- you need page content, not browser interaction
+- the task is fetch-and-read rather than click-and-drive
+
+## Use `browser` First
+
+Use `browser` when the user needs:
+
+- login-gated pages
+- clicking, typing, uploads, downloads, tabs, screenshots
+- form submission
+- navigating a live web app
+- inspecting visible UI state
+- browser-based verification
+
+If setup is uncertain, call `browser_admin` with `status` or `setup` first.
+
+## Fallback Order
+
+1. If `web_search` is available, use it for current knowledge discovery.
+2. If `web_fetch` is available and the target URL is already known, use it.
+3. If the answer requires interacting with a page, switch to `browser`.
+4. If high-level link-world tools are unavailable but internet runtime is present, use `link_world_exec`.
+5. Only fall back to `bash` for external CLIs when the dedicated tools are unavailable.
+
+## Working Rule
+
+Prefer NanoPencil's named tools over raw shell commands. The integration boundary should stay inside:
+
+- `link_world_admin`
+- `web_search`
+- `web_fetch`
+- `link_world_exec`
+- `browser_admin`
+- `browser`

package/dist/extensions/builtin/loop/README.md

@@ -1,92 +1,92 @@
-# Loop Extension
-
-`/loop` schedules a recurring prompt or slash command for the current session.
-Uses the unified **cron scheduler** architecture per the refactoring plan.
-
-For the autonomous "keep digging until done" runner, see the sibling
-[`grub` extension](../grub/README.md).
-
-## Architecture
-
-```
-/loop command ──→ addCronTask ──→ unified store ──→ cron scheduler ──→ onFire ──→ dispatch
-                     │                                  │
-              CronCreate tool                    file watcher (3s reload)
-              CronDelete tool                    jitter + lock
-              CronList tool                      7-day expiry
-```
-
-**Key design decisions**:
-- Single scheduler (cron scheduler) for all tasks
-- Single storage (`.nanopencil/cron-tasks.json` for durable, memory for session)
-- `/loop` command and CronCreate tool both use `addCronTask`
-- Enhanced features (--name, --max, --quiet, pause/resume) built on top
-
-## Quick start
-
-```
-/loop check the build                       # every 10m (default)
-/loop 5m /grub status                       # slash command every 5 minutes
-/loop every 10m Review test failures
-/loop Drink water every 30m --name hydrate --max 8 --quiet
-/loop Check build every 5m --durable        # persists across sessions
-```
-
-## Manage
-
-```
-/loop list                  # all scheduled loops
-/loop status <ref>          # detail one loop (ref = name or id)
-/loop pause <ref>
-/loop resume <ref>
-/loop run <ref>             # fire immediately
-/loop cancel <ref>          # remove one
-/loop clear                 # remove all
-```
-
-`<ref>` can be either the auto-generated id or the `--name` slug.
-
-## Flags
-
-- `--name <slug>` — give the loop a friendly handle so you can `pause hydrate`
-  instead of memorising hex ids.
-- `--max <n>` — auto-cancel after `n` runs.
-- `--quiet` (or `-q`) — suppress per-tick UI messages. Errors and terminal
-  events still surface; routine ticks are still recorded via `appendEntry`.
-- `--durable` (or `-d`) — persist the loop across sessions. Durable loops are
-  saved to `.nanopencil/cron-tasks.json` and will resume when you reopen the
-  project.
-
-## Notes
-
-- By default, loops are **session-scoped**: closing the session clears them.
-- Use `--durable` to persist loops across sessions.
-- Durable loops are stored in `.nanopencil/cron-tasks.json` in your project
-  directory.
-- **Auto-expiry**: Durable loops automatically expire after 7 days to prevent
-  zombie tasks from accumulating.
-- Due tasks wait for the agent to be idle; missed intervals collapse to one
-  pending run.
-- Slash-command payloads are detected at parse time and dispatched through
-  `executeCommand`; everything else is delivered through `sendUserMessage` as
-  a follow-up turn.
-- After each loop tick the last assistant message is captured (truncated to
-  120 chars) and shown in `/loop status <ref>` as `Last output`.
-- Supports `s/m/h/d` durations and `hourly`/`daily` shortcuts.
-- **Jitter**: Tasks have deterministic jitter (based on task ID) to avoid
-  traffic spikes at round times.
-- **Scheduler lock**: Multiple sessions in the same project use proper-lockfile
-  to prevent duplicate task execution.
-
-## Cron Tools
-
-The extension also registers three tools for the model to use directly:
-
-| Tool | Purpose |
-|------|---------|
-| `CronCreate` | Create a scheduled task with cron expression |
-| `CronDelete` | Delete a scheduled task by ID |
-| `CronList` | List all active scheduled tasks |
-
-This allows the model to create and manage scheduled tasks through natural
-language understanding, following the refactoring plan's architecture.
+# Loop Extension
+
+`/loop` schedules a recurring prompt or slash command for the current session.
+Uses the unified **cron scheduler** architecture per the refactoring plan.
+
+For the autonomous "keep digging until done" runner, see the sibling
+[`grub` extension](../grub/README.md).
+
+## Architecture
+
+```
+/loop command ──→ addCronTask ──→ unified store ──→ cron scheduler ──→ onFire ──→ dispatch
+                     │                                  │
+              CronCreate tool                    file watcher (3s reload)
+              CronDelete tool                    jitter + lock
+              CronList tool                      7-day expiry
+```
+
+**Key design decisions**:
+- Single scheduler (cron scheduler) for all tasks
+- Single storage (`.nanopencil/cron-tasks.json` for durable, memory for session)
+- `/loop` command and CronCreate tool both use `addCronTask`
+- Enhanced features (--name, --max, --quiet, pause/resume) built on top
+
+## Quick start
+
+```
+/loop check the build                       # every 10m (default)
+/loop 5m /grub status                       # slash command every 5 minutes
+/loop every 10m Review test failures
+/loop Drink water every 30m --name hydrate --max 8 --quiet
+/loop Check build every 5m --durable        # persists across sessions
+```
+
+## Manage
+
+```
+/loop list                  # all scheduled loops
+/loop status <ref>          # detail one loop (ref = name or id)
+/loop pause <ref>
+/loop resume <ref>
+/loop run <ref>             # fire immediately
+/loop cancel <ref>          # remove one
+/loop clear                 # remove all
+```
+
+`<ref>` can be either the auto-generated id or the `--name` slug.
+
+## Flags
+
+- `--name <slug>` — give the loop a friendly handle so you can `pause hydrate`
+  instead of memorising hex ids.
+- `--max <n>` — auto-cancel after `n` runs.
+- `--quiet` (or `-q`) — suppress per-tick UI messages. Errors and terminal
+  events still surface; routine ticks are still recorded via `appendEntry`.
+- `--durable` (or `-d`) — persist the loop across sessions. Durable loops are
+  saved to `.nanopencil/cron-tasks.json` and will resume when you reopen the
+  project.
+
+## Notes
+
+- By default, loops are **session-scoped**: closing the session clears them.
+- Use `--durable` to persist loops across sessions.
+- Durable loops are stored in `.nanopencil/cron-tasks.json` in your project
+  directory.
+- **Auto-expiry**: Durable loops automatically expire after 7 days to prevent
+  zombie tasks from accumulating.
+- Due tasks wait for the agent to be idle; missed intervals collapse to one
+  pending run.
+- Slash-command payloads are detected at parse time and dispatched through
+  `executeCommand`; everything else is delivered through `sendUserMessage` as
+  a follow-up turn.
+- After each loop tick the last assistant message is captured (truncated to
+  120 chars) and shown in `/loop status <ref>` as `Last output`.
+- Supports `s/m/h/d` durations and `hourly`/`daily` shortcuts.
+- **Jitter**: Tasks have deterministic jitter (based on task ID) to avoid
+  traffic spikes at round times.
+- **Scheduler lock**: Multiple sessions in the same project use proper-lockfile
+  to prevent duplicate task execution.
+
+## Cron Tools
+
+The extension also registers three tools for the model to use directly:
+
+| Tool | Purpose |
+|------|---------|
+| `CronCreate` | Create a scheduled task with cron expression |
+| `CronDelete` | Delete a scheduled task by ID |
+| `CronList` | List all active scheduled tasks |
+
+This allows the model to create and manage scheduled tasks through natural
+language understanding, following the refactoring plan's architecture.

package/dist/extensions/builtin/mcp/figma-design.md

@@ -1,68 +1,68 @@
----
-name: figma-design
-description: Use this skill when the user wants NanoPencil to inspect, create, or edit designs in Figma through MCP.
----
-
-# Figma Design
-
-Use this skill when the user asks NanoPencil to:
-
-- Generate a design in Figma
-- Edit an existing Figma file
-- Turn requirements into Figma frames, components, or styles
-- Read design context from Figma before implementing UI
-
-## Preferred integration path
-
-Prefer the official Figma Remote MCP server first. Use the desktop server as a fallback or as an additional local-context path.
-
-NanoPencil includes two built-in disabled MCP presets:
-
-- Server ID: `figma-remote`
-- URL: `https://mcp.figma.com/mcp`
-- Auth: `/figma auth` tries a standalone browser OAuth flow first. If Figma blocks first-time client registration on this machine, NanoPencil can fall back to importing an existing official local session.
-
-- Server ID: `figma-desktop`
-- URL: `http://127.0.0.1:3845/mcp`
-
-## First-time setup flow
-
-If the Figma MCP tools are not available yet:
-
-1. Prefer the remote setup first:
-
-```text
-/figma auth
-/figma remote
-```
-
-If the user already has dedicated Figma OAuth credentials for NanoPencil, they can also set:
-
-```text
-NANOPENCIL_FIGMA_CLIENT_ID
-NANOPENCIL_FIGMA_CLIENT_SECRET
-```
-
-2. If the user wants the local desktop route instead, ask them to open the Figma desktop app and enable the desktop MCP server in Figma Dev Mode.
-3. Then tell them to run:
-
-```text
-/figma setup
-```
-
-4. After reload, check whether MCP tools from a Figma server are available.
-
-## How to work once Figma tools are available
-
-- First inspect the available Figma MCP tools in the current session.
-- Prefer reading the current file or selection context before writing.
-- Then create or update frames, components, text, styles, or variables as needed.
-- When the user wants generated UI, write the result into Figma instead of only describing it in chat.
-
-## Important guidance
-
-- Prefer the remote path when possible because it is closer to the Codex/Claude-style setup.
-- If the remote path is not authenticated yet, guide the user through `/figma auth` before falling back to desktop.
-- The official write-capable path is MCP, not the read-heavy REST API.
-- If tools are missing after enabling either server, remind the user to run `/reload`.
-- If the remote path fails but the user already has a valid local desktop MCP server, use the desktop route so the design task can still move forward.
+---
+name: figma-design
+description: Use this skill when the user wants NanoPencil to inspect, create, or edit designs in Figma through MCP.
+---
+
+# Figma Design
+
+Use this skill when the user asks NanoPencil to:
+
+- Generate a design in Figma
+- Edit an existing Figma file
+- Turn requirements into Figma frames, components, or styles
+- Read design context from Figma before implementing UI
+
+## Preferred integration path
+
+Prefer the official Figma Remote MCP server first. Use the desktop server as a fallback or as an additional local-context path.
+
+NanoPencil includes two built-in disabled MCP presets:
+
+- Server ID: `figma-remote`
+- URL: `https://mcp.figma.com/mcp`
+- Auth: `/figma auth` tries a standalone browser OAuth flow first. If Figma blocks first-time client registration on this machine, NanoPencil can fall back to importing an existing official local session.
+
+- Server ID: `figma-desktop`
+- URL: `http://127.0.0.1:3845/mcp`
+
+## First-time setup flow
+
+If the Figma MCP tools are not available yet:
+
+1. Prefer the remote setup first:
+
+```text
+/figma auth
+/figma remote
+```
+
+If the user already has dedicated Figma OAuth credentials for NanoPencil, they can also set:
+
+```text
+NANOPENCIL_FIGMA_CLIENT_ID
+NANOPENCIL_FIGMA_CLIENT_SECRET
+```
+
+2. If the user wants the local desktop route instead, ask them to open the Figma desktop app and enable the desktop MCP server in Figma Dev Mode.
+3. Then tell them to run:
+
+```text
+/figma setup
+```
+
+4. After reload, check whether MCP tools from a Figma server are available.
+
+## How to work once Figma tools are available
+
+- First inspect the available Figma MCP tools in the current session.
+- Prefer reading the current file or selection context before writing.
+- Then create or update frames, components, text, styles, or variables as needed.
+- When the user wants generated UI, write the result into Figma instead of only describing it in chat.
+
+## Important guidance
+
+- Prefer the remote path when possible because it is closer to the Codex/Claude-style setup.
+- If the remote path is not authenticated yet, guide the user through `/figma auth` before falling back to desktop.
+- The official write-capable path is MCP, not the read-heavy REST API.
+- If tools are missing after enabling either server, remind the user to run `/reload`.
+- If the remote path fails but the user already has a valid local desktop MCP server, use the desktop route so the design task can still move forward.

package/dist/extensions/builtin/mcp/mcp-management.md

@@ -1,85 +1,85 @@
----
-name: mcp-management
-description: Use this skill when the user asks to install, configure, debug, enable, or disable MCP servers or MCP tools in NanoPencil.
----
-
-# MCP Management
-
-Use this skill when the user asks for any of the following:
-
-- Install a new MCP server
-- Configure an existing MCP server
-- Enable or disable MCP servers in NanoPencil
-- Debug why MCP tools are missing
-- Add API keys or environment variables for an MCP server
-
-## What NanoPencil already does
-
-- MCP is enabled by default in NanoPencil unless the user launched it with `--no-mcp` or in offline mode.
-- NanoPencil reads MCP server definitions from `~/.nanopencil/agent/mcp.json`.
-- MCP tools are loaded into the current session at startup and on `/reload`.
-
-Important:
-
-- Editing `mcp.json` alone does not make new MCP tools appear immediately in the current session.
-- After changing MCP config, tell the user to run `/reload`, or explain that a restart/reload is needed before the new tools can be used.
-
-## How to inspect the current MCP setup
-
-1. Read `~/.nanopencil/agent/mcp.json` if it exists.
-2. Check whether the target server already exists in `mcpServers`.
-3. Check whether it is enabled.
-4. Check whether required environment variables are present.
-
-If the file does not exist, NanoPencil will create a default one when MCP config is first loaded.
-
-## How to add a new MCP server
-
-1. Find the official install/start command from the server's documentation.
-2. Prefer stable commands such as:
-   - `npx -y <package>`
-   - `uvx <package>`
-   - `python -m <module>`
-   - `node /absolute/path/to/server.js`
-3. Add a server entry to `~/.nanopencil/agent/mcp.json`.
-4. Set `enabled: true` only if the command and required credentials are ready.
-5. Tell the user that `/reload` is required to apply the change.
-
-## Config shape reminder
-
-Use this structure:
-
-```json
-{
-  "mcpServers": [
-    {
-      "id": "example",
-      "name": "Example",
-      "command": "npx",
-      "args": ["-y", "@example/server"],
-      "enabled": true,
-      "transport": "stdio",
-      "toolTimeout": 30000
-    }
-  ]
-}
-```
-
-For remote HTTP/SSE MCP servers, use the server's documented transport and URL fields supported by NanoPencil's MCP config.
-
-## Safe operating rules
-
-- Do not invent MCP package names. Check the server's official docs first.
-- Do not claim the new MCP tools are ready until the config is written and the user has reloaded.
-- If credentials are required, ask the user for the missing values instead of guessing.
-- If an install command modifies global system state, tell the user what will be installed.
-
-## Good response pattern
-
-When the user asks you to install an MCP server:
-
-1. Inspect `mcp.json`
-2. Install or configure the server
-3. Update `mcp.json`
-4. Tell the user exactly what changed
-5. Ask them to run `/reload` if the current session needs to pick up the new tools
+---
+name: mcp-management
+description: Use this skill when the user asks to install, configure, debug, enable, or disable MCP servers or MCP tools in NanoPencil.
+---
+
+# MCP Management
+
+Use this skill when the user asks for any of the following:
+
+- Install a new MCP server
+- Configure an existing MCP server
+- Enable or disable MCP servers in NanoPencil
+- Debug why MCP tools are missing
+- Add API keys or environment variables for an MCP server
+
+## What NanoPencil already does
+
+- MCP is enabled by default in NanoPencil unless the user launched it with `--no-mcp` or in offline mode.
+- NanoPencil reads MCP server definitions from `~/.nanopencil/agent/mcp.json`.
+- MCP tools are loaded into the current session at startup and on `/reload`.
+
+Important:
+
+- Editing `mcp.json` alone does not make new MCP tools appear immediately in the current session.
+- After changing MCP config, tell the user to run `/reload`, or explain that a restart/reload is needed before the new tools can be used.
+
+## How to inspect the current MCP setup
+
+1. Read `~/.nanopencil/agent/mcp.json` if it exists.
+2. Check whether the target server already exists in `mcpServers`.
+3. Check whether it is enabled.
+4. Check whether required environment variables are present.
+
+If the file does not exist, NanoPencil will create a default one when MCP config is first loaded.
+
+## How to add a new MCP server
+
+1. Find the official install/start command from the server's documentation.
+2. Prefer stable commands such as:
+   - `npx -y <package>`
+   - `uvx <package>`
+   - `python -m <module>`
+   - `node /absolute/path/to/server.js`
+3. Add a server entry to `~/.nanopencil/agent/mcp.json`.
+4. Set `enabled: true` only if the command and required credentials are ready.
+5. Tell the user that `/reload` is required to apply the change.
+
+## Config shape reminder
+
+Use this structure:
+
+```json
+{
+  "mcpServers": [
+    {
+      "id": "example",
+      "name": "Example",
+      "command": "npx",
+      "args": ["-y", "@example/server"],
+      "enabled": true,
+      "transport": "stdio",
+      "toolTimeout": 30000
+    }
+  ]
+}
+```
+
+For remote HTTP/SSE MCP servers, use the server's documented transport and URL fields supported by NanoPencil's MCP config.
+
+## Safe operating rules
+
+- Do not invent MCP package names. Check the server's official docs first.
+- Do not claim the new MCP tools are ready until the config is written and the user has reloaded.
+- If credentials are required, ask the user for the missing values instead of guessing.
+- If an install command modifies global system state, tell the user what will be installed.
+
+## Good response pattern
+
+When the user asks you to install an MCP server:
+
+1. Inspect `mcp.json`
+2. Install or configure the server
+3. Update `mcp.json`
+4. Tell the user exactly what changed
+5. Ask them to run `/reload` if the current session needs to pick up the new tools

package/dist/extensions/builtin/recap/AGENT.md

@@ -1,15 +1,15 @@
-# extensions/builtin/recap/
-
-> P2 | Parent: ../AGENT.md
-
-Member List
-index.ts: recapExtension entry — registers /recap command (Free deterministic by default; --smart opts into LLM-polished synthesis) and ※ recap message renderer; on-demand only, no auto trigger
-recap-types.ts: RECAP_MESSAGE_TYPE constant, RecapEntry / RecapSource / RecapTriggerReason / RecapSettings types, RECAP_DEFAULTS conservative settings
-recap-budget.ts: estimateInputTokens() char-count pre-flight estimate, checkPerCallBudget() pre-call hard-cap enforcement
-recap-extractor.ts: extractFreeRecap() + formatFreeRecap() + walkSessionActivity() — zero-LLM deterministic Free path; goal=longest substantive user message, facts=tool/file frequency top-3, next=question-mark detection
-recap-synthesizer.ts: buildRecapContext() returns prompt + activity counts (userTurns/assistantTurns/toolCalls) via shared walkSessionActivity walker, hasMeaningfulActivity() pre-check used by handler before "Synthesizing…" notify, synthesizeSmartRecap() runs completeSimpleWithUsage with three-clause system prompt, surfaces real provider usage, returns empty_session as a defensive fallback
-recap-renderer.ts: createRecapRenderer() — italic dim ※ recap with `{in} in / {out} out · ~${cost}` badge, no background block (low-weight in-conversation hint), Text-only (no Markdown coupling)
-
-Rule: Members complete, one item per line, parent links valid, precise terms first
-
-[COVENANT]: Update this file header on changes and verify against parent AGENT.md
+# extensions/builtin/recap/
+
+> P2 | Parent: ../AGENT.md
+
+Member List
+index.ts: recapExtension entry — registers /recap command (Free deterministic by default; --smart opts into LLM-polished synthesis) and ※ recap message renderer; on-demand only, no auto trigger
+recap-types.ts: RECAP_MESSAGE_TYPE constant, RecapEntry / RecapSource / RecapTriggerReason / RecapSettings types, RECAP_DEFAULTS conservative settings
+recap-budget.ts: estimateInputTokens() char-count pre-flight estimate, checkPerCallBudget() pre-call hard-cap enforcement
+recap-extractor.ts: extractFreeRecap() + formatFreeRecap() + walkSessionActivity() — zero-LLM deterministic Free path; goal=longest substantive user message, facts=tool/file frequency top-3, next=question-mark detection
+recap-synthesizer.ts: buildRecapContext() returns prompt + activity counts (userTurns/assistantTurns/toolCalls) via shared walkSessionActivity walker, hasMeaningfulActivity() pre-check used by handler before "Synthesizing…" notify, synthesizeSmartRecap() runs completeSimpleWithUsage with three-clause system prompt, surfaces real provider usage, returns empty_session as a defensive fallback
+recap-renderer.ts: createRecapRenderer() — italic dim ※ recap with `{in} in / {out} out · ~${cost}` badge, no background block (low-weight in-conversation hint), Text-only (no Markdown coupling)
+
+Rule: Members complete, one item per line, parent links valid, precise terms first
+
+[COVENANT]: Update this file header on changes and verify against parent AGENT.md