drupal-mcp-connector 2.20.0 → 2.21.0

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.21.0] - 2026-09-19
+
+### Added
+- **Module-owned workflow prompts (#333).** Workflows are definitions the
+  connector loads, filters and relays. v1 sources them from built-in
+  definitions (the five connector-authored workflows, now the same format)
+  and from `serverTools.modules.workflows` next to approved module tools.
+  A workflow names tools by local alias (`{tool:alias}`), is listed only
+  when every named tool is visible, and cannot invent a tool the site did
+  not already approve. Write workflows require `mcp_write`, tell the model
+  to confirm, and append that module writes are not retried. Design:
+  `docs/module-workflows.md`. The example config ships `review_and_log` on
+  `example_site`. Drupal `prompts/list` is specified there and not
+  implemented in this change.
+
+### Fixed
+- **Remaining northbound HTTP timeouts.** Server-tool `tools/call` (including
+  governed config), the OAuth token POST, and the Sentinel readiness GET now
+  abort with `AbortSignal.timeout` so a hung Drupal/Sentinel host cannot stall
+  the MCP process. `requestServerTool` always attaches the 256 KiB body cap and
+  a 15s abort; those were previously gated on `maxBytes`, so `callGovernedServerTool`
+  could hang unbounded. Token acquisition fails as `OAuthError` after 30s.
+  A hung readiness probe stays `sentinel_unreachable`.
+
 ## [2.20.0] - 2026-09-19
 
 ### Added

package/README.md

@@ -118,6 +118,8 @@ and other MCP-aware agents). Two kinds ship with the connector:
 - `drupal-create-article` — guided article creation with all fields
 - `drupal-seo-fix` — find and fix SEO gaps
 - `drupal-user-cleanup` — identify and handle inactive accounts
+- Module-owned workflows (`drupal-<namespace>-<workflow>`) when
+  `serverTools.modules.workflows` is enabled — see `docs/module-workflows.md`
 
 **One prompt per tool** — every `drupal_*` tool is also exposed as a
 `drupal-<tool>` prompt (e.g. `drupal-create-node`, `drupal-list-nodes`,

package/config/config.example.json

@@ -155,7 +155,7 @@
 
   "_server_tools": {
     "_comment": "serverTools.url is the JSON-RPC endpoint of the Drupal-side governed MCP tools (mcp_server_tool_bridge / mcp_sentinel), resolved against baseUrl. Required for drupal_config_get/list/set. The config-inspection audits will also use it (governed path) when present, but fall back to the drush bridge, so it is optional for the audits. Authenticated with the same OAuth bearer.",
-    "_modules_comment": "Optional. serverTools.modules exposes Drupal module-owned tools through the generic registry. It is opt-in: a tool installed on the source, or listed in its catalog, is not exposed until it is named here. namespace is lowercase letters, digits and underscores, up to 24 characters. An alias follows the same rule, up to 48 characters. The namespace and alias together must be unique across configured sites. Each entry under tools is an alias with four required keys. name is the exact wire name from the source's tools/list; copy it, because bridge versions join the parts differently and the connector does not rewrite it. scope is the inbound scope a caller needs. operation is read, write or delete; it sets the public tool name (drupal_module_<operation>_<namespace>__<alias>) and the connector gate, whatever the source's own annotation says. capabilities lists extra connector gates (publish, configRead, configWrite, graphql, rawSql) and may be empty. These keys only narrow access; Drupal stays authoritative. To get slash-command stubs for the approved module tools, run `npm run install:commands -- --modules` from the directory that holds config/config.json. See docs/module-tools.md.",
+    "_modules_comment": "Optional. serverTools.modules exposes Drupal module-owned tools through the generic registry. It is opt-in: a tool installed on the source, or listed in its catalog, is not exposed until it is named here. namespace is lowercase letters, digits and underscores, up to 24 characters. An alias follows the same rule, up to 48 characters. The namespace and alias together must be unique across configured sites. Each entry under tools is an alias with four required keys. name is the exact wire name from the source's tools/list; copy it, because bridge versions join the parts differently and the connector does not rewrite it. scope is the inbound scope a caller needs. operation is read, write or delete; it sets the public tool name (drupal_module_<operation>_<namespace>__<alias>) and the connector gate, whatever the source's own annotation says. capabilities lists extra connector gates (publish, configRead, configWrite, graphql, rawSql) and may be empty. These keys only narrow access; Drupal stays authoritative. To get slash-command stubs for the approved module tools, run `npm run install:commands -- --modules` from the directory that holds config/config.json. Optional serverTools.modules.workflows enables module-owned workflow prompts (drupal-<namespace>-<workflow>); a workflow may only name aliases already under tools. See docs/module-tools.md and docs/module-workflows.md.",
     "_bindings_comment": "Optional. serverTools.bindings keeps a built-in command's public name while its implementation lives in a Drupal module. Each binding names an alias under serverTools.modules.tools on the same site. configGet, configList, configSet serve drupal_config_get/list/set and the config reports; codegenInspect, codegenDiff, codegenPreview serve drupal_codegen_inspect/diff/generate; sqlQuery serves drupal_drush_sql_query. Required alias policy: config and codegen aliases use scope mcp_config; get, list and the three codegen aliases are operation read with capability configRead; configSet is operation write with capability configWrite; sqlQuery is scope mcp_admin, operation read, capability rawSql, and still needs drushSsh.rawSql: \"governed\" on the site. Once a bindings object exists, every one of these commands resolves only through its binding: a missing or mismatched mapping refuses the command, with no fallback to another tool or to SSH. Configure the full set for the commands the site uses. Without a bindings object these commands keep their built-in transport. See docs/module-tools.md.",
     "example": {
       "serverTools": {
@@ -182,6 +182,17 @@
             "codegen_diff":     { "name": "tool_api__graphql_compose_codegen_diff",       "scope": "mcp_config", "operation": "read",  "capabilities": ["configRead"] },
             "codegen_preview":  { "name": "tool_api__graphql_compose_codegen_preview",    "scope": "mcp_config", "operation": "read",  "capabilities": ["configRead"] },
             "sql_query":        { "name": "tool_api__mcp_sentinel_sql_query",             "scope": "mcp_admin",  "operation": "read",  "capabilities": ["rawSql"] }
+          },
+          "workflows": {
+            "review_and_log": {
+              "description": "Review recent activities and, after confirmation, log a follow-up. Write is opt-in and is not retried.",
+              "readOnly": false,
+              "tools": ["list_activities", "record_activity"],
+              "arguments": [
+                { "name": "site", "description": "Target site", "required": false }
+              ],
+              "instructions": "1. Call {tool:list_activities} for recent rows.\n2. Summarize what needs a follow-up.\n3. Ask the person before calling {tool:record_activity}. Do not retry a write."
+            }
           }
         },
         "bindings": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drupal-mcp-connector",
-  "version": "2.20.0",
+  "version": "2.21.0",
   "description": "Drupal MCP Connector — multi-site MCP server for Drupal with JSON:API and GraphQL, governed writes, draft translations, content tools, audit reports, and an SSH Drush bridge.",
   "type": "module",
   "main": "src/index.js",

package/scripts/generate-commands.js

@@ -45,6 +45,20 @@ export function commandFileName(def) {
 /** Trailing marker that tells the installer a stub belongs to a module-owned tool. */
 export const MODULE_STUB_MARKER = "<!-- drupal-mcp-connector:module-tool -->";
 
+/** Trailing marker for a module-owned workflow stub. */
+export const WORKFLOW_STUB_MARKER = "<!-- drupal-mcp-connector:module-workflow -->";
+
+/**
+ * Command filename for a module-owned workflow prompt.
+ *
+ * @param {string} namespace
+ * @param {string} id
+ * @returns {string}
+ */
+export function workflowCommandFileName(namespace, id) {
+  return `drupal-${namespace}-${id}.md`.replace(/_/g, "-");
+}
+
 const MODULE_TOOL_NAME = /^drupal_module_(?:read|write|delete)_([a-z][a-z0-9_]*?)__([a-z][a-z0-9_]*)$/;
 
 /**
@@ -144,6 +158,35 @@ export function renderCommandMarkdown(def, options = {}) {
  * @param {object} def - The tool definition.
  * @returns {string} File contents.
  */
+/**
+ * Filesystem stub for a module-owned workflow prompt.
+ *
+ * @param {object} workflow - A loaded workflow from the #333 loader.
+ * @returns {string}
+ */
+export function renderWorkflowCommandMarkdown(workflow) {
+  const params = (workflow.arguments ?? []).map((arg) => ({
+    name: arg.name,
+    required: Boolean(arg.required),
+  }));
+  const hint = argumentHint(params);
+  const tools = (workflow.publicTools ?? []).map((name) => `\`${name}\``).join(", ");
+  const body = [
+    `# ${workflow.name}`,
+    "",
+    workflow.description,
+    "",
+    `This is a workflow prompt. Ask the MCP client for prompt \`${workflow.name}\`.`,
+    tools ? `It names these tools: ${tools}.` : "",
+    workflow.readOnly
+      ? "Read-only: do not write."
+      : "Confirm with the person before any write. Module writes are not retried.",
+    "",
+    WORKFLOW_STUB_MARKER,
+  ].filter((line, i, arr) => line !== "" || arr[i - 1] !== "");
+  return `---\ndescription: ${yamlString(workflow.description)}\nargument-hint: "${hint}"\n---\n\n${body.join("\n")}\n`;
+}
+
 export function renderClaudeCommandMarkdown(def) {
   return renderCommandMarkdown(def, {
     allowedTools: `mcp__drupal__${def.name}`,

package/scripts/install-commands.js

@@ -32,10 +32,13 @@ import {
   commandFileName,
   moduleCommandFileName,
   MODULE_STUB_MARKER,
+  WORKFLOW_STUB_MARKER,
   renderCommandMarkdown,
   renderClaudeCommandMarkdown,
   renderCodexSkillMarkdown,
   renderCodexToolsReference,
+  renderWorkflowCommandMarkdown,
+  workflowCommandFileName,
   CODEX_SKILL_NAME,
 } from "./generate-commands.js";
 
@@ -154,15 +157,43 @@ export function missingModuleTools(configured, discovered) {
   return configured.filter((name) => !found.has(name));
 }
 
-/** Whether an installed stub was written for a module-owned tool. */
+/** Whether an installed stub was written for a module-owned tool or workflow. */
 function isModuleStub(path) {
   try {
-    return readFileSync(path, "utf8").includes(MODULE_STUB_MARKER);
+    const text = readFileSync(path, "utf8");
+    return text.includes(MODULE_STUB_MARKER) || text.includes(WORKFLOW_STUB_MARKER);
   } catch {
     return false;
   }
 }
 
+/**
+ * Workflow stubs for enabled local definitions whose named tools were discovered.
+ *
+ * @param {object[]} workflows
+ * @param {Set<string>} builtInFiles
+ * @param {Set<string>} moduleFiles
+ * @returns {{stubs: Array<{file: string, workflow: object}>, refused: Array<object>}}
+ */
+export function planWorkflowStubs(workflows, builtInFiles, moduleFiles) {
+  const stubs = [];
+  const refused = [];
+  const byFile = new Map();
+  for (const workflow of workflows ?? []) {
+    const file = workflowCommandFileName(workflow.namespace, workflow.id);
+    if (builtInFiles.has(file) || moduleFiles.has(file)) {
+      refused.push({ name: workflow.name, file, reason: "matches a built-in or module-tool command" });
+      continue;
+    }
+    byFile.set(file, [...(byFile.get(file) ?? []), workflow]);
+  }
+  for (const [file, defs] of byFile) {
+    if (defs.length === 1) stubs.push({ file, workflow: defs[0] });
+    else defs.forEach((workflow) => refused.push({ name: workflow.name, file, reason: "shared by more than one workflow" }));
+  }
+  return { stubs, refused };
+}
+
 /**
  * Write one `drupal-*.md` per tool into each requested client directory,
  * pruning stale stubs first. Unknown client names fail closed.
@@ -229,6 +260,11 @@ export function install(options = {}) {
       writeFileSync(join(dir, file), client.render(def));
       moduleWritten.push(file);
     }
+    const workflowStubs = options.workflowStubs ?? [];
+    for (const { file, workflow } of workflowStubs) {
+      writeFileSync(join(dir, file), renderWorkflowCommandMarkdown(workflow));
+      moduleWritten.push(file);
+    }
     results.push({ client: name, dir, written, moduleWritten });
   }
   return results;
@@ -266,9 +302,11 @@ deprecated Codex custom prompts (~/.codex/prompts).
   --home DIR       Install root (default: the current user's home)
   --clients LIST   Comma-separated subset of: claude, grok, codex, agents
                    (default: claude,grok,codex)
-  --modules        Also write stubs for module-owned tools. Discovers them from
-                   the sources in config/config.json (run from that directory).
-                   Without this flag, installed module stubs are left alone.
+  --modules        Also write stubs for module-owned tools and workflows.
+                   Discovers tools from the sources in config/config.json
+                   (run from that directory). Workflows come from
+                   serverTools.modules.workflows. Without this flag, installed
+                   module stubs are left alone.
 `;
 
 const invokedDirectly =
@@ -302,6 +340,19 @@ if (invokedDirectly) {
       opts.moduleParts = parts;
       // An incomplete listing must not delete stubs for tools that may only be unreachable.
       opts.pruneModules = missing.length === 0;
+      const { loadWorkflows, moduleWorkflowProviders } = await import("../src/lib/workflow-prompts.js");
+      const { listResolvableSiteConfigs } = await import("../src/lib/dispatch.js");
+      const workflows = loadWorkflows(moduleWorkflowProviders(listResolvableSiteConfigs()), {
+        tools: definitions,
+        taken: new Set(allDefinitions.map((def) => def.name.replace(/_/g, "-"))),
+      });
+      const builtInFiles = new Set(allDefinitions.map(commandFileName));
+      const moduleFiles = new Set(planModuleStubs(definitions, allDefinitions, parts).stubs.map((s) => s.file));
+      const planned = planWorkflowStubs(workflows, builtInFiles, moduleFiles);
+      for (const r of planned.refused) {
+        console.error(`[install-commands] WARNING: no workflow stub for ${r.name}: ${r.reason}${r.file ? ` (${r.file})` : ""}`);
+      }
+      opts.workflowStubs = planned.stubs;
     }
     const results = install(opts);
     for (const r of results) {

package/src/index.js

@@ -60,6 +60,15 @@ import {
 import { allDefinitions, allHandlers, definitionsByName } from "./tools/index.js";
 import { createModuleToolRegistry, isModuleTool } from "./lib/module-tools.js";
 import { buildToolPrompts, createPromptSurface } from "./lib/tool-prompts.js";
+import {
+  loadWorkflows,
+  toPromptDescriptor,
+  renderWorkflowMessages,
+  moduleWorkflowProviders,
+  registerBuiltinWorkflows,
+  replaceModuleWorkflows,
+} from "./lib/workflow-prompts.js";
+import { builtinWorkflowProvider } from "./lib/workflows/builtin.js";
 
 // Apply config/secrets.map (or the shipped example table) before any site
 // resolution. MCP clients spawn this file directly; the shell launcher is
@@ -167,129 +176,31 @@ async function readResource(uri) {
 // MCP Prompts — common Drupal workflow templates
 // ---------------------------------------------------------------------------
 
-const PROMPTS = [
-  {
-    name:        "drupal-content-audit",
-    description: "Walk through a full content audit: inventory, staleness, SEO gaps, accessibility issues, and recommendations.",
-    arguments:   [{ name: "site", description: "Named site to audit (omit for default)", required: false }],
-  },
-  {
-    name:        "drupal-create-article",
-    description: "Guided workflow to research, draft, and publish an article node with all fields, tags, and metadata.",
-    arguments:   [
-      { name: "site",  description: "Target site",        required: false },
-      { name: "topic", description: "Article topic/brief", required: true  },
-    ],
-  },
-  {
-    name:        "drupal-seo-fix",
-    description: "Find SEO gaps in content (missing meta descriptions, thin content, title issues) and fix them interactively.",
-    arguments:   [
-      { name: "site", description: "Target site",         required: false },
-      { name: "type", description: "Content type to scan", required: false },
-    ],
-  },
-  {
-    name:        "drupal-user-cleanup",
-    description: "Identify inactive, never-logged-in, or overly permissioned user accounts and take action.",
-    arguments:   [{ name: "site", description: "Target site", required: false }],
-  },
-  {
-    name:        "drupal-full-audit",
-    description: "Run a full site-health audit — content, link/404 integrity, and configuration posture — and turn the scored dashboard into a prioritized action plan.",
-    arguments:   [
-      { name: "site", description: "Named site to audit (omit for default)", required: false },
-      { name: "type", description: "Primary content type to audit",          required: false },
-    ],
-  },
-];
+const builtinWorkflows = loadWorkflows([builtinWorkflowProvider], { tools: allDefinitions });
+registerBuiltinWorkflows(builtinWorkflows);
+const PROMPTS = builtinWorkflows.map(toPromptDescriptor);
 
 // Per-tool prompts: one slash-command prompt for every Drupal tool, derived from
 // the tool definitions so the set always matches the tools. Merged after the
-// hand-authored workflow prompts above (names never collide — workflow prompts use
-// composite verbs, tool prompts mirror the `drupal_*` tool names).
+// workflow prompts (names never collide — workflow prompts use composite verbs,
+// tool prompts mirror the `drupal_*` tool names).
 const WORKFLOW_PROMPT_NAMES = new Set(PROMPTS.map((p) => p.name));
 const TOOL_PROMPTS = buildToolPrompts(allDefinitions);
 const ALL_PROMPTS  = [...PROMPTS, ...TOOL_PROMPTS];
 
 /**
- * Build the message list for a named prompt, interpolating site/type/topic
- * args into a pre-authored multi-step workflow. Unknown prompt names fall back
- * to a generic one-line instruction so the call never fails.
+ * Build the message list for a named built-in workflow. Unknown names fall
+ * back to a generic one-line instruction so the call never fails.
  *
  * @param {string} name - The prompt name.
  * @param {object} args - Prompt arguments (site, type, topic — all optional).
  * @returns {Array<object>} MCP prompt messages.
  */
 function getPromptMessages(name, args) {
-  const site  = args?.site  ? `on the "${args.site}" site` : "on the default site";
-  const type  = args?.type  || "article";
-  const topic = args?.topic || "the requested topic";
-
-  const prompts = {
-    "drupal-content-audit": [
-      { role: "user", content: { type: "text", text:
-        `Please run a comprehensive content audit ${site}. Do not assume any particular content type exists — every site has a different model, so discover it first and audit the types this site actually has.\n` +
-        "1. Call drupal_report_content_summary for the full inventory. Its byContentType list is the set of content types to audit — derive the types from it; never assume a fixed type such as \"article\".\n" +
-        "2. For each content type that has nodes, call drupal_report_stale_content (days: 180).\n" +
-        "3. For each content type that has nodes, call drupal_report_field_completeness.\n" +
-        "4. For each content type with published nodes, check SEO: prefer drupal_report_seo_meta_coverage (it reads the site's actual meta field rather than assuming one) and use drupal_report_seo_audit for title-length and thin-content checks.\n" +
-        "5. For each content type with published nodes, call drupal_report_accessibility_audit.\n" +
-        "6. For any content type reporting zero nodes, skip its per-type scans and record it as empty — an empty type is not a clean one.\n" +
-        "7. Synthesize findings into: (a) immediate actions, (b) medium-term improvements, (c) process recommendations.\n" +
-        "Present results as a structured report with counts, severity, and specific node links where possible. State which content types were scanned so an empty or unexpected model cannot be mistaken for a clean audit."
-      }},
-    ],
-    "drupal-create-article": [
-      { role: "user", content: { type: "text", text:
-        `I need to create a new article ${site} about: ${topic}\n\n` +
-        "Please:\n" +
-        "1. Call drupal_list_content_types to confirm \"article\" exists and check its fields.\n" +
-        "2. Call drupal_get_entity_schema for node/article to see all available fields.\n" +
-        "3. Call drupal_list_vocabularies and drupal_get_taxonomy_terms for relevant vocabularies.\n" +
-        "4. Draft the article — title, body (well-structured HTML), summary, and meta description.\n" +
-        "5. Suggest appropriate taxonomy tags.\n" +
-        "6. Call drupal_create_node with status: false (draft) and show me the result.\n" +
-        "7. Ask me to review before publishing."
-      }},
-    ],
-    "drupal-seo-fix": [
-      { role: "user", content: { type: "text", text:
-        `Please find and fix SEO issues in "${type}" content ${site}.\n\n` +
-        "1. Call drupal_report_seo_audit to identify all issues.\n" +
-        "2. For nodes missing meta descriptions: generate appropriate descriptions (max 160 chars) and update them.\n" +
-        "3. For thin content (under 300 words): flag for editorial review — do not auto-expand.\n" +
-        "4. For title length issues: suggest better titles but ask before updating.\n" +
-        "5. Report what was fixed, what needs human review, and any patterns you noticed."
-      }},
-    ],
-    "drupal-user-cleanup": [
-      { role: "user", content: { type: "text", text:
-        `Please audit user accounts ${site} and recommend cleanup actions.\n\n` +
-        "1. Call drupal_report_user_activity to identify inactive and never-logged-in accounts.\n" +
-        "2. Call drupal_list_users with no filter to get the full list.\n" +
-        "3. Call drupal_list_roles to see all available roles.\n" +
-        "4. Identify: (a) accounts inactive 90+ days, (b) never-logged-in accounts, (c) accounts with admin roles that look like test/temp accounts.\n" +
-        "5. For each category, recommend action (block, delete, or keep) with reasoning.\n" +
-        "6. Ask for approval before making any changes."
-      }},
-    ],
-    "drupal-full-audit": [
-      { role: "user", content: { type: "text", text:
-        `Please run a full site-health audit ${site} and turn it into a prioritized action plan.\n\n` +
-        `1. Call drupal_audit_site_health (type: "${type}") for the scored dashboard and overall grade.\n` +
-        "2. For any section reporting high-severity findings, drill in with the matching tool for detail:\n" +
-        "   - links/404: drupal_report_404_log, drupal_report_redirect_health, drupal_report_broken_links (checkLive only with approval).\n" +
-        "   - config: drupal_audit_config_best_practices, drupal_report_module_audit, drupal_report_permission_audit.\n" +
-        "   - content: drupal_report_pii_exposure, drupal_report_duplicate_content, drupal_report_readability.\n" +
-        "3. For sections reported 'unavailable', note what (server-tool bridge or drush) would enable them — do not treat unavailable as 'passing'.\n" +
-        "4. Synthesize a prioritized plan: (a) high-severity/security fixes first, (b) content-quality improvements, (c) process recommendations.\n" +
-        "5. Present counts, severity, and specific node/config references; propose redirects for the top 404s. Ask before making any changes."
-      }},
-    ],
-  };
-
-  return new Map(Object.entries(prompts)).get(name) ?? [{ role: "user", content: { type: "text", text: `Run the ${name} workflow ${site}.` } }];
+  const workflow = builtinWorkflows.find((item) => item.name === name);
+  if (workflow) return renderWorkflowMessages(workflow, args);
+  const site = args?.site ? `on the "${args.site}" site` : "on the default site";
+  return [{ role: "user", content: { type: "text", text: `Run the ${name} workflow ${site}.` } }];
 }
 
 // ---------------------------------------------------------------------------
@@ -320,6 +231,12 @@ const buildConnectorServer = createConnectorServerFactory({
     workflowNames: WORKFLOW_PROMPT_NAMES,
     workflowMessages: getPromptMessages,
     definitionsByName,
+    extraWorkflows: (tools, taken) => {
+      const loaded = loadWorkflows(moduleWorkflowProviders(listResolvableSiteConfigs()), { tools, taken });
+      replaceModuleWorkflows(loaded);
+      return loaded;
+    },
+    extraWorkflowMessages: renderWorkflowMessages,
   }),
 });
 

package/src/lib/governance.js

@@ -23,6 +23,9 @@ import { DIAGNOSTIC_TOOLS } from "./principal.js";
 /** How long a passing verification stays fresh before it must be re-proven. */
 export const OK_TTL_MS = 60_000;
 
+/** Readiness GET abort timeout. Matches Drupal/Drush outbound HTTP. */
+export const READINESS_TIMEOUT_MS = 30_000;
+
 /** How long a failed verification is held before the next attempt re-checks. */
 export const FAIL_TTL_MS = 5_000;
 
@@ -81,7 +84,7 @@ export async function verifySourceGovernance(site, { force = false } = {}) {
 }
 
 /**
- * One authenticated readiness probe; maps every outcome to {ok, reason}.
+ * One authenticated readiness probe; maps every outcome (including abort) to {ok, reason}.
  * @param {object} site Resolved site config.
  * @returns {Promise<{ok: boolean, reason: string|null, checkedAt: number}>}
  */
@@ -104,7 +107,11 @@ async function probeReadiness(site) {
 
   let res;
   try {
-    res = await fetch(`${site.baseUrl}/drupal-mcp/readiness`, { method: "GET", headers });
+    res = await fetch(`${site.baseUrl}/drupal-mcp/readiness`, {
+      method: "GET",
+      headers,
+      signal: AbortSignal.timeout(READINESS_TIMEOUT_MS),
+    });
   } catch {
     // Network detail (addresses, DNS text) is deliberately not propagated.
     return { ok: false, reason: "sentinel_unreachable", checkedAt };

package/src/lib/oauth.js

@@ -15,6 +15,9 @@ import fetch from "node-fetch";
 /** Re-acquire this many ms before the stated expiry to absorb clock skew. */
 const EXPIRY_SKEW_MS = 60_000;
 
+/** Token-endpoint abort timeout. Matches Drupal/Drush outbound HTTP. */
+export const OAUTH_TOKEN_TIMEOUT_MS = 30_000;
+
 /**
  * Per-site token cache, keyed by site._name. A value is either a resolved
  * { token, expiresAt, refreshToken } entry or an in-flight Promise of one
@@ -67,20 +70,31 @@ function buildBody(oauth, useRefresh, refreshToken) {
  * @param {boolean} useRefresh Whether to use the refresh_token grant.
  * @param {?string} refreshToken Refresh token for the refresh grant.
  * @returns {Promise<{token: string, expiresAt: number, refreshToken: ?string}>}
- * @throws {OAuthError} on a non-2xx response or a missing access_token.
+ * @throws {OAuthError} on a non-2xx response, a missing access_token, or a timeout.
  */
 async function requestToken(site, useRefresh, refreshToken) {
   const { oauth } = site;
   const url = `${site.baseUrl}${oauth.tokenUrl || "/oauth/token"}`;
 
-  const res = await fetch(url, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/x-www-form-urlencoded",
-      Accept: "application/json",
-    },
-    body: buildBody(oauth, useRefresh, refreshToken),
-  });
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: buildBody(oauth, useRefresh, refreshToken),
+      signal: AbortSignal.timeout(OAUTH_TOKEN_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (err?.name === "AbortError" || err?.name === "TimeoutError") {
+      throw new OAuthError(
+        `OAuth token request to ${site._name} timed out after ${OAUTH_TOKEN_TIMEOUT_MS / 1000}s.`
+      );
+    }
+    throw err;
+  }
 
   if (!res.ok) {
     throw new OAuthError(

package/src/lib/principal.js

@@ -17,6 +17,7 @@ import { getDefaultSiteName, getInboundGrants } from "./config.js";
 import { inferOperation } from "./operations.js";
 import { POLICY_DIGEST } from "./policy-promotion.js";
 import { resolveSecurityConfig, SecurityError } from "./security.js";
+import { lookupWorkflow } from "./workflow-prompts.js";
 
 const identityStore = new AsyncLocalStorage();
 
@@ -515,6 +516,19 @@ export function filterPromptsByPrincipal(prompts, identity, visibleTools) {
   if (!identity) return prompts;
   const visible = new Set((visibleTools ?? []).map((tool) => tool.name));
   return prompts.filter((prompt) => {
+    const wf = lookupWorkflow(prompt.name);
+    if (wf) {
+      if (wf.readOnly) {
+        if (!principalHasScope(identity, "mcp_read")) return false;
+      } else if (!principalHasScope(identity, "mcp_write")) {
+        return false;
+      }
+      if (!wf.builtin && Array.isArray(wf.publicTools) &&
+          !wf.publicTools.every((name) => visible.has(name))) {
+        return false;
+      }
+      return true;
+    }
     if (WRITE_WORKFLOW_PROMPTS.has(prompt.name)) {
       return principalHasScope(identity, "mcp_write");
     }

package/src/lib/server-tools.js

@@ -139,6 +139,12 @@ export async function callGovernedServerTool(site, binding, args = {}) {
 /** MCP protocol version advertised on the handshake and every subsequent POST. */
 const MCP_PROTOCOL_VERSION = "2025-06-18";
 
+/** MCP server-tool POST timeout. Handshake, catalog, and tools/call share this. */
+export const SERVER_TOOL_TIMEOUT_MS = 15_000;
+
+/** Default MCP response body cap (bytes). Caller `maxBytes` overrides. */
+export const SERVER_TOOL_MAX_BYTES = 262_144;
+
 // Monotonic JSON-RPC request id. A simple counter keeps ids unique per process
 // without relying on Math.random()/Date.now().
 let rpcId = 0;
@@ -337,8 +343,8 @@ async function initializeSession(site, endpoint, key) {
       method: "POST",
       headers: await baseHeaders(site, null),
       body: JSON.stringify(payload),
-      size: 262144,
-      signal: AbortSignal.timeout(15000),
+      size: SERVER_TOOL_MAX_BYTES,
+      signal: AbortSignal.timeout(SERVER_TOOL_TIMEOUT_MS),
     });
 
   let res = await post();
@@ -374,8 +380,8 @@ async function initializeSession(site, endpoint, key) {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
       body: JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }),
-      size: 262144,
-      signal: AbortSignal.timeout(15000),
+      size: SERVER_TOOL_MAX_BYTES,
+      signal: AbortSignal.timeout(SERVER_TOOL_TIMEOUT_MS),
     });
   } catch {
     // Notification is advisory; proceed with the established session.
@@ -432,11 +438,11 @@ export async function callServerTool(site, toolName, args = {}, options = {}) {
 /** Fetch one page of the authenticated module tool catalog. */
 export async function listServerTools(site, cursor) {
   return requestServerTool(site, "tools/list", cursor === undefined ? {} : { cursor }, {
-    maxBytes: 262144, preserveErrors: true,
+    maxBytes: SERVER_TOOL_MAX_BYTES, preserveErrors: true,
   });
 }
 
-/** Shared bounded MCP request transport; retries only explicit auth/session rejection. */
+/** Shared bounded MCP request transport; size + abort are always attached. */
 async function requestServerTool(site, method, params, options) {
   const toolName = params.name ?? method;
   const endpoint = resolveEndpoint(site);
@@ -463,7 +469,8 @@ async function requestServerTool(site, method, params, options) {
       method: "POST",
       headers: await baseHeaders(site, sessionId),
       body: JSON.stringify(payload),
-      ...(options.maxBytes ? { size: options.maxBytes, signal: AbortSignal.timeout(15000) } : {}),
+      size: options.maxBytes ?? SERVER_TOOL_MAX_BYTES,
+      signal: AbortSignal.timeout(SERVER_TOOL_TIMEOUT_MS),
     });
     const { body, rawText } = await readBody(res);
 

package/src/lib/tool-prompts.js

@@ -239,10 +239,15 @@ export function getToolPromptMessages(promptName, args = {}, definitionsByName)
  * @param {Set<string>} options.workflowNames - Names of the hand-authored workflow prompts.
  * @param {(name: string, args: object) => Array<object>} options.workflowMessages
  * @param {Map<string,object>} options.definitionsByName - Built-in tool name → definition.
+ * @param {(tools: Array<object>, taken: Set<string>) => object[]} [options.extraWorkflows]
+ *   Module-owned workflows visible for this request. Each item has name,
+ *   description, arguments, and is renderable by extraWorkflowMessages.
+ * @param {(workflow: object, args: object) => Array<object>} [options.extraWorkflowMessages]
  * @returns {{definitions: Array<object>, list: Function, describe: Function, get: Function}}
  */
 export function createPromptSurface({
   staticPrompts, discover, filter, workflowNames, workflowMessages, definitionsByName,
+  extraWorkflows, extraWorkflowMessages,
 }) {
   const get = (name, args) => workflowNames.has(name)
     ? workflowMessages(name, args)
@@ -251,11 +256,22 @@ export function createPromptSurface({
   async function visible() {
     const tools = await discover();
     const taken = new Set(staticPrompts.map((prompt) => prompt.name));
+    const extra = extraWorkflows ? extraWorkflows(tools, taken) : [];
+    for (const workflow of extra) taken.add(workflow.name);
     // A reserved module name cannot match a built-in, but never let a remote
     // catalog shadow a static prompt if that invariant is ever broken.
     const moduleDefs = tools.filter((tool) =>
       isModuleDefinition(tool) && !taken.has(toolNameToPromptName(tool.name)));
-    return { prompts: [...filter(staticPrompts, tools), ...buildToolPrompts(moduleDefs)], moduleDefs };
+    const extraPrompts = extra.map((workflow) => ({
+      name: workflow.name,
+      description: workflow.description,
+      arguments: workflow.arguments,
+    }));
+    return {
+      prompts: [...filter([...staticPrompts, ...extraPrompts], tools), ...buildToolPrompts(moduleDefs)],
+      moduleDefs,
+      extra,
+    };
   }
 
   return {
@@ -264,14 +280,21 @@ export function createPromptSurface({
     list: async () => (await visible()).prompts,
     /** Resolve one prompt, or null when it is not visible to this request. */
     async describe(name, args = {}) {
-      const { prompts, moduleDefs } = await visible();
+      const { prompts, moduleDefs, extra } = await visible();
       const known = prompts.find((prompt) => prompt.name === name);
       if (!known) return null;
       const live = moduleDefs.find((def) => toolNameToPromptName(def.name) === name);
-      const messages = live
-        ? getToolPromptMessages(name, args, new Map([[live.name, live]]))
-        : get(name, args);
-      return { description: known.description, messages };
+      if (live) {
+        return {
+          description: known.description,
+          messages: getToolPromptMessages(name, args, new Map([[live.name, live]])),
+        };
+      }
+      const workflow = extra.find((item) => item.name === name);
+      if (workflow && extraWorkflowMessages) {
+        return { description: known.description, messages: extraWorkflowMessages(workflow, args) };
+      }
+      return { description: known.description, messages: get(name, args) };
     },
   };
 }

package/src/lib/workflow-prompts.js

@@ -0,0 +1,348 @@
+/**
+ * Module-owned and built-in workflow prompts (#333).
+ *
+ * A workflow is a definition (id, tools, instructions) from a provider. The
+ * loader validates, bounds, and filters. It does not call tools. See
+ * docs/module-workflows.md.
+ */
+
+import { sourceText, toolNameToPromptName } from "./tool-prompts.js";
+
+const ID_RE = /^[a-z][a-z0-9_]{0,47}$/;
+const ARG_RE = /^[a-z][a-z0-9_]{0,47}$/;
+const MAX_DESCRIPTION = 1024;
+const MAX_INSTRUCTIONS = 8192;
+const MAX_ARG_VALUE = 200;
+const MAX_WORKFLOWS = 64;
+const MAX_TOOLS = 32;
+const MAX_ARGUMENTS = 16;
+const WRITE_EPILOGUE = "Module writes are not retried.";
+
+/**
+ * Public MCP prompt name for a module workflow.
+ *
+ * @param {string} namespace
+ * @param {string} id
+ * @returns {string}
+ */
+export function workflowPromptName(namespace, id) {
+  return `drupal-${String(namespace).replace(/_/g, "-")}-${String(id).replace(/_/g, "-")}`;
+}
+
+/**
+ * Instruction text safe to hand to a model: no heading, no system: prefix.
+ *
+ * @param {*} value
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function sanitizeInstructions(value, limit = MAX_INSTRUCTIONS) {
+  return String(value ?? "")
+    .replace(/\r/g, "")
+    .replace(/^\s*#{1,6}\s+/gm, "")
+    .replace(/^\s*system\s*:/gim, "")
+    .trim()
+    .slice(0, limit);
+}
+
+function sanitizeArgValue(value) {
+  return String(value ?? "").replace(/\s+/g, " ").trim().slice(0, MAX_ARG_VALUE);
+}
+
+/**
+ * Validate one definition. Throws if it cannot be loaded.
+ *
+ * @param {object} raw
+ * @returns {object}
+ */
+export function normalizeWorkflow(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("Workflow definition must be an object.");
+  }
+  if (!ID_RE.test(raw.id ?? "")) throw new Error("Invalid workflow id.");
+  if (typeof raw.description !== "string" || !raw.description.trim()) {
+    throw new Error("Workflow description is required.");
+  }
+  if (typeof raw.readOnly !== "boolean") throw new Error("Workflow readOnly is required.");
+  if (!Array.isArray(raw.tools) || raw.tools.length < 1 || raw.tools.length > MAX_TOOLS) {
+    throw new Error("Workflow tools must be a non-empty list.");
+  }
+  if (raw.tools.some((alias) => !ID_RE.test(alias ?? ""))) {
+    throw new Error("Invalid workflow tool alias.");
+  }
+  if (new Set(raw.tools).size !== raw.tools.length) {
+    throw new Error("Workflow tools must be unique.");
+  }
+  if (typeof raw.instructions !== "string" || !raw.instructions.trim()) {
+    throw new Error("Workflow instructions are required.");
+  }
+  const args = Array.isArray(raw.arguments) ? raw.arguments : [];
+  if (args.length > MAX_ARGUMENTS) throw new Error("Too many workflow arguments.");
+  const arguments_ = [];
+  for (const arg of args) {
+    if (!arg || !ARG_RE.test(arg.name ?? "") || typeof arg.description !== "string") {
+      throw new Error("Invalid workflow argument.");
+    }
+    arguments_.push({
+      name: arg.name,
+      description: sourceText(arg.description),
+      required: Boolean(arg.required),
+    });
+  }
+  const placeholders = [...raw.instructions.matchAll(/\{tool:([a-z][a-z0-9_]{0,47})\}/g)].map((m) => m[1]);
+  for (const alias of placeholders) {
+    if (!raw.tools.includes(alias)) {
+      throw new Error("Workflow instructions name a tool that is not in tools.");
+    }
+  }
+  return {
+    id: raw.id,
+    description: sourceText(raw.description),
+    readOnly: raw.readOnly,
+    tools: [...raw.tools],
+    arguments: arguments_,
+    instructions: sanitizeInstructions(raw.instructions),
+    name: typeof raw.name === "string" && raw.name ? raw.name : undefined,
+  };
+}
+
+/**
+ * @param {object} def
+ * @param {string} namespace
+ * @returns {string}
+ */
+export function resolvedName(def, namespace) {
+  return def.name || workflowPromptName(namespace, def.id);
+}
+
+/**
+ * Map a local alias to the public module tool name using the live tool list.
+ *
+ * @param {string} namespace
+ * @param {string} alias
+ * @param {Array<{name: string}>} tools
+ * @returns {string|null}
+ */
+export function publicToolName(namespace, alias, tools) {
+  const suffix = `_${namespace}__${alias}`;
+  const found = (tools ?? []).filter((tool) =>
+    typeof tool?.name === "string" &&
+    tool.name.startsWith("drupal_module_") &&
+    tool.name.endsWith(suffix));
+  return found.length === 1 ? found[0].name : null;
+}
+
+/**
+ * Whether every named tool is visible. Built-in public names must match
+ * exactly; module aliases resolve through {@link publicToolName}.
+ *
+ * @param {object} def
+ * @param {string} namespace
+ * @param {Array<{name: string}>} tools
+ * @param {{builtin?: boolean}} [opts]
+ * @returns {string[]|null} Public names, or null when any tool is missing.
+ */
+export function resolveToolNames(def, namespace, tools, opts = {}) {
+  const visible = new Set((tools ?? []).map((tool) => tool.name));
+  const names = [];
+  for (const alias of def.tools) {
+    const publicName = opts.builtin
+      ? (visible.has(alias) ? alias : null)
+      : publicToolName(namespace, alias, tools);
+    if (!publicName) return null;
+    names.push(publicName);
+  }
+  return names;
+}
+
+/**
+ * Load workflows from providers. Each provider is
+ * `{ id, namespace, builtin?, workflows }` or a function returning that.
+ *
+ * Two unrelated providers are the intended test shape: a CRM-like catalog and
+ * an intake-like catalog must not leak into each other.
+ *
+ * @param {Array<object|Function>} providers
+ * @param {object} [context]
+ * @param {Array<{name: string}>} [context.tools]
+ * @param {Set<string>} [context.taken]
+ * @returns {object[]} Loaded, visible workflows.
+ */
+export function loadWorkflows(providers, context = {}) {
+  const tools = context.tools ?? [];
+  const taken = new Set(context.taken ?? []);
+  const out = [];
+  for (const rawProvider of providers) {
+    const provider = typeof rawProvider === "function" ? rawProvider() : rawProvider;
+    if (!provider || typeof provider.namespace !== "string") continue;
+    if (!provider.builtin && !/^[a-z][a-z0-9_]{0,23}$/.test(provider.namespace ?? "")) {
+      continue;
+    }
+    const list = Array.isArray(provider.workflows) ? provider.workflows : [];
+    let n = 0;
+    for (const raw of list) {
+      if (n >= MAX_WORKFLOWS) break;
+      let def;
+      try {
+        def = normalizeWorkflow(raw);
+      } catch {
+        continue;
+      }
+      n += 1;
+      const name = resolvedName(def, provider.namespace);
+      if (taken.has(name) || (!provider.builtin && name !== workflowPromptName(provider.namespace, def.id))) {
+        continue;
+      }
+      const publicNames = resolveToolNames(def, provider.namespace, tools, { builtin: Boolean(provider.builtin) });
+      if (!publicNames) continue;
+      taken.add(name);
+      out.push({
+        ...def,
+        name,
+        namespace: provider.namespace,
+        builtin: Boolean(provider.builtin),
+        publicTools: publicNames,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * MCP prompt descriptor (no internal fields).
+ *
+ * @param {object} workflow
+ * @returns {object}
+ */
+export function toPromptDescriptor(workflow) {
+  return {
+    name: workflow.name,
+    description: workflow.description,
+    arguments: workflow.arguments.map((arg) => ({
+      name: arg.name,
+      description: arg.description,
+      required: arg.required,
+    })),
+  };
+}
+
+function builtinArgValues(args) {
+  const site = sanitizeArgValue(args?.site);
+  return {
+    site_phrase: site ? `on the "${site}" site` : "on the default site",
+    type: sanitizeArgValue(args?.type) || "article",
+    topic: sanitizeArgValue(args?.topic) || "the requested topic",
+    site,
+  };
+}
+
+/**
+ * Render MCP messages for a loaded workflow.
+ *
+ * @param {object} workflow
+ * @param {object} [args]
+ * @returns {Array<object>}
+ */
+export function renderWorkflowMessages(workflow, args = {}) {
+  const publicTools = [...(workflow.publicTools ?? [])];
+  const toolMap = new Map();
+  workflow.tools.forEach((alias, index) => {
+    toolMap.set(alias, publicTools.at(index));
+  });
+  const argMap = new Map(Object.entries(builtinArgValues(args)));
+  for (const arg of workflow.arguments) {
+    if (arg.name !== "site_phrase" && Object.hasOwn(args, arg.name)) {
+      argMap.set(arg.name, sanitizeArgValue(args[arg.name]));
+    }
+  }
+  let text = workflow.instructions.replace(/\{tool:([a-z][a-z0-9_]{0,47})\}/g, (_, alias) => {
+    return toolMap.get(alias) || `{tool:${alias}}`;
+  });
+  text = text.replace(/\{arg:([a-z][a-z0-9_]{0,47})\}/g, (_, name) => argMap.get(name) ?? "");
+  if (!workflow.readOnly) {
+    text = `${text}\n${WRITE_EPILOGUE}`;
+  }
+  return [{ role: "user", content: { type: "text", text } }];
+}
+
+/**
+ * Provider from site `serverTools.modules.workflows` maps.
+ *
+ * @param {Array<object>} sites
+ * @returns {Array<object>}
+ */
+export function moduleWorkflowProviders(sites) {
+  const providers = [];
+  for (const site of sites ?? []) {
+    const modules = site.serverTools?.modules;
+    if (!modules?.namespace || !modules.workflows || typeof modules.workflows !== "object") continue;
+    const workflows = [];
+    for (const [id, body] of Object.entries(modules.workflows)) {
+      if (id.startsWith("_") || !body || typeof body !== "object") continue;
+      workflows.push({ ...body, id: body.id ?? id });
+    }
+    providers.push({
+      id: `config:${modules.namespace}`,
+      namespace: modules.namespace,
+      workflows,
+    });
+  }
+  return providers;
+}
+
+const INDEX = new Map();
+const MODULE_KEYS = new Set();
+
+/**
+ * Register built-in workflows for principal filtering.
+ *
+ * @param {object[]} workflows
+ */
+export function registerBuiltinWorkflows(workflows) {
+  for (const wf of workflows ?? []) INDEX.set(wf.name, wf);
+}
+
+/**
+ * Replace the module-owned slice of the workflow index (per request).
+ *
+ * @param {object[]} workflows
+ */
+export function replaceModuleWorkflows(workflows) {
+  for (const key of MODULE_KEYS) INDEX.delete(key);
+  MODULE_KEYS.clear();
+  for (const wf of workflows ?? []) {
+    INDEX.set(wf.name, wf);
+    MODULE_KEYS.add(wf.name);
+  }
+}
+
+/**
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+export function lookupWorkflow(name) {
+  return INDEX.get(name);
+}
+
+/**
+ * Index used by tests.
+ *
+ * @param {object[]} workflows
+ * @returns {Map<string, {readOnly: boolean, builtin: boolean, publicTools: string[]}>}
+ */
+export function workflowIndex(workflows) {
+  return new Map((workflows ?? []).map((wf) => [wf.name, {
+    readOnly: wf.readOnly,
+    builtin: wf.builtin,
+    publicTools: wf.publicTools,
+  }]));
+}
+
+export const WORKFLOW_LIMITS = {
+  MAX_DESCRIPTION,
+  MAX_INSTRUCTIONS,
+  MAX_WORKFLOWS,
+};
+
+// Re-export for callers that already import tool prompt hyphenation.
+export { toolNameToPromptName };

package/src/lib/workflows/builtin.js

@@ -0,0 +1,134 @@
+/**
+ * Connector-authored workflow definitions (#333).
+ *
+ * Public names and steps match the previous hand-written prompts in
+ * src/index.js. They go through the same loader as module workflows.
+ */
+
+const SITE = { name: "site", description: "Named site (omit for default)", required: false };
+
+export const builtinWorkflowProvider = {
+  id: "builtin",
+  namespace: "builtin",
+  builtin: true,
+  workflows: [
+    {
+      id: "content_audit",
+      name: "drupal-content-audit",
+      description: "Walk through a full content audit: inventory, staleness, SEO gaps, accessibility issues, and recommendations.",
+      readOnly: true,
+      tools: [
+        "drupal_report_content_summary",
+        "drupal_report_stale_content",
+        "drupal_report_field_completeness",
+        "drupal_report_seo_meta_coverage",
+        "drupal_report_seo_audit",
+        "drupal_report_accessibility_audit",
+      ],
+      arguments: [SITE],
+      instructions:
+        "Please run a comprehensive content audit {arg:site_phrase}. Do not assume any particular content type exists — every site has a different model, so discover it first and audit the types this site actually has.\n" +
+        "1. Call {tool:drupal_report_content_summary} for the full inventory. Its byContentType list is the set of content types to audit — derive the types from it; never assume a fixed type such as \"article\".\n" +
+        "2. For each content type that has nodes, call {tool:drupal_report_stale_content} (days: 180).\n" +
+        "3. For each content type that has nodes, call {tool:drupal_report_field_completeness}.\n" +
+        "4. For each content type with published nodes, check SEO: prefer {tool:drupal_report_seo_meta_coverage} (it reads the site's actual meta field rather than assuming one) and use {tool:drupal_report_seo_audit} for title-length and thin-content checks.\n" +
+        "5. For each content type with published nodes, call {tool:drupal_report_accessibility_audit}.\n" +
+        "6. For any content type reporting zero nodes, skip its per-type scans and record it as empty — an empty type is not a clean one.\n" +
+        "7. Synthesize findings into: (a) immediate actions, (b) medium-term improvements, (c) process recommendations.\n" +
+        "Present results as a structured report with counts, severity, and specific node links where possible. State which content types were scanned so an empty or unexpected model cannot be mistaken for a clean audit.",
+    },
+    {
+      id: "create_article",
+      name: "drupal-create-article",
+      description: "Guided workflow to research, draft, and publish an article node with all fields, tags, and metadata.",
+      readOnly: false,
+      tools: [
+        "drupal_list_content_types",
+        "drupal_get_entity_schema",
+        "drupal_list_vocabularies",
+        "drupal_get_taxonomy_terms",
+        "drupal_create_node",
+      ],
+      arguments: [
+        SITE,
+        { name: "topic", description: "Article topic/brief", required: true },
+      ],
+      instructions:
+        "I need to create a new article {arg:site_phrase} about: {arg:topic}\n\n" +
+        "Please:\n" +
+        "1. Call {tool:drupal_list_content_types} to confirm \"article\" exists and check its fields.\n" +
+        "2. Call {tool:drupal_get_entity_schema} for node/article to see all available fields.\n" +
+        "3. Call {tool:drupal_list_vocabularies} and {tool:drupal_get_taxonomy_terms} for relevant vocabularies.\n" +
+        "4. Draft the article — title, body (well-structured HTML), summary, and meta description.\n" +
+        "5. Suggest appropriate taxonomy tags.\n" +
+        "6. Call {tool:drupal_create_node} with status: false (draft) and show me the result.\n" +
+        "7. Ask me to review before publishing.",
+    },
+    {
+      id: "seo_fix",
+      name: "drupal-seo-fix",
+      description: "Find SEO gaps in content (missing meta descriptions, thin content, title issues) and fix them interactively.",
+      readOnly: false,
+      tools: ["drupal_report_seo_audit"],
+      arguments: [
+        SITE,
+        { name: "type", description: "Content type to scan", required: false },
+      ],
+      instructions:
+        "Please find and fix SEO issues in \"{arg:type}\" content {arg:site_phrase}.\n\n" +
+        "1. Call {tool:drupal_report_seo_audit} to identify all issues.\n" +
+        "2. For nodes missing meta descriptions: generate appropriate descriptions (max 160 chars) and update them.\n" +
+        "3. For thin content (under 300 words): flag for editorial review — do not auto-expand.\n" +
+        "4. For title length issues: suggest better titles but ask before updating.\n" +
+        "5. Report what was fixed, what needs human review, and any patterns you noticed.",
+    },
+    {
+      id: "user_cleanup",
+      name: "drupal-user-cleanup",
+      description: "Identify inactive, never-logged-in, or overly permissioned user accounts and take action.",
+      readOnly: false,
+      tools: ["drupal_report_user_activity", "drupal_list_users", "drupal_list_roles"],
+      arguments: [SITE],
+      instructions:
+        "Please audit user accounts {arg:site_phrase} and recommend cleanup actions.\n\n" +
+        "1. Call {tool:drupal_report_user_activity} to identify inactive and never-logged-in accounts.\n" +
+        "2. Call {tool:drupal_list_users} with no filter to get the full list.\n" +
+        "3. Call {tool:drupal_list_roles} to see all available roles.\n" +
+        "4. Identify: (a) accounts inactive 90+ days, (b) never-logged-in accounts, (c) accounts with admin roles that look like test/temp accounts.\n" +
+        "5. For each category, recommend action (block, delete, or keep) with reasoning.\n" +
+        "6. Ask for approval before making any changes.",
+    },
+    {
+      id: "full_audit",
+      name: "drupal-full-audit",
+      description: "Run a full site-health audit — content, link/404 integrity, and configuration posture — and turn the scored dashboard into a prioritized action plan.",
+      readOnly: true,
+      tools: [
+        "drupal_audit_site_health",
+        "drupal_report_404_log",
+        "drupal_report_redirect_health",
+        "drupal_report_broken_links",
+        "drupal_audit_config_best_practices",
+        "drupal_report_module_audit",
+        "drupal_report_permission_audit",
+        "drupal_report_pii_exposure",
+        "drupal_report_duplicate_content",
+        "drupal_report_readability",
+      ],
+      arguments: [
+        SITE,
+        { name: "type", description: "Primary content type to audit", required: false },
+      ],
+      instructions:
+        "Please run a full site-health audit {arg:site_phrase} and turn it into a prioritized action plan.\n\n" +
+        "1. Call {tool:drupal_audit_site_health} (type: \"{arg:type}\") for the scored dashboard and overall grade.\n" +
+        "2. For any section reporting high-severity findings, drill in with the matching tool for detail:\n" +
+        "   - links/404: {tool:drupal_report_404_log}, {tool:drupal_report_redirect_health}, {tool:drupal_report_broken_links} (checkLive only with approval).\n" +
+        "   - config: {tool:drupal_audit_config_best_practices}, {tool:drupal_report_module_audit}, {tool:drupal_report_permission_audit}.\n" +
+        "   - content: {tool:drupal_report_pii_exposure}, {tool:drupal_report_duplicate_content}, {tool:drupal_report_readability}.\n" +
+        "3. For sections reported 'unavailable', note what (server-tool bridge or drush) would enable them — do not treat unavailable as 'passing'.\n" +
+        "4. Synthesize a prioritized plan: (a) high-severity/security fixes first, (b) content-quality improvements, (c) process recommendations.\n" +
+        "5. Present counts, severity, and specific node/config references; propose redirects for the top 404s. Ask before making any changes.",
+    },
+  ],
+};