@pingvinen/donna-assistant 0.6.0 → 0.7.0

package/README.md

@@ -73,7 +73,14 @@ Re-pulls data from all configured tools. New items appear, resolved items get cl
 
 ## External tools
 
-Donna can pull tasks and status from CLI tools you already have installed. Register them with:
+Donna can pull tasks and status from external tools you already use. She supports four tool types:
+
+- **CLI tools** — shell commands like `gh`, `jira`, `kubectl`
+- **REST APIs** — HTTP endpoints like GitHub API, Slack API
+- **GraphQL APIs** — GraphQL endpoints like Linear, GitHub GraphQL
+- **MCP servers** — Claude Code MCP tools like linear, postgres
+
+Register a tool with:
 
 ```
 /donna:add-tool gh
@@ -81,9 +88,17 @@ Donna can pull tasks and status from CLI tools you already have installed. Regis
 
 Or call it without arguments — Donna will check your role and suggest tools typically associated with your job.
 
-Donna verifies the tool is installed and authenticated, learns its capabilities, and asks what scope to query (which repos, projects, namespaces). Any CLI tool can be added — Donna uses the AI model's knowledge of well-known tools and parses `--help` output for everything else.
+For CLI tools, Donna verifies installation and authentication, learns capabilities, and asks what scope to query. For REST and GraphQL APIs, Donna sets up secure secret management (via a gitignored `secrets.md` file) and validates API connectivity. MCP servers are configured through Claude Code settings.
+
+When multiple tools are registered, Donna runs them in parallel — one agent per tool — so your morning brief stays fast regardless of how many tools you have.
+
+Edit a tool's configuration (scope, capabilities, auth, command, type) at any time:
+
+```
+/donna:adjust-tool
+```
 
-If a tool version is newer than what the AI model knows, Donna will inspect it to learn its current capabilities. You can also re-learn tools at any time:
+If a CLI tool version is newer than what the AI model knows, Donna will re-learn its capabilities:
 
 ```
 /donna:relearn-tools
@@ -120,9 +135,10 @@ Most commands are safe to run again. Want to update your role? Run `/donna:set-r
 | `/donna:begin-the-day` | Morning brief with carry-forward, recurring tasks, tool data |
 | `/donna:add-task` | Capture a task instantly |
 | `/donna:done` | Mark a task complete |
-| `/donna:add-tool` | Register an external CLI tool |
+| `/donna:add-tool` | Register an external tool (CLI, REST API, GraphQL API, MCP server) |
+| `/donna:adjust-tool` | Edit a tool's configuration (scope, capabilities, auth, command, type) |
 | `/donna:run-tools` | Refresh tool data mid-day |
-| `/donna:relearn-tools` | Update tool knowledge after upgrades |
+| `/donna:relearn-tools` | Update CLI tool knowledge after upgrades |
 | `/donna:help` | Conversational troubleshooting for config, storage, or skill issues |
 | `/donna:contribute-idea` | Submit a feature idea or bug report via GitHub Issues |
 

package/migrations/003-tool-type-backfill.cjs

@@ -0,0 +1,36 @@
+"use strict";
+
+module.exports = {
+    version: "0.7.0",
+    description: "Backfill type: cli on existing tool sections in tools.md",
+    up(ctx) {
+        // tools.md lives in the user's storage repo, which is not accessible
+        // from the migration context. We write a pending flag to state.md so that
+        // workflows can detect and execute the backfill on next skill run.
+        const statePath = ctx.path.join(ctx.donnaDir, "state.md");
+
+        if (ctx.fs.existsSync(statePath)) {
+            const content = ctx.fs.readFileSync(statePath, "utf8");
+            if (content.includes("backfill-tool-type")) {
+                // Already queued — idempotent, nothing to do
+                return;
+            }
+        }
+
+        if (ctx.fs.existsSync(statePath)) {
+            // Append to existing pending_migrations list
+            const existing = ctx.fs.readFileSync(statePath, "utf8");
+            const updated = existing.replace(
+                /^(pending_migrations:\n(?:\s+-\s+.*\n)*)/m,
+                "$1  - backfill-tool-type\n",
+            );
+            if (updated !== existing) {
+                ctx.fs.writeFileSync(statePath, updated, "utf8");
+                return;
+            }
+        }
+
+        const pendingFlag = "---\npending_migrations:\n  - backfill-tool-type\n---\n";
+        ctx.fs.writeFileSync(statePath, pendingFlag, "utf8");
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingvinen/donna-assistant",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Donna - your AI powered personal assistant",
   "bin": {
     "donna-assistant": "./bin/donna-assistant"

package/src/installer.cjs

@@ -79,7 +79,7 @@ async function run(options = {}) {
         for (const provider of detected) {
             fs.cpSync(provider.stubSource, provider.stubTarget, { recursive: true });
             output.success(
-                `Copied donna skills (setup, add-task, done, set-role, begin-the-day, add-tool, relearn-tools, run-tools, help, contribute-idea) to ${provider.stubTarget}`,
+                `Copied donna skills (setup, add-task, done, set-role, begin-the-day, add-tool, relearn-tools, run-tools, help, contribute-idea, adjust-tool) to ${provider.stubTarget}`,
             );
         }
     } else {

package/stubs/claude-code/donna/adjust-tool.md

@@ -0,0 +1,17 @@
+---
+name: donna:adjust-tool
+description: Edit an existing tool's configuration — scope, capabilities, auth, or command
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Run the Donna adjust-tool workflow. Edit an existing registered tool's configuration.
+</objective>
+
+<execution_context>
+@~/.donna/workflows/adjust-tool.md
+</execution_context>

package/workflows/add-tool.md

@@ -1,7 +1,7 @@
 # Donna Add-Tool Workflow
 
 <objective>
-Declare an external CLI tool, verify its installation and authentication, learn its capabilities, and persist the result to tools.md in the storage repo.
+Declare an external tool (CLI, REST API, GraphQL API, or MCP server), verify its connectivity, learn its capabilities, and persist the result to tools.md in the storage repo.
 </objective>
 
 <step name="read-config">
@@ -54,6 +54,26 @@ git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "
 
 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"
+```
+
+If `auto_push` is true in config, also push.
+
 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
 ---
@@ -84,17 +104,43 @@ What tool would you like to add? (e.g. gh, jira, kubectl)
 ```
 
 Store the answer as `<tool_name>`.
+</step>
+
+<step name="ask-tool-type">
+Use AskUserQuestion:
+```
+What type of tool is <tool_name>?
+
+1. CLI — runs shell commands (e.g., gh, jira, kubectl)
+2. REST API — HTTP endpoints (e.g., GitHub API, Slack API)
+3. GraphQL API — GraphQL endpoint (e.g., Linear, GitHub GraphQL)
+4. MCP server — Claude Code MCP tool (e.g., linear, postgres)
+```
 
-Resolve the CLI command — default to the tool name itself. If the tool name is in `<noted_tools>`, pre-fill any context from set-role notes. Use AskUserQuestion to confirm or override the CLI command:
+Store the answer as `<tool_type>`: one of `cli`, `rest`, `graphql`, `mcp`.
 
+**If type is `cli`:** Use AskUserQuestion to confirm or override the CLI command:
 ```
 CLI command for <tool_name>? (default: <tool_name>)
 ```
+If the tool name is in `<noted_tools>`, pre-fill any context from set-role notes. If the user presses enter without typing, use the default. Store the confirmed CLI command as `<command>`.
+
+**If type is `rest` or `graphql`:**
 
-If the user presses enter without typing, use the default. Store the confirmed CLI command as `<command>`.
+The base URL is the root API endpoint (for example, https://api.github.com for GitHub REST or https://api.linear.app/graphql for Linear). Guide the user if they seem unsure, but do not include examples in the AskUserQuestion prompt text — inline examples render as picker options in Claude Code.
+
+Use AskUserQuestion:
+```
+What is the base URL for <tool_name>?
+```
+Store as `<base_url>`. Set `<command>` to `<base_url>` (for display purposes).
+
+**If type is `mcp`:** Skip the command question. Set `<command>` to `mcp`.
 </step>
 
 <step name="verify-installation">
+If `<tool_type>` is not `cli`, skip this step.
+
 Run via Bash:
 ```bash
 which <command> && echo "INSTALLED=true" || echo "INSTALLED=false"
@@ -115,6 +161,8 @@ Store the output as `<version>`. If the command does not support `--version`, st
 </step>
 
 <step name="auth-test">
+**If `<tool_type>` is `cli`:**
+
 For well-known tools, run the appropriate auth test via Bash with a 10-second timeout:
 
 - `gh`: `timeout 10 gh api user --jq '.login' 2>&1`
@@ -132,9 +180,66 @@ Fix instructions per tool:
 - `kubectl` → check your kubeconfig
 
 Continue (do not stop — user may want to save the tool despite auth issues).
+
+**If `<tool_type>` is `rest` or `graphql`:**
+
+Common auth headers include Authorization (for Bearer tokens) and X-API-Key. Do not include examples in the prompt text.
+
+Use AskUserQuestion to ask for the auth header name:
+```
+What auth header does <tool_name> use? Default: Authorization
+```
+Store as `<auth_header>` (default: `Authorization` if blank).
+
+The key name should match the service convention (e.g., GITHUB_TOKEN, SLACK_TOKEN, LINEAR_API_KEY). Guide the user if needed but keep examples out of the prompt.
+
+Use AskUserQuestion to ask for the secret key name:
+```
+What should the secret key be called in secrets.md for <tool_name>?
+```
+Store as `<auth_secret>`.
+
+**Set up secrets.md:**
+Read `<storage_repo>/donna/secrets.md` with the Read tool. If the file does not exist, create it with:
+```markdown
+---
+# secrets.md -- managed by user, never by donna
+# Auto-added to .gitignore
+---
+```
+
+Check if `<auth_secret>` already appears in secrets.md. If not, append a placeholder line:
+```
+<auth_secret>: REPLACE_WITH_YOUR_SECRET
+```
+
+Write the updated secrets.md.
+
+**Ensure secrets.md is gitignored:**
+Read `<storage_repo>/.gitignore` with the Read tool. If the file does not exist or does not contain `donna/secrets.md`, append `donna/secrets.md` to `.gitignore` and write back. If `.gitignore` does not exist, create it with `donna/secrets.md` as its sole content.
+
+**Validate API connectivity:**
+Read `<storage_repo>/donna/secrets.md` to get the current value for `<auth_secret>`. If the value is `REPLACE_WITH_YOUR_SECRET` or the key is absent, print:
+```
+! No secret set for <auth_secret> — edit donna/secrets.md before testing connectivity.
+```
+Skip validation.
+
+If a real secret value exists, run via Bash:
+```bash
+curl -s -o /dev/null -w "%{http_code}" -H "<auth_header>: <resolved_secret>" <base_url> 2>&1
+```
+- 200-299: print `✓ API reachable at <base_url>`
+- 401/403: print `! Authentication failed — check <auth_secret> in donna/secrets.md`
+- Other/timeout: print `! Could not reach <base_url>`
+
+**If `<tool_type>` is `mcp`:**
+Print `ℹ MCP server auth is managed in Claude Code settings. Skipping auth test.`
 </step>
 
 <step name="ask-scope">
+**If `<tool_type>` is `cli`:**
+
 Ask the user to define the scope/context for this tool. Different tools need different scope:
 
 - **gh**: Which GitHub orgs or repos to pull from (e.g., `mycompany`, `mycompany/api mycompany/web`)
@@ -149,10 +254,28 @@ What scope should Donna use for <tool_name>?
 Leave blank for no filtering.
 ```
 
+**If `<tool_type>` is `rest` or `graphql`:**
+
+Use AskUserQuestion:
+```
+What scope should Donna use for <tool_name>? (e.g., specific endpoints or resource filters to apply)
+Leave blank for no filtering.
+```
+
+**If `<tool_type>` is `mcp`:**
+
+Use AskUserQuestion:
+```
+What scope should Donna use for <tool_name>? (e.g., specific resources to monitor)
+Leave blank for no filtering.
+```
+
 Store the answer as `<scope>`. If blank, set to empty string.
 </step>
 
 <step name="learn-capabilities">
+**If `<tool_type>` is `cli`:**
+
 Determine if the tool is well-known (gh, jira, kubectl) or unknown. For well-known tools, synthesize capabilities from training data. Do NOT parse --help for well-known tools.
 
 **gh (GitHub CLI) — training data baseline:**
@@ -179,6 +302,50 @@ If `<scope>` is set, replace `--all-namespaces` with `-n <namespace>` for each n
 
 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. If `<scope>` is set, incorporate the scope into the CLI invocations where appropriate. Format each as `name: <cli invocation>`.
 
+**If `<tool_type>` is `rest`:**
+
+Print to user:
+```
+Each capability is a name and HTTP method + path.
+Format: <name>: <METHOD> /path?params
+Example: list-issues: GET /repos/{owner}/{repo}/issues?state=open
+Example: my-profile: GET /user
+```
+
+Use AskUserQuestion:
+```
+Enter capabilities for <tool_name> (one per line, blank line when done):
+```
+
+**If `<tool_type>` is `graphql`:**
+
+Print to user:
+```
+Each capability is a name and a GraphQL query (single line).
+Format: <name>: query { ... }
+Example: my-issues: query { viewer { issues(first: 20, states: OPEN) { nodes { title url } } } }
+```
+
+Use AskUserQuestion:
+```
+Enter capabilities for <tool_name> (one per line, blank line when done):
+```
+
+**If `<tool_type>` is `mcp`:**
+
+Print to user:
+```
+Each capability is a name and an MCP tool reference.
+Format: <name>: mcp:<server_name>/<tool_name>
+Example: list-issues: mcp:linear/list_issues
+Example: search-docs: mcp:notion/search
+```
+
+Use AskUserQuestion:
+```
+Enter capabilities for <tool_name> (one per line, blank line when done):
+```
+
 Store the full list as `<available_capabilities>`.
 </step>
 
@@ -202,11 +369,14 @@ Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not ex
 ---
 ```
 
-Upsert (not overwrite) the tool's section. Each tool section has this format:
+Upsert (not overwrite) the tool's section. Each tool section has a type-specific format:
+
+**CLI tools:**
 ```markdown
 ## <tool_name>
 
 - command: <command>
+- type: cli
 - version: <version>
 - learned: <today's date YYYY-MM-DD>
 - auth_test: <auth_test_command or "none">
@@ -216,6 +386,47 @@ Upsert (not overwrite) the tool's section. Each tool section has this format:
 - <capability_name>: <cli_invocation>
 ```
 
+**REST API tools:**
+```markdown
+## <tool_name>
+
+- type: rest
+- base_url: <base_url>
+- auth_header: <auth_header>
+- auth_secret: <auth_secret>
+- scope: <scope or "none">
+- learned: <today's date YYYY-MM-DD>
+
+### Capabilities
+- <capability_name>: <METHOD> /path
+```
+
+**GraphQL API tools:**
+```markdown
+## <tool_name>
+
+- type: graphql
+- base_url: <base_url>
+- auth_header: <auth_header>
+- auth_secret: <auth_secret>
+- scope: <scope or "none">
+- learned: <today's date YYYY-MM-DD>
+
+### Capabilities
+- <capability_name>: <graphql_query>
+```
+
+**MCP server tools:**
+```markdown
+## <tool_name>
+
+- type: mcp
+- learned: <today's date YYYY-MM-DD>
+
+### Capabilities
+- <capability_name>: mcp:<server>/<tool>
+```
+
 If a section for this tool already exists in tools.md, replace it entirely. Write the full file back with the Write tool. Preserve all other tool sections unchanged.
 </step>
 
@@ -244,6 +455,8 @@ git -C <storage_repo> push
 </step>
 
 <step name="confirm">
+**If `<tool_type>` is `cli`:**
+
 Print:
 ```
 ✓ Added <tool_name> to tools registry
@@ -254,6 +467,29 @@ Print:
   Run /donna:begin-the-day to see tool data in your daily brief.
 ```
 
+**If `<tool_type>` is `rest` or `graphql`:**
+
+Print:
+```
+✓ Added <tool_name> to tools registry (type: <tool_type>)
+  Base URL: <base_url>
+  Capabilities: <count> configured
+  Secrets: Edit donna/secrets.md to set <auth_secret>
+
+  Run /donna:begin-the-day to see tool data in your daily brief.
+```
+
+**If `<tool_type>` is `mcp`:**
+
+Print:
+```
+✓ Added <tool_name> to tools registry (type: mcp)
+  Capabilities: <count> configured
+
+  Ensure the MCP server is configured in Claude Code settings.
+  Run /donna:begin-the-day to see tool data in your daily brief.
+```
+
 If in batch mode, repeat steps ask-tool-name through confirm for each remaining tool in `<noted_tools>`, then print a final summary:
 ```
 ✓ Configured <N> tools: <tool_name_1>, <tool_name_2>, ...

package/workflows/adjust-tool.md

@@ -0,0 +1,250 @@
+# Donna Adjust-Tool Workflow
+
+<objective>
+Edit an existing registered tool's configuration — scope, capabilities, auth/secrets, command, or type.
+</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.
+
+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"
+```
+
+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"
+```
+
+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"
+```
+
+If `auto_push` is true in config, also push.
+
+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: []
+---
+```
+</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. Run /donna:add-tool first.
+```
+Stop.
+
+Parse each tool section (starting with `## <tool_name>`). For each tool, extract the `type` field (if absent, treat as "cli"), `command`, `version`, `learned`, `auth_test`, `scope`, and capabilities list under `### Capabilities`.
+
+Store as `<registered_tools>`.
+</step>
+
+<step name="select-tool">
+If a tool name was provided as argument (e.g., `/donna:adjust-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 adjust?
+
+<numbered list of tool names from registered_tools>
+```
+Store the selected tool as `<selected_tool>`.
+</step>
+
+<step name="show-current-config">
+Display the current configuration of `<selected_tool>`:
+```
+Current configuration for <tool_name>:
+
+  command:   <command>
+  type:      <type>
+  version:   <version>
+  learned:   <learned>
+  auth_test: <auth_test>
+  scope:     <scope>
+
+  Capabilities:
+  - <name>: <invocation>
+  - ...
+```
+</step>
+
+<step name="ask-what-to-change">
+Use AskUserQuestion:
+```
+What would you like to change?
+
+1. scope — filtering context (orgs, repos, projects, namespaces)
+2. capabilities — add, remove, or modify capability commands
+3. command — the CLI command or base URL
+4. auth — auth test command or API secrets
+5. type — tool type (cli, rest, graphql, mcp)
+```
+Store as `<change_choice>`.
+</step>
+
+<step name="apply-change">
+Based on `<change_choice>`:
+
+**1. scope:**
+Show current scope. Use AskUserQuestion: `New scope for <tool_name>? (current: <scope>)`. Store new value.
+Then ask via AskUserQuestion: `Scope changed. Re-learn capabilities with new scope? (yes/no)`.
+If yes, run the same learn-capabilities logic as add-tool.md (well-known baselines for gh/jira/kubectl, `--help` parse for unknown tools), incorporating the new scope into CLI invocations.
+
+**2. capabilities:**
+Show current capabilities numbered. Use AskUserQuestion:
+```
+Current capabilities:
+1. <name>: <invocation>
+2. ...
+
+Type "remove <number>" to remove, "add <name>: <command>" to add, or "edit <number> <new_command>" to modify.
+```
+Apply the change. Allow multiple edits — keep asking until user says "done".
+
+**3. command:**
+Use AskUserQuestion: `New command for <tool_name>? (current: <command>)`. Store new value.
+Verify installation: `which <new_command>` via Bash. Print result.
+
+**4. auth:**
+For type=cli: Use AskUserQuestion to update auth_test command.
+For type=rest|graphql: Print `Edit your secrets in <storage_repo>/donna/secrets.md directly. The auth_secret field references the key name in that file.` Use AskUserQuestion to update `auth_secret` field name if needed.
+For type=mcp: Print `MCP server auth is managed in Claude Code settings, not in Donna.`
+
+**5. type:**
+Use AskUserQuestion:
+```
+What is the correct type for <tool_name>? (cli, rest, graphql, mcp) Current: <type>
+```
+Store new value as `<new_type>`.
+
+If `<new_type>` differs from `<type>`, check for capability format mismatches:
+
+**Detect format mismatches:**
+For each capability line (`- <name>: <invocation>`), check if the invocation matches the expected format for `<new_type>`:
+- `cli`: invocation should be a shell command (no `mcp:` prefix, no `GET /` or `POST /` pattern, no `query {` pattern)
+- `rest`: invocation should match `<METHOD> /path` pattern (e.g., `GET /repos/...`)
+- `graphql`: invocation should contain `query {` or `mutation {`
+- `mcp`: invocation should match `mcp:<server>/<tool>` pattern
+
+If ANY capability does not match the expected format for `<new_type>`, print:
+
+```
+⚠ Capability format mismatch detected. Current capabilities are in <type> format but type is changing to <new_type>.
+
+Mismatched capabilities:
+<list each mismatched capability with its current invocation>
+```
+
+Use AskUserQuestion:
+```
+How would you like to fix the capabilities?
+```
+Suggest these options:
+1. Re-enter capabilities manually (interactive editor)
+2. Clear all capabilities (start fresh with adjust-tool later)
+3. Keep as-is (may cause runtime errors)
+
+If option 1: Present the same interactive capabilities editing loop (show numbered list, accept "remove N", "add name: invocation", "edit N new_invocation", "done"). Pre-populate with existing capability NAMES but empty invocations so the user only needs to type the new format.
+
+If option 2: Clear the capabilities section entirely. Print `✓ Capabilities cleared. Run /donna:adjust-tool <tool_name> to add new capabilities.`
+
+If option 3: Print `⚠ Keeping mismatched capabilities — runtime errors may occur.`
+
+**Update structural fields when type changes:**
+- Changing TO rest/graphql: ensure `base_url`, `auth_header`, `auth_secret` fields exist. If missing, prompt for them (same prompts as add-tool).
+- Changing TO mcp: remove `command`, `version`, `base_url`, `auth_header`, `auth_secret` fields if present.
+- Changing TO cli: ensure `command`, `version` fields exist. If missing, prompt for command and run version check.
+- Changing FROM rest/graphql: remove `base_url`, `auth_header`, `auth_secret` fields.
+</step>
+
+<step name="write-tools-md">
+Read `<storage_repo>/donna/tools.md`. Update only the `<selected_tool>` section with the changed fields. Preserve all other tool sections unchanged. Write the full file back with the Write tool.
+</step>
+
+<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(adjust-tool): updated <tool_name> (<change_description>)"
+```
+
+If `auto_push` is true in config, also run:
+```bash
+git -C <storage_repo> push
+```
+</step>
+
+<step name="confirm">
+Print:
+```
+! Updated <tool_name>:
+  <field>: <old_value> -> <new_value>
+```
+</step>

package/workflows/begin-the-day.md

@@ -54,6 +54,26 @@ git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "
 
 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"
+```
+
+If `auto_push` is true in config, also push.
+
 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
 ---
@@ -132,9 +152,33 @@ Read `<storage_repo>/donna/tools.md` with the Read tool.
 
 If the file does not exist or has no tool sections (no `## ` headers after the frontmatter), set `<tool_tasks>` to an empty list and `<tool_warnings>` to an empty list. Continue to the next step. Do NOT print any error — tools are optional.
 
-For each tool section in tools.md, parse the `command` field and the `### Capabilities` entries. For each capability entry (format: `- <name>: <cli_invocation>`):
+Parse each tool section (starting with `## <tool_name>`). For each tool, extract the `type` field (if absent, treat as "cli"), the `command` field (or `base_url` for rest/graphql), and the capabilities list under `### Capabilities`.
+
+Store the parsed tools and their capabilities as `<registered_tools>`.
+
+**If only one tool is registered**, run it directly (no Task spawning needed) using the type-aware execution logic below.
+
+**If multiple tools are registered**, spawn one Task agent per tool. Each agent receives:
+
+- The tool name, type, and its capabilities list
+- For REST/GraphQL tools: the base_url, auth_header, and auth_secret fields
+- For MCP tools: the capability names with mcp: prefix
+- Instructions to execute all capabilities and return results as a structured list
+- Instructions to NEVER write to any file or run git commands
+
+**CRITICAL constraints for Task agents:**
+- Agents return raw task lists and warnings ONLY
+- Agents must NOT write to any file (no Write tool calls to daily file)
+- Agents must NOT run git commands (SSH signing constraint from CLAUDE.md)
+- All file writing happens in the main workflow after agents return
+
+**Global timeout:** Wait for all Task agents to complete, up to 2 minutes total. After 2 minutes, collect whatever results have been returned and treat non-responding tools as failed with warning: `! <tool_name>: timed out (2-minute batch limit)`.
 
-Run the CLI invocation via Bash with a 10-second timeout:
+**Type-aware execution within each agent (or direct execution for single tool):**
+
+For `type: cli` capabilities (format: `<name>: <cli_invocation>`):
+
+Run via Bash with a 10-second timeout:
 ```bash
 timeout 10 <cli_invocation> 2>&1
 ```
@@ -161,7 +205,44 @@ Determine the failure type from the exit code and output:
 - Exit 127 or "not found" in output: `! <tool_name>: command not found — install <command> first`
 - Other: `! <tool_name>: <first line of stderr>`
 
-Add the warning to `<tool_warnings>`. Continue to next capability/tool. Never retry. Tool failures must never block manual tasks, carry-forward, or recurring task processing.
+Add the warning to `<tool_warnings>`. Continue to next capability/tool. Never retry.
+
+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:
+```bash
+timeout 10 curl -s -H "<auth_header>: <resolved_secret>" "<base_url><path>" 2>&1
+```
+4. Parse the JSON response using Claude's understanding to extract task-like items. Format:
+`- [ ] (<tool_name>) <description> [<identifier>](<url>)`
+
+**On any failure** (non-zero exit, timeout, missing secret):
+Add a warning: `! <tool_name>: <error_description>`
+Continue. Never retry.
+
+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:
+```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
+```
+3. Parse the JSON response to extract task-like items. Same format as REST.
+
+**On any failure** (non-zero exit, timeout, missing secret):
+Add a warning: `! <tool_name>: <error_description>`
+Continue. Never retry.
+
+For `type: mcp` capabilities (format: `<name>: mcp:<server>/<tool>`):
+1. Invoke the MCP tool directly using Claude's native MCP tool invocation (NOT via Bash).
+2. Parse the MCP tool's response using Claude's understanding of the tool to extract task-like items. Format:
+`- [ ] (<tool_name>) <description> [<identifier>](<url>)`
+
+**On any failure:**
+Add a warning: `! <tool_name>: <error_description>`
+Continue. Never retry.
+
+Tool failures must never block manual tasks, carry-forward, or recurring task processing.
 
 Collect all task entries as `<tool_tasks>`.
 Collect all warning messages as `<tool_warnings>`.

package/workflows/relearn-tools.md

@@ -54,6 +54,26 @@ git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "
 
 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"
+```
+
+If `auto_push` is true in config, also push.
+
 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
 ---
@@ -70,31 +90,92 @@ Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not ex
 Stop.
 
 Parse each tool section (starting with `## <tool_name>`). For each tool, extract:
-- `command` — the CLI command to run
-- `version` — the stored version string
+- `command` — the CLI command to run (CLI/MCP tools only)
+- `type` — the tool type field (if absent, treat as "cli")
+- `version` — the stored version string (CLI tools only)
 - `learned` — the date capabilities were last learned
+- `base_url` — the API endpoint (REST/GraphQL tools only)
+- `auth_header` — the auth header name, if present (REST/GraphQL tools only)
+- `auth_secret` — the secret key name, if present (REST/GraphQL tools only)
 - capabilities list under `### Capabilities`
 
 Store the parsed tools as `<registered_tools>`.
 </step>
 
 <step name="check-versions">
-For each tool in `<registered_tools>`, run via Bash:
-```bash
-<command> --version 2>/dev/null | head -1
-```
+For each tool in `<registered_tools>`:
+
+If `<type>` is `rest` or `mcp`:
+  Add to `<unchanged_tools>` — version checking is not applicable for REST/MCP tools.
+  Continue to next tool.
+
+If `<type>` is `graphql`:
+  Run a GraphQL introspection query to detect schema changes.
+
+  **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.**
+
+  2. Run via Bash with a 15-second timeout. Include the auth header only when a real secret was resolved:
+     - If `<resolved_secret>` is non-empty:
+       ```bash
+       timeout 15 curl -s -X POST \
+         -H "<auth_header>: <resolved_secret>" \
+         -H "Content-Type: application/json" \
+         -d '{"query":"{ __schema { types { name fields { name type { name } } } } }"}' \
+         "<base_url>" 2>&1
+       ```
+     - If `<resolved_secret>` is empty (public API or no secret configured):
+       ```bash
+       timeout 15 curl -s -X POST \
+         -H "Content-Type: application/json" \
+         -d '{"query":"{ __schema { types { name fields { name type { name } } } } }"}' \
+         "<base_url>" 2>&1
+       ```
+
+  3. If the request fails (non-zero exit, timeout, or error response), add to `<unchanged_tools>` with note "introspection failed — skipped" and continue.
+
+  4. If successful, compare the returned schema against stored capabilities:
+     - Extract field names and types from the introspection response for the types/queries relevant to stored capabilities.
+     - Check if any stored capability references fields that no longer exist in the schema (removed fields).
+     - Check if the schema has new fields on types used by stored capabilities that might be useful.
+
+  5. If no meaningful changes detected, add to `<unchanged_tools>`.
+
+  6. If changes detected, add to `<changed_tools>` with a `<schema_changes>` annotation listing:
+     - Removed fields (fields in stored capabilities no longer in schema)
+     - New fields (fields in schema not referenced by any stored capability)
+
+If `<type>` is `cli` (or absent; treat as `cli`):
+  Run via Bash:
+  ```bash
+  <command> --version 2>/dev/null | head -1
+  ```
+
+  Compare the output against the stored `version` field using simple string equality — "is it different?" is sufficient; no semver parsing required.
+
+  If `<command>` is not found (command fails), treat it as changed with a warning note.
+
+  Add to:
+  - `<changed_tools>` — installed version differs from stored version (or command not found)
+  - `<unchanged_tools>` — installed version matches stored version exactly
+</step>
 
-Compare the output against the stored `version` field using simple string equality — "is it different?" is sufficient; no semver parsing required.
+<step name="report-unchanged">
+For each tool in `<unchanged_tools>`:
 
-If `<command>` is not found (command fails), treat it as changed with a warning note.
+If `<type>` is `rest` or `mcp`, print:
+```
+⊘ <tool_name>: <type> tool — re-learning not applicable (capabilities are user-defined)
+```
 
-Collect tools into two lists:
-- `<changed_tools>` — installed version differs from stored version (or command not found)
-- `<unchanged_tools>` — installed version matches stored version exactly
-</step>
+If `<type>` is `graphql`, print using the skip reason from check-versions:
+```
+⊘ <tool_name>: graphql tool — <skip_reason>
+```
+Where `<skip_reason>` is "no schema changes detected" or "introspection failed — skipped".
 
-<step name="report-unchanged">
-For each tool in `<unchanged_tools>`, print:
+Otherwise (CLI tools), print:
 ```
 ⊘ <tool_name>: unchanged at <version> — skipped
 ```
@@ -106,7 +187,34 @@ If ALL tools are in `<unchanged_tools>` (no changes found), print:
 Stop.
 </step>
 
+<step name="relearn-graphql">
+For each graphql tool in `<changed_tools>`:
+
+Print:
+```
+⚠ <tool_name>: schema changes detected
+  Removed fields: <list or "none">
+  New fields: <list or "none">
+```
+
+Use AskUserQuestion:
+```
+Update capabilities for <tool_name>?
+```
+Suggest "yes" and "no" as options.
+
+If yes:
+  Show the current capabilities and the detected changes side by side. Use AskUserQuestion to let the user update capabilities interactively (same editing loop as adjust-tool: "remove <number>", "add <name>: <query>", "edit <number> <new_query>", "done").
+
+  Store the updated capabilities. Update `learned` date to today.
+
+If no:
+  Skip — keep existing capabilities unchanged. Update `learned` date to today (to avoid re-checking next run).
+</step>
+
 <step name="relearn-changed">
+Note: Re-learning is supported for CLI tools (version-based) and GraphQL tools (schema introspection). REST and MCP tool capabilities are user-defined and not auto-learned.
+
 For each tool in `<changed_tools>`, apply the same learn-capabilities logic as add-tool.md's learn-capabilities step.
 
 Determine if the tool is well-known (gh, jira, kubectl) or unknown. For well-known tools, synthesize capabilities from training data. Do NOT parse --help for well-known tools.

package/workflows/run-tools.md

@@ -54,6 +54,26 @@ git -C <storage_repo> diff --cached --quiet || git -C <storage_repo> commit -m "
 
 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"
+```
+
+If `auto_push` is true in config, also push.
+
 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
 ---
@@ -69,7 +89,7 @@ Read `<storage_repo>/donna/tools.md` with the Read tool. If the file does not ex
 ```
 Stop.
 
-Parse each tool section (starting with `## <tool_name>`). For each tool, extract the `command` field and the capabilities list under `### Capabilities`.
+Parse each tool section (starting with `## <tool_name>`). For each tool, extract the `type` field (if absent, treat as "cli"), the `command` field, and the capabilities list under `### Capabilities`.
 
 Store the parsed tools and their capabilities as `<registered_tools>`.
 </step>
@@ -101,7 +121,27 @@ If the `## From Tools` section does not exist in today's file, set `<existing_to
 </step>
 
 <step name="pull-fresh-data">
-For each tool in `<registered_tools>`, for each capability:
+**If only one tool is registered**, run it directly (no Task spawning needed) using the type-aware execution logic below.
+
+**If multiple tools are registered**, spawn one Task agent per tool. Each agent receives:
+
+- The tool name, type, and its capabilities list
+- For REST/GraphQL tools: the base_url, auth_header, and auth_secret fields
+- For MCP tools: the capability names with mcp: prefix
+- Instructions to execute all capabilities and return results as a structured list
+- Instructions to NEVER write to any file or run git commands
+
+**CRITICAL constraints for Task agents:**
+- Agents return raw task lists and warnings ONLY
+- Agents must NOT write to any file (no Write tool calls to daily file)
+- Agents must NOT run git commands (SSH signing constraint from CLAUDE.md)
+- All file writing happens in the main workflow after agents return
+
+**Global timeout:** Wait for all Task agents to complete, up to 2 minutes total. After 2 minutes, collect whatever results have been returned and treat non-responding tools as failed with warning: `! <tool_name>: timed out (2-minute batch limit)`.
+
+**Type-aware execution within each agent (or direct execution for single tool):**
+
+For `type: cli` capabilities (format: `<name>: <cli_invocation>`):
 
 Run the capability command via Bash with a 10-second timeout:
 ```bash
@@ -133,6 +173,41 @@ For other tools: use Claude's understanding to extract task-like items from the
 ```
 Continue to the next capability. Never retry.
 
+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:
+```bash
+timeout 10 curl -s -H "<auth_header>: <resolved_secret>" "<base_url><path>" 2>&1
+```
+4. Parse the JSON response using Claude's understanding to extract task-like items. Format:
+`- [ ] (<tool_name>) <description> [<identifier>](<url>)`
+
+**On any failure** (non-zero exit, timeout, missing secret):
+Add a warning: `! <tool_name>: <error_description>`
+Continue. Never retry.
+
+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:
+```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
+```
+3. Parse the JSON response to extract task-like items. Same format as REST.
+
+**On any failure** (non-zero exit, timeout, missing secret):
+Add a warning: `! <tool_name>: <error_description>`
+Continue. Never retry.
+
+For `type: mcp` capabilities (format: `<name>: mcp:<server>/<tool>`):
+1. Invoke the MCP tool directly using Claude's native MCP tool invocation (NOT via Bash).
+2. Parse the MCP tool's response using Claude's understanding of the tool to extract task-like items. Format:
+`- [ ] (<tool_name>) <description> [<identifier>](<url>)`
+
+**On any failure:**
+Add a warning: `! <tool_name>: <error_description>`
+Continue. Never retry.
+
 Store all fresh tasks as `<fresh_tool_tasks>`: a map of URL to task line.
 Collect all warning messages as `<tool_warnings>`.
 </step>