@ezmodo/mcp-server 0.14.4 → 0.18.0

package/handlers/unmapped-paths.js

@@ -0,0 +1,60 @@
+/**
+ * Unmapped code path handlers (E-258 #2756)
+ *
+ * Thin wrappers over /api/mcp/v1/unmapped-paths. Dispatch and validation live
+ * server-side in core/unmappedpaths.Service; these only shape the arguments.
+ */
+
+import { callZephlyAPI } from '../lib/http-client.js';
+
+/**
+ * List a project's unmapped paths, pending by default.
+ */
+export async function listUnmappedPaths({ projectId, status }) {
+  if (!projectId) {
+    throw new Error('projectId is required');
+  }
+  const params = { projectId };
+  if (status) params.status = status;
+  return callZephlyAPI('mcpListUnmappedPaths', params);
+}
+
+/**
+ * Dispatch resolve_unmapped actions.
+ */
+export async function resolveUnmapped(args) {
+  const { action, ...params } = args;
+  switch (action) {
+  case 'reconcile': return reconcileUnmappedPaths(params);
+  case 'assign': return assignUnmappedPath(params);
+  case 'dismiss': return dismissUnmappedPath(params);
+  default:
+    throw new Error(`Unknown action: ${action}. Expected reconcile, assign, or dismiss.`);
+  }
+}
+
+// Close every pending row an existing feature path already covers. Rows several
+// features could claim are left pending on purpose.
+async function reconcileUnmappedPaths({ projectId }) {
+  requireProject(projectId, 'reconcile');
+  return callZephlyAPI('mcpReconcileUnmappedPaths', { projectId });
+}
+
+async function assignUnmappedPath({ projectId, pathId, featureId }) {
+  requireProject(projectId, 'assign');
+  if (!pathId) throw new Error('pathId is required for assign');
+  if (!featureId) throw new Error('featureId is required for assign');
+  return callZephlyAPI('mcpAssignUnmappedPath', { projectId, pathId, featureId });
+}
+
+async function dismissUnmappedPath({ projectId, pathId }) {
+  requireProject(projectId, 'dismiss');
+  if (!pathId) throw new Error('pathId is required for dismiss');
+  return callZephlyAPI('mcpDismissUnmappedPath', { projectId, pathId });
+}
+
+function requireProject(projectId, action) {
+  if (!projectId) {
+    throw new Error(`projectId is required for ${action}`);
+  }
+}

package/lib/auto-assign.js

@@ -1,7 +1,7 @@
 /**
  * Auto-assign Utility
- * Matches task/epic content against cached tags and components
- * for automatic assignment during creation.
+ * Matches task/epic content against cached tags for automatic assignment
+ * during creation.
  */
 
 import { readConfig } from './local-cache.js';
@@ -13,20 +13,6 @@ function escapeRegex(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
-/**
- * Match components against text content using word boundary matching.
- * @param {string} text - Combined title + description
- * @param {Array} components - Array of {id, name, description}
- * @returns {Array} Matching component objects
- */
-export function matchComponents(text, components) {
-  if (!text || !components?.length) return [];
-  return components.filter((c) => {
-    const regex = new RegExp(`\\b${escapeRegex(c.name)}\\b`, 'i');
-    return regex.test(text);
-  });
-}
-
 /**
  * Match tags against text content using word boundary matching.
  * @param {string} text - Combined title + description
@@ -43,10 +29,7 @@ export function matchTags(text, tags) {
 
 /**
  * Resolve auto-assignment for a task being created.
- * Returns { matchedTags, availableComponents, organizationId } or null if no cache available.
- *
- * Components are NOT auto-assigned — agents must explicitly provide componentId.
- * This function returns available components so the handler can hint at them if needed.
+ * Returns { matchedTags, organizationId } or null if no cache available.
  *
  * @param {string} projectId - The task's project ID
  * @param {string} title - Task title
@@ -59,12 +42,10 @@ export async function resolveTaskAutoAssign(projectId, title, description) {
 
   const text = `${title || ''} ${description || ''}`.trim();
 
-  const components = config.projectId === projectId ? (config.components || []) : [];
   const tags = config.tags || [];
 
   return {
     matchedTags: text ? matchTags(text, tags) : [],
-    availableComponents: components.map((c) => ({ id: c.id, name: c.name })),
     organizationId: config.organizationId || null,
   };
 }

package/lib/autolink.js

@@ -3,7 +3,7 @@ import { callZephlyAPI } from './http-client.js';
 /**
  * Auto-linking helpers (E-225).
  *
- * The API resolves file paths to the components that own them and previews what
+ * The API resolves file paths to the features that own them and previews what
  * the autolink engine would propose. Both are read-only, so an agent can ask
  * "what does this touch?" before it creates or commits anything.
  *
@@ -14,27 +14,31 @@ import { callZephlyAPI } from './http-client.js';
  */
 
 /**
- * Resolve repo-relative file paths to the components that own them.
+ * Resolve repo-relative file paths to the features that own them through their
+ * code paths (E-258).
+ *
+ * The API's response may still carry a component `matches` array (components
+ * were retired after this server shipped); it is ignored.
  *
  * @param {object} params
  * @param {string} params.projectId
  * @param {string[]} params.paths - repo-relative paths
- * @returns {Promise<{matches: object[], unresolved: string[]}>}
+ * @returns {Promise<{features: object[], unresolved: string[]}>}
  */
-export async function resolvePathsToComponents({ projectId, paths }) {
+export async function resolvePathsToFeatures({ projectId, paths }) {
   if (!projectId || !Array.isArray(paths) || paths.length === 0) {
-    return { matches: [], unresolved: [] };
+    return { features: [], unresolved: [] };
   }
   try {
     const result = await callZephlyAPI('mcpResolvePaths', { projectId, paths });
     return {
-      matches: result?.matches || [],
+      features: result?.features || [],
       unresolved: result?.unresolved || [],
     };
   } catch {
     // An API predating E-225 has no such route. Report nothing rather than
     // surfacing a 404 the agent can do nothing about.
-    return { matches: [], unresolved: paths };
+    return { features: [], unresolved: paths };
   }
 }
 
@@ -50,7 +54,6 @@ export async function resolvePathsToComponents({ projectId, paths }) {
  * @param {string} params.subjectId
  * @param {string[]} [params.paths]
  * @param {string} [params.trigger]
- * @param {string} [params.componentId]
  * @param {string} [params.epicId]
  * @returns {Promise<{proposals: object[]}>}
  */
@@ -60,7 +63,6 @@ export async function previewEntityLinks({
   subjectId,
   paths,
   trigger,
-  componentId,
   epicId,
 }) {
   if (!subjectType || !subjectId) return { proposals: [] };
@@ -71,7 +73,6 @@ export async function previewEntityLinks({
       subjectId,
       paths,
       trigger,
-      componentId,
       epicId,
     });
     return { proposals: result?.proposals || [] };

package/lib/http-client.js

@@ -172,6 +172,12 @@ export async function callZephlyAPI(endpoint, data) {
     if (typeof error.retryable === 'boolean') {
       thrown.retryable = error.retryable;
     }
+    // Structured details, when the API sent an object rather than a sentence —
+    // a plan conflict (E-259) carries the current plan and what changed, which
+    // is exactly what the agent needs to redo its edit.
+    if (error.details && typeof error.details === 'object') {
+      thrown.details = error.details;
+    }
     throw thrown;
   }
 

package/lib/instructions.generated.js

@@ -9,6 +9,6 @@
  * __tests__/instructions.test.js fails if this drifts from the skill.
  */
 
-export const WORK_TRACKING_CORE = 'Work in this repository is tracked in EzModo, and the tools for it are on this\nMCP server. The contract, in short:\n\n1. **Create the task before you edit, not after.** A task written afterwards is\n   a changelog; a task written first is what the next session reads to find out\n   what you were doing and why.\n2. **Start the session by calling `get_current_project_context()`.** Cache the\n   `projectId`. It also returns the components, tags and `terminology` you need.\n   No `.ezmodo/config.json` means this repo is not tracked — say so rather than\n   guessing at a project.\n3. **Call `get_context` with a keyword query before creating anything.** Use\n   what comes back to write a task that names real files, endpoints and\n   patterns. A vague task is not worth the call that made it.\n4. **Name every component the work touches** via `componentIds`. A task spanning\n   web and api belongs to both. The list REPLACES the previous set on update.\n5. **Set `taskType`** — `feature` | `bug` | `testing` | `chore`. Not cosmetic:\n   `bug` feeds open-bug counts, milestone freezes gate on it, and estimation\n   weights past tasks of the same kind.\n6. **Toggle steps as you finish them**, not in a batch at the end\n   (`manage_task action:"update" toggleSteps:[...]`).\n7. **Capture knowledge the moment it happens**, not in a summary at the end:\n   `addKnowledge` with `fact` for a root cause, `decision` for a choice —\n   including what you rejected and why — `reference` for a key file or pattern,\n   `context` for progress. Be specific: file paths, function names, exact\n   errors. "Fixed a bug in the parser" helps nobody.\n8. **Already three edits in with no task?** Call `report_untracked_work` the\n   moment you notice, rather than continuing untracked.\n9. **Resuming?** `get_task` first, and read ALL of its knowledge items. That is\n   where the previous session\'s reasoning went — do not re-derive it.\n10. **Finish at `in_review`** with `completionNotes`, and do NOT call\n    `action:"complete"`. A human completes a task after verifying it.\n11. **Report what actually happened.** A task moved to `in_review` claiming work\n    that was not done is worse than no task, because the next session trusts it.\n\nRespect the project\'s `terminology`: a project can rename epics, tasks and\ncomponents, and a marketing project calls an epic a "Campaign". Write anything a\nhuman reads in those words; keep API field names (`epicId`, `taskId`) as they\nare.';
+export const WORK_TRACKING_CORE = "Work in this repository is tracked in EzModo, and the tools for it are on this\nMCP server. The contract, in short:\n\n1. **Create the task before you edit, not after.** A task written afterwards is\n   a changelog; a task written first is what the next session reads to find out\n   what you were doing and why.\n2. **Start the session by calling `get_current_project_context()`.** Cache the\n   `projectId`. It also returns the tags and `terminology` you need.\n   No `.ezmodo/config.json` means this repo is not tracked — say so rather than\n   guessing at a project.\n3. **Call `get_context` with a keyword query before creating anything.** Use\n   what comes back to write a task that names real files, endpoints and\n   patterns. A vague task is not worth the call that made it.\n4. **Link the feature the work advances** via `links: [{targetType:\"feature\",\n   targetId}]`, found with `search_features`. Code links are derived: features\n   own code paths, and the files you touch link the work to their owners.\n5. **Set `taskType`** — `feature` | `bug` | `testing` | `chore`. Not cosmetic:\n   `bug` feeds open-bug counts, milestone freezes gate on it, and estimation\n   weights past tasks of the same kind.\n6. **Toggle steps as you finish them**, not in a batch at the end\n   (`manage_task action:\"update\" toggleSteps:[...]`).\n7. **Capture knowledge the moment it happens**, not in a summary at the end:\n   `addKnowledge` with `fact` for a root cause, `decision` for a choice —\n   including what you rejected and why — `reference` for a key file or pattern,\n   `context` for progress. Be specific: file paths, function names, exact\n   errors. \"Fixed a bug in the parser\" helps nobody.\n8. **Already three edits in with no task?** Call `report_untracked_work` the\n   moment you notice, rather than continuing untracked.\n9. **Resuming?** `get_task` first, and read ALL of its knowledge items. That is\n   where the previous session's reasoning went — do not re-derive it.\n10. **Finish at `in_review`** with `completionNotes`, and do NOT call\n    `action:\"complete\"`. A human completes a task after verifying it.\n11. **Report what actually happened.** A task moved to `in_review` claiming work\n    that was not done is worse than no task, because the next session trusts it.\n\nRespect the project's `terminology`: a project can rename epics and tasks, and a\nmarketing project calls an epic a \"Campaign\". Write anything a\nhuman reads in those words; keep API field names (`epicId`, `taskId`) as they\nare.";
 
-export const WORK_TRACKING_LOCAL = 'Running against a local checkout, two more:\n\n12. **Link every commit**: `manage_task action:"link_commit"` with the full\n    40-character `sha` from `git rev-parse HEAD`. A short SHA is rejected, and\n    padding one is not a fix. Linking is also what derives component links from\n    the commit\'s files — do not link those by hand.\n13. **Pass `changedFiles`** when creating or updating a task, so the work\n    resolves to the components that own those paths.';
+export const WORK_TRACKING_LOCAL = "Running against a local checkout, two more:\n\n12. **Link every commit**: `manage_task action:\"link_commit\"` with the full\n    40-character `sha` from `git rev-parse HEAD`. A short SHA is rejected, and\n    padding one is not a fix. Linking is also what derives feature links from\n    the commit's files — do not link those by hand.\n13. **Pass `changedFiles`** when creating or updating a task, so the work\n    resolves to the features that own those paths.";

package/lib/local-cache.js

@@ -1,6 +1,6 @@
 /**
  * Local Cache Utility
- * Reads and writes the project config.json cache for tags and components.
+ * Reads and writes the project config.json cache for tags.
  * Looks in `.ezmodo/` first, falls back to legacy `.zephly/`.
  * Used by MCP handlers to avoid unnecessary API calls for frequently-read data.
  */
@@ -94,23 +94,9 @@ export async function getCachedTags() {
   return config.tags || null;
 }
 
-/**
- * Get cached components for a specific project if the cache is fresh.
- * @param {string} projectId - Only return components if they match this project
- * @returns {Promise<Array|null>} Cached components array, or null if stale/missing/wrong project
- */
-export async function getCachedComponents(projectId) {
-  const config = await readConfig();
-  if (!config) return null;
-  if (!isCacheFresh(config.lastUpdatedAt)) return null;
-  // Only return if the cached config belongs to this project
-  if (config.projectId !== projectId) return null;
-  return config.components || null;
-}
-
 /**
  * Update specific sections in the config cache. Non-fatal on failure.
- * @param {object} updates - Key-value pairs to merge into config (e.g., { tags: [...], components: [...] })
+ * @param {object} updates - Key-value pairs to merge into config (e.g., { tags: [...] })
  */
 export async function updateCacheSections(updates) {
   try {
@@ -126,7 +112,7 @@ export async function updateCacheSections(updates) {
 /**
  * Invalidate a specific cache section by removing it from config.
  * The next read will return null, triggering a fresh API call.
- * @param {string} section - 'tags' or 'components'
+ * @param {string} section - e.g. 'tags'
  */
 export async function invalidateCacheSection(section) {
   try {

package/lib/remote-tools.js

@@ -58,6 +58,7 @@ export const LOCAL_ONLY_TOOLS = Object.freeze([
 /** Tools safe to serve over the remote transport. */
 export const REMOTE_SAFE_TOOLS = Object.freeze([
   'accept_agent_suggestion',
+  'add_epic_comment',
   'configure_agent',
   'create_tasks',
   'delete_attachment',
@@ -75,6 +76,7 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'get_document',
   'get_document_template',
   'get_epic',
+  'get_epic_plan',
   'get_feature',
   'get_feature_flag',
   'get_goal',
@@ -93,8 +95,9 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'list_attachments',
   'list_catalog_items',
   'list_catalogs',
-  'list_components',
+  'list_unmapped_paths',
   'list_designs',
+  'list_epic_comments',
   'list_epics',
   'list_facts',
   'list_feature_flags',
@@ -110,7 +113,6 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'list_watched',
   'manage_access',
   'manage_catalog',
-  'manage_component',
   'manage_decision',
   'manage_design',
   'manage_document',
@@ -141,10 +143,12 @@ export const REMOTE_SAFE_TOOLS = Object.freeze([
   'resolve_concepts',
   'resolve_link_suggestions',
   'resolve_links',
+  'resolve_unmapped',
   'run_agent_now',
   'search_epics',
   'search_features',
   'search_tasks',
+  'update_epic_plan',
   'update_manifest_entries',
   'validate_manifest',
 ]);

package/lib/version.js

@@ -7,4 +7,4 @@
  *
  * Update this when bumping the version in package.json.
  */
-export const MCP_VERSION = '0.14.4';
+export const MCP_VERSION = '0.18.0';

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@ezmodo/mcp-server",
-  "version": "0.14.4",
+  "version": "0.18.0",
   "description": "MCP server for ezmodo - AI-first project management",
   "main": "index.js",
   "type": "module",
   "bin": {
-    "mcp-server": "./index.js",
-    "ezmodo-mcp-server": "./index.js",
-    "zephly-mcp-server": "./index.js",
-    "ezmodo-mcp-server-http": "./http.js"
+    "mcp-server": "index.js",
+    "ezmodo-mcp-server": "index.js",
+    "zephly-mcp-server": "index.js",
+    "ezmodo-mcp-server-http": "http.js"
   },
   "scripts": {
     "dev": "BUILD_ENV=development node index.js",

package/prompts/commands.generated.js

@@ -18,7 +18,7 @@ export const COMMAND_PROMPTS = [
       "local",
       "remote"
     ],
-    "body": "Start tracked work on: **$ARGUMENTS**\n\nFollow the work-tracking contract in this server's instructions. In short:\n\n1. `get_current_project_context()` — cache the `projectId`, note the components,\n   tags and `terminology`.\n2. `get_context` with a keyword query drawn from the request above. Read what\n   comes back before writing anything: it tells you which files exist, what\n   patterns they follow, and what the change will touch.\n3. `resolve_links` on the paths you expect to change. A component you did not\n   expect means the work is broader than the request sounds.\n4. Create the work:\n   - **Single scope** (a fix, a small feature, a config or docs change) —\n     `manage_task action:\"create\"` with `status:\"in_progress\"`, a description\n     that says why/where/how, steps that name real files, `componentIds` for\n     every component involved, and the right `taskType`.\n   - **Multi scope** (spanning areas, or a large refactor) — `manage_epic\n     action:\"create\"` with its child tasks in the same request, ordered by\n     dependency.\n\nThen report the task number and web URL and begin. Do not edit anything before\nthe task exists — a task created afterwards is a task written from memory.\n\nIf no `.ezmodo/config.json` is found, say so and stop rather than guessing at a\nproject."
+    "body": "Start tracked work on: **$ARGUMENTS**\n\nFollow the work-tracking contract in this server's instructions. In short:\n\n1. `get_current_project_context()` — cache the `projectId`, note the tags and\n   `terminology`.\n2. `get_context` with a keyword query drawn from the request above. Read what\n   comes back before writing anything: it tells you which files exist, what\n   patterns they follow, and what the change will touch.\n3. `resolve_links` on the paths you expect to change. A feature you did not\n   expect means the work is broader than the request sounds.\n4. Create the work:\n   - **Single scope** (a fix, a small feature, a config or docs change) —\n     `manage_task action:\"create\"` with `status:\"in_progress\"`, a description\n     that says why/where/how, steps that name real files, `changedFiles` for\n     the paths involved, a `links` entry for the feature it advances, and the\n     right `taskType`.\n   - **Multi scope** (spanning several parts of the codebase, or a large refactor) — `manage_epic\n     action:\"create\"` with its child tasks in the same request, ordered by\n     dependency.\n\nThen report the task number and web URL and begin. Do not edit anything before\nthe task exists — a task created afterwards is a task written from memory.\n\nIf no `.ezmodo/config.json` is found, say so and stop rather than guessing at a\nproject."
   },
   {
     "name": "resume",
@@ -47,6 +47,6 @@ export const COMMAND_PROMPTS = [
       "local",
       "remote"
     ],
-    "body": "Capture the current uncommitted work as a task.\n\nCurrent branch: run `git rev-parse --abbrev-ref HEAD` and use its output\nChanged files: run `git status --porcelain` and use its output\n\nUse `report_untracked_work` with:\n\n- `projectId` from `get_current_project_context()`\n- `title` — concise, describing what was actually done\n- `description` — what and **why**. Do not restate the branch or file list; they\n  are appended automatically as evidence.\n- `changedFiles` — the paths above\n- `branch` — as above\n- `componentIds` — resolve the changed paths with `resolve_links` rather than\n  guessing; untracked work often spans more than one area, which is part of why\n  it went untracked\n- `origin`:\n  - `discovered` — found while working on another task (set `discoveredDuringTaskId`)\n  - `scope-creep` — went beyond the active task's scope (set `discoveredDuringTaskId`)\n  - `rework` — redoing prior work\n  - `untracked` — unplanned standalone work (the default)\n\nIf there is an active task in this session, prefer `discovered` or\n`scope-creep` and link it — the discovery chain is the point of the\nclassification.\n\nThe new task comes back `in_progress` and becomes the active one. Track against\nit for the rest of the work.\n\nExtra context from the user, if any: $ARGUMENTS"
+    "body": "Capture the current uncommitted work as a task.\n\nCurrent branch: run `git rev-parse --abbrev-ref HEAD` and use its output\nChanged files: run `git status --porcelain` and use its output\n\nUse `report_untracked_work` with:\n\n- `projectId` from `get_current_project_context()`\n- `title` — concise, describing what was actually done\n- `description` — what and **why**. Do not restate the branch or file list; they\n  are appended automatically as evidence.\n- `changedFiles` — the paths above\n- `branch` — as above\n- `origin`:\n  - `discovered` — found while working on another task (set `discoveredDuringTaskId`)\n  - `scope-creep` — went beyond the active task's scope (set `discoveredDuringTaskId`)\n  - `rework` — redoing prior work\n  - `untracked` — unplanned standalone work (the default)\n\nIf there is an active task in this session, prefer `discovered` or\n`scope-creep` and link it — the discovery chain is the point of the\nclassification.\n\nThe new task comes back `in_progress` and becomes the active one. Track against\nit for the rest of the work.\n\nExtra context from the user, if any: $ARGUMENTS"
   }
 ];

package/tools/catalogs.js

@@ -80,8 +80,14 @@ export const CATALOG_TOOLS = [
     name: 'manage_catalog',
     description: 'Create, update, or delete an org-level Catalog, link/unlink it to other artifacts, ' +
       'or push a new versioned snapshot of its contents. A Catalog is a generalized, code-derived ' +
-      'catalog (kind = notifications | analytics_events | db_schema | custom); its versions are ' +
+      'catalog (kind = notifications | analytics_events | db_schema | screens | custom); its versions are ' +
       'immutable { columns, items } snapshots.\n\n' +
+      'SCREENS (E-258): each project has one kind:"screens" catalog, its UI inventory (screens and pages, ' +
+      'keyed by source path). Do not snapshot it by hand: action:"discover_screens" (projectId) lists what ' +
+      'the Context Manifest shows that the catalog lacks, and action:"import_screens" (projectId, screens, ' +
+      'optional featureId) adds them and links each to the feature. action:"sync_screens" (projectId) ' +
+      'reconciles the catalog with the manifest and re-derives the screen flow map (navigates_to edges ' +
+      'between screens); it cannot remove a hand-added screen or a human-confirmed edge.\n\n' +
       'CAPTURE-AT-BUILD (important): whenever you change the catalog\'s source of truth in code, call ' +
       'action:"snapshot" and put the source path/commit in `source`. The server is checksum-gated — ' +
       're-snapshotting unchanged content creates no new version and is a cheap no-op — so it is safe ' +
@@ -97,7 +103,7 @@ export const CATALOG_TOOLS = [
       '`go run ./cmd/dbschema-snapshot -upload -catalog-id <id>` from api/ introspects and uploads the ' +
       'whole schema without passing it through the model at all — cheaper still than a patch.\n\n' +
       'LINK, DON\'T CONTAIN: use action:"link"/"unlink" to relate a catalog to a feature, feature_flag, ' +
-      'epic, task, document, component, milestone, goal or project (e.g. link the notification catalog ' +
+      'epic, task, document, milestone, goal or project (e.g. link the notification catalog ' +
       'to its Notifications feature and the ezmodo doc that describes it).\n\n' +
       'ITEM-LEVEL LINKS (E-218): pass `itemKey` on action:"link"/"unlink" to attach the link to a SINGLE ' +
       'catalog entry instead of the whole catalog — this is how a task/epic that builds one entry records ' +
@@ -109,7 +115,8 @@ export const CATALOG_TOOLS = [
       properties: {
         action: {
           type: 'string',
-          enum: ['create', 'update', 'delete', 'link', 'unlink', 'snapshot'],
+          enum: ['create', 'update', 'delete', 'link', 'unlink', 'snapshot', 'discover_screens', 'import_screens',
+            'sync_screens'],
           description: 'Action to perform. "snapshot" pushes a new version (checksum-gated) — send a ' +
             'delta with mode:"patch" unless this is the catalog\'s first snapshot. "link"/"unlink" ' +
             'manage relates_to edges to other artifacts.',
@@ -127,10 +134,30 @@ export const CATALOG_TOOLS = [
           type: 'string',
           description: 'Catalog ID (required for update, delete, link, unlink, snapshot)',
         },
+        // --- Screens (E-258) ---
+        screens: {
+          type: 'array',
+          description: 'Screens to add for import_screens, usually taken from discover_screens.',
+          items: {
+            type: 'object',
+            properties: {
+              name: { type: 'string', description: 'Display name, e.g. "CookSessionDetailScreen"' },
+              sourcePath: { type: 'string', description: 'Repo-relative file; becomes the item key' },
+              kind: { type: 'string', enum: ['screen', 'page'], description: 'Default "screen"' },
+              route: { type: 'string', description: 'Route, for web pages' },
+              framework: { type: 'string', description: 'e.g. "nextjs", "flutter"' },
+            },
+            required: ['name', 'sourcePath'],
+          },
+        },
+        featureId: {
+          type: 'string',
+          description: 'Feature to link every imported screen to (import_screens)',
+        },
         // --- Create / update fields ---
         kind: {
           type: 'string',
-          enum: ['db_schema', 'notifications', 'analytics_events', 'custom'],
+          enum: ['db_schema', 'notifications', 'analytics_events', 'screens', 'custom'],
           description: 'What the catalog catalogs (default "custom") (create, update)',
         },
         name: {
@@ -276,7 +303,7 @@ export const CATALOG_TOOLS = [
         },
         kind: {
           type: 'string',
-          enum: ['db_schema', 'notifications', 'analytics_events', 'custom'],
+          enum: ['db_schema', 'notifications', 'analytics_events', 'screens', 'custom'],
           description: 'Filter to a single kind',
         },
         linkedType: {

package/tools/context-manifest.js

@@ -13,7 +13,7 @@ export const CONTEXT_MANIFEST_TOOLS = [
   {
     name: 'get_context',
     description:
-      'Get contextual information about any entity (project, task, epic, component, file, tag). ' +
+      'Get contextual information about any entity (project, task, epic, file, tag). ' +
       'Replaces search_project_context, get_related_files, get_project_overview, get_critical_files, ' +
       'query_project_graph, analyze_impact, get_graph_stats, analyze_project_organization. ' +
       'Use `query` for keyword search, or `entityType` + `entityId` for entity-specific context. ' +
@@ -27,7 +27,7 @@ export const CONTEXT_MANIFEST_TOOLS = [
         },
         entityType: {
           type: 'string',
-          enum: ['project', 'task', 'epic', 'component', 'file', 'tag'],
+          enum: ['project', 'task', 'epic', 'file', 'tag'],
           description: 'Type of entity to get context for',
         },
         entityId: {

package/tools/decisions.js

@@ -11,6 +11,11 @@
  * Decisions capture "why we built it this way" so the rationale survives the work
  * that produced it. A task's decision-type knowledge item can be elevated into a
  * durable Decision via promote_from_knowledge.
+ *
+ * Decisions to make (E-259): a proposed Decision asked on an epic, with a plain
+ * question, options, a recommendation and the people who should weigh in. Each
+ * of them, or their AI, adds a pick (add_input); the epic's owner or an editor
+ * decides (decide). A decision can hold tasks back until it is decided.
  */
 
 import { LINKABLE_TYPES } from './linkable-types.js';
@@ -23,17 +28,81 @@ export const DECISION_TOOLS = [
       'options, decision, consequences, status), link/unlink it to existing artifacts, mark it ' +
       'superseded by another decision, or promote a task\'s decision-type knowledge item into a ' +
       'durable Decision. Decisions are org-level and LINK to features/epics/tasks/milestones/etc., ' +
-      'they do not contain them.',
+      'they do not contain them.\n\n' +
+      'DECISIONS TO MAKE (open choices on an epic that several people weigh in on): create with ' +
+      'epicId + question + choices + recommendation + requestedFrom (the people whose view is ' +
+      'wanted; they are notified). Write the question, options and recommendation in plain ' +
+      'language a non-developer can answer. Then "add_input" records a pick (choiceId + a ' +
+      'one-line reason; your pick counts for the person whose key you use, and replaces their ' +
+      'earlier one). "decide" is for the epic\'s owner or an editor only: pass choiceId, ' +
+      'optionally decision (the answer in plain words) and rejectedReasons {choiceId: why}. ' +
+      '"hold_task" makes a task wait until the decision is made (it is blocked, and released on ' +
+      'decide); "release_task" undoes that. Do not decide on someone\'s behalf unless they asked ' +
+      'you to — add a pick instead.',
     inputSchema: {
       type: 'object',
       properties: {
         action: {
           type: 'string',
-          enum: ['create', 'update', 'delete', 'link', 'unlink', 'supersede', 'promote_from_knowledge'],
+          enum: ['create', 'update', 'delete', 'link', 'unlink', 'supersede', 'promote_from_knowledge',
+            'add_input', 'decide', 'hold_task', 'release_task'],
           description: 'Action to perform. "supersede" marks a decision as superseded by another ' +
             '(pass decisionId + supersededById). "promote_from_knowledge" elevates a task\'s ' +
             'decision-type knowledge item into a durable Decision (pass organizationId + taskId + ' +
-            'knowledgeId, optionally title + linkToType/linkToId to link it on creation).',
+            'knowledgeId, optionally title + linkToType/linkToId to link it on creation). ' +
+            '"add_input" (decisionId + choiceId + reason), "decide" (decisionId + choiceId), ' +
+            '"hold_task" / "release_task" (decisionId + taskId) are for decisions to make on an epic.',
+        },
+        // --- Decisions to make (E-259) ---
+        epicId: {
+          type: 'string',
+          description: 'Ask this decision on an epic (create). Its owner or an editor decides it; the ' +
+            'decision is scoped to the epic\'s project and linked to it.',
+        },
+        question: {
+          type: 'string',
+          description: 'The plain question to answer, e.g. "Who should review changes to the plan?" ' +
+            '(create, update)',
+        },
+        recommendation: {
+          type: 'string',
+          description: 'The recommended answer and why, in a sentence or two (create, update)',
+        },
+        choices: {
+          type: 'array',
+          items: {
+            oneOf: [
+              { type: 'string' },
+              {
+                type: 'object',
+                properties: { id: { type: 'string' }, label: { type: 'string' } },
+                required: ['label'],
+              },
+            ],
+          },
+          description: 'The options to pick from. On create, a list of plain labels. On update, the ' +
+            'full list as {id, label}: keep an option\'s id to keep the picks made for it; leave id ' +
+            'off to add one; omit an option to remove it (create, update)',
+        },
+        requestedFrom: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'User ids of the people whose view is wanted. They are notified (on update, ' +
+            'only the newly added ones) (create, update)',
+        },
+        choiceId: {
+          type: 'string',
+          description: 'An option id from the decision\'s choices, e.g. "c2" (add_input: your pick, ' +
+            'omit for "none of these" and say why in reason; decide: the chosen option)',
+        },
+        reason: {
+          type: 'string',
+          description: 'One line on why you picked it (add_input)',
+        },
+        rejectedReasons: {
+          type: 'object',
+          additionalProperties: { type: 'string' },
+          description: 'Why each option was turned down, as {choiceId: reason} (decide)',
         },
         // --- Identifiers ---
         organizationId: {
@@ -74,7 +143,9 @@ export const DECISION_TOOLS = [
         status: {
           type: 'string',
           enum: ['proposed', 'accepted', 'rejected', 'superseded', 'deprecated'],
-          description: 'Decision lifecycle status (default: "proposed") (create, update)',
+          description: 'Decision lifecycle status (default: "proposed") (create, update). For decide: ' +
+            '"accepted" (default) or "rejected" (none of the options). A decision to make on an epic ' +
+            'cannot change status through update; use decide.',
         },
         projectId: {
           type: 'string',
@@ -95,7 +166,8 @@ export const DECISION_TOOLS = [
         // --- promote_from_knowledge fields ---
         taskId: {
           type: 'string',
-          description: 'Task whose knowledge item to promote (required for promote_from_knowledge)',
+          description: 'Task whose knowledge item to promote (required for promote_from_knowledge), ' +
+            'or the task to hold back / release (hold_task, release_task)',
         },
         knowledgeId: {
           type: 'string',
@@ -121,8 +193,10 @@ export const DECISION_TOOLS = [
     name: 'get_decision',
     description: 'Retrieve a single Decision, list an organization\'s decisions, or list the decisions ' +
       'linked to a given entity (e.g. all decisions on a feature). Provide decisionId for a single ' +
-      'lookup; provide linkedType + linkedId to list decisions linked to that entity; otherwise ' +
-      'provide organizationId to list.',
+      'lookup; provide linkedType + linkedId to list decisions linked to that entity; provide ' +
+      'epicId to list the decisions to make on an epic (open ones first, each with everyone\'s ' +
+      'picks and the tasks it holds back; add status "proposed" for only the open ones); ' +
+      'otherwise provide organizationId to list.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -132,7 +206,11 @@ export const DECISION_TOOLS = [
         },
         organizationId: {
           type: 'string',
-          description: 'Organization ID (required for list, unless using linkedType + linkedId)',
+          description: 'Organization ID (required for list, unless using linkedType + linkedId or epicId)',
+        },
+        epicId: {
+          type: 'string',
+          description: 'List the decisions to make on this epic, with picks and held tasks',
         },
         linkedType: {
           type: 'string',