@pingvinen/donna-assistant 0.9.0 → 0.10.0

package/workflows/done.md

@@ -4,71 +4,33 @@
 Mark one or more tasks as complete in today's daily journal file and commit the change to git.
 </objective>
 
-<step name="read-config">
-Read `~/.config/donna/config.md`.
-
-If the file does not exist, print:
-```
-✗ Donna is not configured. Run /donna:setup first.
-```
-Stop.
-
-Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (default: false) fields from the YAML frontmatter.
-
-**Obsidian sync:** Check if `<storage_repo>/.obsidian/daily-notes.json` exists.
-- If it exists and has a `folder` field that differs from `<daily_folder>`: update `<daily_folder>` to match Obsidian's value, and update `~/.config/donna/config.md` with the new `daily_folder`. Print `✓ Synced daily folder with Obsidian: <daily_folder>`.
-- If `<storage_repo>/.obsidian/` exists but `daily-notes.json` does not exist or has no `folder` field: write `<storage_repo>/.obsidian/daily-notes.json` with `{"folder":"<daily_folder>"}`. Print `✓ Configured Obsidian daily notes to use <daily_folder>/`.
-- Otherwise: do nothing.
-</step>
-
-<step name="check-pending-migrations">
-Read `~/.donna/state.md` with the Read tool. If the file does not exist or has no `pending_migrations` field in its YAML frontmatter, skip this step.
-
-For each entry in `pending_migrations`:
-
-**`move-standing-files`:** Move standing files from storage repo root to donna/ subfolder.
-
+<step name="init">
 Run via Bash:
 ```bash
-STORAGE_REPO="<storage_repo>"
-DONNA_DIR="$STORAGE_REPO/donna"
-MOVED=0
-
-mkdir -p "$DONNA_DIR"
-for FILE in role.md recurring.md role-research.md; do
-    if [ -f "$STORAGE_REPO/$FILE" ] && [ ! -f "$DONNA_DIR/$FILE" ]; then
-        mv "$STORAGE_REPO/$FILE" "$DONNA_DIR/$FILE"
-        echo "Moved $FILE to donna/$FILE"
-        MOVED=$((MOVED + 1))
-    fi
-done
-
-echo "MOVED=$MOVED"
+INIT=$(node ~/.donna/donna-tools.cjs init)
 ```
 
-If MOVED > 0, commit the move:
-```bash
-git -C <storage_repo> add -A
-git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "donna(migrate): move standing files to donna/ subfolder"
+Parse the JSON response. If the `error` field is `"not_configured"`, print:
+```
+x Donna is not configured. Run /donna:setup first.
 ```
+Stop.
 
-If `auto_push` is true in config, also push.
+Extract `storage_repo`, `daily_folder`, `auto_push` from the JSON.
 
-After processing all pending migrations, update `~/.donna/state.md` with the Write tool: remove the completed entries from `pending_migrations`. If no entries remain, write:
-```markdown
----
-pending_migrations: []
----
+If `update_available` is non-null, print:
+```
+Donna v<update_available> available -- run npx @pingvinen/donna-assistant to update
 ```
+Continue normally.
 </step>
 
 <step name="find-daily-file">
-Run via Bash to get today's date:
+Get the daily file path via donna-tools:
 ```bash
-date +%Y-%m-%d
+DAILY_PATH=$(node ~/.donna/donna-tools.cjs daily-path | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.parse(d).path))")
 ```
-
-Store the result as `<date>`. Construct the daily file path: `<storage_repo>/<daily_folder>/<date>.md`.
+Store the result as `<daily_file_path>`. Extract `<date>` from the filename (last path component without `.md`).
 
 If the file does not exist, print:
 ```
@@ -135,30 +97,10 @@ Write the updated file with the Write tool.
 <step name="git-commit">
 Run via Bash:
 ```bash
-git -C <storage_repo> add -A
-```
-
-Check whether there is anything to commit:
-```bash
-git -C <storage_repo> status --porcelain
+node ~/.donna/donna-tools.cjs commit "donna(done): <task_summary>" --files <daily_folder>/<date>.md
 ```
 
-If the output is empty, skip the commit and continue.
-
-If one task was completed, run:
-```bash
-git -C <storage_repo> commit -m "donna(done): <description>"
-```
-
-If multiple tasks were completed, run:
-```bash
-git -C <storage_repo> commit -m "donna(done): <N> tasks completed"
-```
-
-If `auto_push` is true in config, also run:
-```bash
-git -C <storage_repo> push
-```
+Where `<task_summary>` is the completed task description (if one task) or `<N> tasks completed` (if multiple tasks).
 </step>
 
 <step name="confirm">

package/workflows/focus.md

@@ -4,92 +4,33 @@
 Read today's daily file, score open tasks on urgency and context signals, optionally re-query active tools for enriched data, and produce a short prioritized focus list written to daily/focus.md and printed to the terminal. This is a read-only operation relative to the daily file: only focus.md is written.
 </objective>
 
-<step name="read-config">
-Read `~/.config/donna/config.md`.
-
-If the file does not exist, print:
-```
-✗ Donna is not configured. Run /donna:setup first.
-```
-Stop.
-
-Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (default: false) fields from the YAML frontmatter.
-
-**Obsidian sync:** Check if `<storage_repo>/.obsidian/daily-notes.json` exists.
-- If it exists and has a `folder` field that differs from `<daily_folder>`: update `<daily_folder>` to match Obsidian's value, and update `~/.config/donna/config.md` with the new `daily_folder`. Print `✓ Synced daily folder with Obsidian: <daily_folder>`.
-- If `<storage_repo>/.obsidian/` exists but `daily-notes.json` does not exist or has no `folder` field: write `<storage_repo>/.obsidian/daily-notes.json` with `{"folder":"<daily_folder>"}`. Print `✓ Configured Obsidian daily notes to use <daily_folder>/`.
-- Otherwise: do nothing.
-</step>
-
-<step name="check-pending-migrations">
-Read `~/.donna/state.md` with the Read tool. If the file does not exist or has no `pending_migrations` field in its YAML frontmatter, skip this step.
-
-For each entry in `pending_migrations`:
-
-**`move-standing-files`:** Move standing files from storage repo root to donna/ subfolder.
-
+<step name="init">
 Run via Bash:
 ```bash
-STORAGE_REPO="<storage_repo>"
-DONNA_DIR="$STORAGE_REPO/donna"
-MOVED=0
-
-mkdir -p "$DONNA_DIR"
-for FILE in role.md recurring.md role-research.md; do
-    if [ -f "$STORAGE_REPO/$FILE" ] && [ ! -f "$DONNA_DIR/$FILE" ]; then
-        mv "$STORAGE_REPO/$FILE" "$DONNA_DIR/$FILE"
-        echo "Moved $FILE to donna/$FILE"
-        MOVED=$((MOVED + 1))
-    fi
-done
-
-echo "MOVED=$MOVED"
+INIT=$(node ~/.donna/donna-tools.cjs init)
 ```
 
-If MOVED > 0, commit the move:
-```bash
-git -C <storage_repo> add -A
-git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "donna(migrate): move standing files to donna/ subfolder"
+Parse the JSON response. If the `error` field is `"not_configured"`, print:
 ```
-
-If `auto_push` is true in config, also push.
-
-**`backfill-tool-type`:** Backfill `type` on existing tool sections in tools.md using heuristic detection.
-
-Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not exist or has no tool sections, skip this handler.
-
-For each tool section (starting with `## <tool_name>`), check if a `- type:` line already exists. If the `- type:` line is missing, detect the correct type:
-
-1. If the tool section contains a `- command:` line where the value starts with `mcp:` (e.g., `- command: mcp:linear`), insert `- type: mcp` immediately after the `- command:` line.
-2. Else, if the tool section contains a `- base_url:` line:
-   - If the capabilities section contains entries that look like GraphQL queries (contain `query {` or `mutation {`), insert `- type: graphql` immediately after `## <tool_name>` (REST/GraphQL tools have no `- command:` line).
-   - Otherwise, insert `- type: rest` immediately after `## <tool_name>`.
-3. Else (no `mcp:` prefix, no `base_url` field), insert `- type: cli` immediately after the `- command:` line.
-
-Write the updated file back with the Write tool. If any changes were made, commit:
-```bash
-git -C <storage_repo> add -A
-git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "donna(migrate): backfill tool types on existing tools"
+x Donna is not configured. Run /donna:setup first.
 ```
+Stop.
 
-If `auto_push` is true in config, also push.
+Extract `storage_repo`, `daily_folder`, `auto_push` from the JSON.
 
-After processing all pending migrations, update `~/.donna/state.md` with the Write tool: remove the completed entries from `pending_migrations`. If no entries remain, write:
-```markdown
----
-pending_migrations: []
----
+If `update_available` is non-null, print:
 ```
+Donna v<update_available> available -- run npx @pingvinen/donna-assistant to update
+```
+Continue normally.
 </step>
 
 <step name="read-daily-file">
-Get today's date via Bash:
+Get the daily file path via donna-tools:
 ```bash
-date +%Y-%m-%d
+DAILY_PATH=$(node ~/.donna/donna-tools.cjs daily-path | node -e "process.stdin.resume();let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.parse(d).path))")
 ```
-Store as `<today>`.
-
-Construct the daily file path: `<storage_repo>/<daily_folder>/<today>.md`.
+Store the result as `<daily_file_path>`. Extract `<today>` from the filename (last path component without `.md`).
 
 Read the daily file with the Read tool. If the file does not exist, print:
 ```
@@ -154,23 +95,25 @@ For each matched tool, extract:
 **Type-aware execution within each agent (or direct execution for single tool):**
 
 For `type: cli` capabilities (format: `<name>: <cli_invocation>`):
+
+Run via Bash (set the Bash tool's `timeout` parameter to `10000`):
 ```bash
-timeout 10 <cli_invocation> 2>&1
+<cli_invocation> 2>&1
 ```
 
 For `type: rest` capabilities (format: `<name>: <METHOD> /path`):
 1. Read `<storage_repo>/donna/secrets.md` with the Read tool. Parse key-value pairs from under the frontmatter.
 2. Resolve the `auth_secret` key to get the actual secret value. If the key is not found in secrets.md or the value is `REPLACE_WITH_YOUR_SECRET`, add warning `! <tool_name>: missing secret <auth_secret> — edit donna/secrets.md` and skip this tool.
-3. For each capability, run via Bash with a 10-second timeout:
+3. For each capability, run via Bash (set the Bash tool's `timeout` parameter to `10000`):
 ```bash
-timeout 10 curl -s -H "<auth_header>: <resolved_secret>" "<base_url><path>" 2>&1
+curl -s -H "<auth_header>: <resolved_secret>" "<base_url><path>" 2>&1
 ```
 
 For `type: graphql` capabilities (format: `<name>: <graphql_query>`):
 1. Same secrets resolution as REST.
-2. For each capability, run via Bash with a 10-second timeout:
+2. For each capability, run via Bash (set the Bash tool's `timeout` parameter to `10000`):
 ```bash
-timeout 10 curl -s -X POST -H "<auth_header>: <resolved_secret>" -H "Content-Type: application/json" -d '{"query":"<graphql_query>"}' "<base_url>" 2>&1
+curl -s -X POST -H "<auth_header>: <resolved_secret>" -H "Content-Type: application/json" -d '{"query":"<graphql_query>"}' "<base_url>" 2>&1
 ```
 
 For `type: mcp` capabilities (format: `<name>: mcp:<server>/<tool>`):
@@ -262,24 +205,7 @@ If there are tool warnings from `<tool_warnings>`, append them after the footer:
 <step name="git-commit">
 Run via Bash:
 ```bash
-git -C <storage_repo> add -A
-```
-
-Check whether there is anything to commit:
-```bash
-git -C <storage_repo> status --porcelain
-```
-
-If the output is empty, skip the commit and continue.
-
-Otherwise, run:
-```bash
-git -C <storage_repo> commit -m "donna(focus): focus list for <today>"
-```
-
-If `auto_push` is true in config, also run:
-```bash
-git -C <storage_repo> push
+node ~/.donna/donna-tools.cjs commit "donna(focus): updated focus list" --files <daily_folder>/<today>.md
 ```
 </step>
 

package/workflows/relearn-tools.md

@@ -4,82 +4,25 @@
 Check each registered tool's installed version against its stored version and re-learn capabilities for tools that have been updated. Tools at the same version are skipped.
 </objective>
 
-<step name="read-config">
-Read `~/.config/donna/config.md`.
-
-If the file does not exist, print:
-```
-✗ Donna is not configured. Run /donna:setup first.
-```
-Stop.
-
-Extract the `storage_repo`, `daily_folder` (default: `daily`), and `auto_push` (default: false) fields from the YAML frontmatter.
-
-**Obsidian sync:** Check if `<storage_repo>/.obsidian/daily-notes.json` exists.
-- If it exists and has a `folder` field that differs from `<daily_folder>`: update `<daily_folder>` to match Obsidian's value, and update `~/.config/donna/config.md` with the new `daily_folder`. Print `✓ Synced daily folder with Obsidian: <daily_folder>`.
-- If `<storage_repo>/.obsidian/` exists but `daily-notes.json` does not exist or has no `folder` field: write `<storage_repo>/.obsidian/daily-notes.json` with `{"folder":"<daily_folder>"}`. Print `✓ Configured Obsidian daily notes to use <daily_folder>/`.
-- Otherwise: do nothing.
-</step>
-
-<step name="check-pending-migrations">
-Read `~/.donna/state.md` with the Read tool. If the file does not exist or has no `pending_migrations` field in its YAML frontmatter, skip this step.
-
-For each entry in `pending_migrations`:
-
-**`move-standing-files`:** Move standing files from storage repo root to donna/ subfolder.
-
+<step name="init">
 Run via Bash:
 ```bash
-STORAGE_REPO="<storage_repo>"
-DONNA_DIR="$STORAGE_REPO/donna"
-MOVED=0
-
-mkdir -p "$DONNA_DIR"
-for FILE in role.md recurring.md role-research.md; do
-    if [ -f "$STORAGE_REPO/$FILE" ] && [ ! -f "$DONNA_DIR/$FILE" ]; then
-        mv "$STORAGE_REPO/$FILE" "$DONNA_DIR/$FILE"
-        echo "Moved $FILE to donna/$FILE"
-        MOVED=$((MOVED + 1))
-    fi
-done
-
-echo "MOVED=$MOVED"
+INIT=$(node ~/.donna/donna-tools.cjs init)
 ```
 
-If MOVED > 0, commit the move:
-```bash
-git -C <storage_repo> add -A
-git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "donna(migrate): move standing files to donna/ subfolder"
+Parse the JSON response. If the `error` field is `"not_configured"`, print:
 ```
-
-If `auto_push` is true in config, also push.
-
-**`backfill-tool-type`:** Backfill `type` on existing tool sections in tools.md using heuristic detection.
-
-Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not exist or has no tool sections, skip this handler.
-
-For each tool section (starting with `## <tool_name>`), check if a `- type:` line already exists. If the `- type:` line is missing, detect the correct type:
-
-1. If the tool section contains a `- command:` line where the value starts with `mcp:` (e.g., `- command: mcp:linear`), insert `- type: mcp` immediately after the `- command:` line.
-2. Else, if the tool section contains a `- base_url:` line:
-   - If the capabilities section contains entries that look like GraphQL queries (contain `query {` or `mutation {`), insert `- type: graphql` immediately after `## <tool_name>` (REST/GraphQL tools have no `- command:` line).
-   - Otherwise, insert `- type: rest` immediately after `## <tool_name>`.
-3. Else (no `mcp:` prefix, no `base_url` field), insert `- type: cli` immediately after the `- command:` line.
-
-Write the updated file back with the Write tool. If any changes were made, commit:
-```bash
-git -C <storage_repo> add -A
-git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "donna(migrate): backfill tool types on existing tools"
+x Donna is not configured. Run /donna:setup first.
 ```
+Stop.
 
-If `auto_push` is true in config, also push.
+Extract `storage_repo`, `daily_folder`, `auto_push` from the JSON.
 
-After processing all pending migrations, update `~/.donna/state.md` with the Write tool: remove the completed entries from `pending_migrations`. If no entries remain, write:
-```markdown
----
-pending_migrations: []
----
+If `update_available` is non-null, print:
+```
+Donna v<update_available> available -- run npx @pingvinen/donna-assistant to update
 ```
+Continue normally.
 </step>
 
 <step name="read-tools-md">
@@ -114,12 +57,16 @@ If `<type>` is `graphql`:
 
   **IMPORTANT: Auth is OPTIONAL for GraphQL tools. Public APIs work without any secret. You MUST always attempt introspection regardless of whether auth is configured. NEVER skip a GraphQL tool just because it has no auth_secret.**
 
-  1. Attempt to read `<storage_repo>/donna/secrets.md` with the Read tool. If the file exists and contains the `auth_secret` key with a value that is not a placeholder (does not contain "REPLACE_WITH"), set `<resolved_secret>` to that value. Otherwise, set `<resolved_secret>` to empty (no auth). **An empty resolved_secret is perfectly valid — proceed to step 2 regardless.**
+  1. Resolve the auth secret via Bash:
+  ```bash
+  node ~/.donna/donna-tools.cjs resolve-secret <auth_secret>
+  ```
+  Parse the JSON response. If `error` is `"key_not_found"` or `"placeholder_value"`, set `<resolved_secret>` to empty (no auth). Otherwise extract the `value` field as `<resolved_secret>`. **An empty resolved_secret is perfectly valid — proceed to step 2 regardless.**
 
-  2. Run via Bash with a 15-second timeout. Include the auth header only when a real secret was resolved:
+  2. Run via Bash with a 15-second timeout (set the Bash tool's `timeout` parameter to `15000`). Include the auth header only when a real secret was resolved:
      - If `<resolved_secret>` is non-empty:
        ```bash
-       timeout 15 curl -s -X POST \
+       curl -s -X POST \
          -H "<auth_header>: <resolved_secret>" \
          -H "Content-Type: application/json" \
          -d '{"query":"{ __schema { types { name fields { name type { name } } } } }"}' \
@@ -127,7 +74,7 @@ If `<type>` is `graphql`:
        ```
      - If `<resolved_secret>` is empty (public API or no secret configured):
        ```bash
-       timeout 15 curl -s -X POST \
+       curl -s -X POST \
          -H "Content-Type: application/json" \
          -d '{"query":"{ __schema { types { name fields { name type { name } } } } }"}' \
          "<base_url>" 2>&1
@@ -232,9 +179,48 @@ Determine if the tool is well-known (gh, jira, kubectl) or unknown. For well-kno
 - list-pods: `kubectl get pods --all-namespaces --field-selector=status.phase!=Succeeded -o wide`
 - list-failing: `kubectl get pods --all-namespaces --field-selector=status.phase=Failed -o wide`
 
-For **unknown tools**, run `<command> --help 2>&1 | head -80` via Bash and use Claude's understanding to identify 3–5 capabilities relevant to daily task management.
+For **unknown tools**, use a cascading approach to re-learn capabilities. Each stage builds on the previous. The goal is to update CLI invocations for existing capability names — do NOT ask the user to re-select capabilities.
+
+**Stage 1 — Local docs:**
+Attempt to find local documentation for the tool:
+```bash
+TOOL_PATH=$(which <command> 2>/dev/null)
+```
+If found, check for README or docs in the tool's package directory:
+```bash
+TOOL_DIR=$(dirname "$(dirname "$TOOL_PATH")")
+ls "$TOOL_DIR"/README* "$TOOL_DIR"/doc* "$TOOL_DIR"/docs* 2>/dev/null | head -5
+```
+If doc files exist, read the entry-point doc (prefer README, then docs/index or equivalent). Then follow internal links, references, or "see also" pointers to sections relevant to the existing capabilities. Use Claude's understanding to navigate — don't stop at a fixed line count.
+
+**Stage 2 — CLI help (baseline):**
+Run `<command> --help 2>&1 | head -80` via Bash. If the help output lists subcommands, also run `<command> <subcommand> --help` for subcommands relevant to existing capabilities. Combine with Stage 1 findings. Update invocations for existing capability names based on any changes to flags, subcommands, or output formats.
+
+**Stage 3 — Web docs (if invocations could not be updated from stages 1-2):**
+If any existing capability's invocation could not be validated from local docs or help output, attempt to fetch the tool's web documentation. Use WebFetch on common doc URLs:
+- `https://<command>.dev` or `https://<command>.io`
+- The homepage URL from `<command> --help` output if one was printed
+
+If a docs page is found, follow links to CLI reference, commands, or API sections rather than reading only the landing page.
+
+**Stage 4 — Source code analysis (user opt-in per D-09):**
+After stages 1-3, if the tool path was found, ask the user:
+
+Use AskUserQuestion:
+```
+Updated <N> capability invocations from docs and help output. Want me to analyze <command>'s source code for additional capabilities?
+```
 
-Do NOT ask the user to re-select capabilities — keep the same capability names, update only the CLI invocations if the training data suggests changes.
+If the user says yes:
+- Read the main entry point (e.g., bin/<command>, cli.js, main.py)
+- Follow imports/requires to command registration, subcommand definitions, or handler modules
+- Navigate into the files that define actual commands and actions — don't stop at the entry point
+- Identify new capabilities from function names, subcommands, or API surface
+- Add any new relevant capabilities to the list
+
+If no: continue with updated invocations.
+
+Do NOT ask the user to re-select capabilities — keep the same capability names, update only the CLI invocations. The cascade's Stage 4 is the only place where NEW capabilities might be added (with user opt-in).
 
 Get the new installed version:
 ```bash
@@ -258,24 +244,7 @@ Write the full file back with the Write tool.
 <step name="git-commit">
 Run via Bash:
 ```bash
-git -C <storage_repo> add -A
-```
-
-Check whether there is anything to commit:
-```bash
-git -C <storage_repo> status --porcelain
-```
-
-If the output is empty, skip the commit and continue.
-
-Otherwise, run:
-```bash
-git -C <storage_repo> commit -m "donna(relearn-tools): updated <count> tool(s)"
-```
-
-If `auto_push` is true in config, also run:
-```bash
-git -C <storage_repo> push
+node ~/.donna/donna-tools.cjs commit "donna(relearn-tools): updated <count> tool(s)" --files donna/tools.md
 ```
 </step>
 

package/workflows/remove-tool.md

@@ -0,0 +1,93 @@
+# Donna Remove-Tool Workflow
+
+<objective>
+Remove a registered tool from tools.md cleanly — confirm with the user, delete the tool's section, and commit.
+</objective>
+
+<step name="init">
+Run via Bash:
+```bash
+INIT=$(node ~/.donna/donna-tools.cjs init)
+```
+
+Parse the JSON response. If the `error` field is `"not_configured"`, print:
+```
+x Donna is not configured. Run /donna:setup first.
+```
+Stop.
+
+Extract `storage_repo`, `daily_folder`, `auto_push` from the JSON.
+
+If `update_available` is non-null, print:
+```
+Donna v<update_available> available -- run npx @pingvinen/donna-assistant to update
+```
+Continue normally.
+</step>
+
+<step name="read-tools-md">
+Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not exist or has no tool sections, print:
+```
+! No tools registered. Nothing to remove.
+```
+Stop.
+
+Parse each tool section (starting with `## <tool_name>`). For each tool, extract `type`, `command`, `scope`, and the capabilities list.
+
+Store as `<registered_tools>`.
+</step>
+
+<step name="select-tool">
+If a tool name was provided as argument (e.g., `/donna:remove-tool gh`), look it up in `<registered_tools>`. If not found, print `! Tool "<name>" not found in tools.md` and stop.
+
+If no argument was provided, list all registered tools via AskUserQuestion:
+```
+Which tool would you like to remove?
+
+<numbered list of tool names with their type>
+```
+Store the selected tool as `<selected_tool>`.
+</step>
+
+<step name="confirm-removal">
+Display the tool's current configuration summary:
+```
+About to remove <tool_name>:
+
+  type:         <type>
+  command:      <command>
+  scope:        <scope>
+  capabilities: <count> registered
+
+This will delete the tool's entire section from tools.md.
+```
+
+Use AskUserQuestion:
+```
+Remove <tool_name>? (yes/no)
+```
+
+If no, print `Cancelled.` and stop.
+</step>
+
+<step name="remove-from-tools-md">
+Read `<storage_repo>/donna/tools.md`. Remove the entire `## <tool_name>` section (from the `## <tool_name>` heading up to but not including the next `## ` heading, or end of file). Preserve all other tool sections unchanged. Write the full file back with the Write tool.
+
+If no tool sections remain after removal, write the file with just the frontmatter header (preserve any existing frontmatter).
+</step>
+
+<step name="git-commit">
+Run via Bash:
+```bash
+node ~/.donna/donna-tools.cjs commit "donna(remove-tool): removed <tool_name>" --files donna/tools.md
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+! Removed <tool_name> from tools.md
+
+To re-add with a different configuration: /donna:add-tool <tool_name>
+```
+</step>