roadmapsmith 0.9.29 → 0.9.30

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.29",
-  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude plus the roadmapsmith status readiness surface.",
+  "version": "0.9.30",
+  "description": "Evidence-backed ROADMAP.md workflows for AI coding agents, with canonical RoadmapSmith status and maintain surfaces plus advanced sync/generate tools and legacy compatibility aliases.",
   "main": "src/index.js",
   "bin": {
     "roadmapsmith": "bin/cli.js"

package/skills/roadmap-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: roadmap-status
-description: Inspect RoadmapSmith readiness through doctor JSON and summarize the result.
+description: Inspect RoadmapSmith readiness through status JSON and summarize the result.
 ---
 
 # RoadmapSmith Status
@@ -10,8 +10,9 @@ Use this command to inspect whether the shared bundle, native host surfaces, CLI
 ## Required behavior
 
 1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js doctor --json --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js doctor --json --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith doctor --json --project-root .`. If its global shim cannot resolve `node`, use `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" doctor --json --project-root .`.
-3. Parse and summarize the JSON output in plain language.
-4. Explicitly call out missing commands or duplicate `/roadmap-sync` registration when doctor reports them.
+   - `node roadmap-skill/bin/cli.js status --json --project-root .`
+   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js status --json --project-root .` if `node` is not in PATH
+2. Otherwise prefer `roadmapsmith status --json --project-root .`. If its global shim cannot resolve `node`, use `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" status --json --project-root .`.
+3. Treat `roadmapsmith doctor --json` as compatibility-only output for existing automation, not as the primary recommendation.
+4. Parse and summarize the JSON output in plain language.
+5. Explicitly call out missing canonical commands, duplicate legacy `/roadmap-sync` registration, and any missing advanced VS Code labels as warnings rather than canonical-readiness failures.

package/skills/roadmap-update/SKILL.md

@@ -5,14 +5,14 @@ description: Apply evidence-backed checklist sync or complete one task with veri
 
 # RoadmapSmith Update
 
-Use this command when the user wants the direct sync surface without routing through the legacy `/roadmap-sync <action>` root.
+Use this command when the user wants the canonical public `update` surface without routing through the legacy `/roadmap-sync <action>` root.
 
 ## Required behavior
 
 1. Prefer the local engine inside this repository:
    - `node roadmap-skill/bin/cli.js update --project-root .`
    - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js update --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith update --project-root .`. If that global shim fails because `node` is not in PATH, run `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" update --project-root .`.
-3. Explain that `/roadmap-update` is the visible namespaced sync command, while `/roadmap-sync <action>` remains legacy compatibility.
-4. Keep the evidence-backed sync semantics unchanged: no-argument update syncs the roadmap from repository evidence; it is not a full regeneration path.
+2. Otherwise prefer `roadmapsmith update --project-root .`. If its global shim fails because `node` is not in PATH, run `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" update --project-root .`.
+3. Explain that `/roadmap-update` is the visible namespaced command for the public `update` family, while `/roadmap-sync <action>` remains deprecated compatibility only.
+4. Keep the evidence-backed refresh semantics unchanged: no-argument `update` syncs the roadmap from repository evidence, and `sync` remains the advanced CLI alias for that same mutating refresh path. It is not a full regeneration path and not an independent audit engine.
 5. To complete one task, run `roadmapsmith update --task <stable-id> --evidence "<single-line evidence>"`. It writes only after the supplied evidence validates at high confidence; use `--dry-run` to preview it.

package/skills.json

@@ -21,74 +21,74 @@
     "command": "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
     "source": "PapiScholz/roadmapsmith",
     "skill": "*",
-    "notes": "Recommended Claude Code install path for native GUI slash commands like /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-init, /roadmap-generate, /roadmap-validate, /roadmap-update, /roadmap-audit, and /roadmap-setup. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the visible readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
+    "notes": "Recommended Claude Code install path for native GUI slash commands. Canonical surfaces: /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-validate, /roadmap-update, /roadmap-setup. The public CLI update family covers both checklist refresh and verified single-task completion; sync remains the advanced alias for the mutating refresh path. Advanced surfaces: /roadmap-init, /roadmap-generate, /roadmap-audit. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the public readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
   },
   "skills": [
     {
       "name": "roadmap",
       "path": "skills/roadmap",
       "description": "Native slash palette for RoadmapSmith commands and recommended entrypoints across supported hosts.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-zero",
       "path": "skills/roadmap-zero",
       "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-maintain",
       "path": "skills/roadmap-maintain",
       "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
       "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-init",
       "path": "skills/roadmap-init",
       "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-generate",
       "path": "skills/roadmap-generate",
       "description": "Native slash entrypoint for managed roadmap updates that require --full-regen before destructive replacement.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-update",
       "path": "skills/roadmap-update",
       "description": "Native slash entrypoint for evidence-backed sync and verified single-task completion.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-sync",
       "path": "skills/roadmap-sync",
       "description": "DEPRECATED legacy compatibility root; use roadmap-maintain or roadmap-update.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-audit",
       "path": "skills/roadmap-audit",
-      "description": "Native slash entrypoint for the current sync-plus-audit workflow.",
-      "version": "0.9.29"
+      "description": "Native slash entrypoint for the advanced sync-plus-audit mutating summary workflow.",
+      "version": "0.9.30"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.29"
+      "version": "0.9.30"
     }
   ]
 }

package/src/host.js

@@ -4,7 +4,14 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 const { readTextIfExists, writeText } = require('./io');
-const { getHostNativeSkillNames, getHostNativeSlashCommands, getSlashActionSpecs } = require('./slash');
+const {
+  getAdvancedHostNativeSlashCommands,
+  getCanonicalHostNativeSlashCommands,
+  getCompatibilityHostNativeSlashCommands,
+  getHostNativeSkillNames,
+  getHostNativeSlashCommands,
+  getSlashActionSpecs
+} = require('./slash');
 
 const SUPPORTED_EDITORS = new Set(['vscode']);
 const SUPPORTED_HOSTS = new Set(['codex', 'claude']);
@@ -13,18 +20,25 @@ const REPO_ROOT = path.resolve(PACKAGE_ROOT, '..');
 const VSCODE_LAUNCHER_RELATIVE_PATH = '.vscode/roadmapsmith-launcher.js';
 const WINDOWS_TASK_WRAPPER_RELATIVE_PATH = '.vscode/roadmapsmith-task.cmd';
 const POSIX_TASK_WRAPPER_RELATIVE_PATH = '.vscode/roadmapsmith-task.sh';
-const ROADMAPSMITH_TASK_LABELS = [
+const ROADMAPSMITH_CANONICAL_TASK_LABELS = [
   'RoadmapSmith: Zero Mode',
   'RoadmapSmith: Maintain',
   'RoadmapSmith: Status',
+  'RoadmapSmith: Validate',
+  'RoadmapSmith: Update',
+  'RoadmapSmith: Refresh Setup'
+];
+const ROADMAPSMITH_ADVANCED_TASK_LABELS = [
   'RoadmapSmith: Explain Workflow',
   'RoadmapSmith: Init',
   'RoadmapSmith: Generate',
-  'RoadmapSmith: Validate',
   'RoadmapSmith: Sync',
   'RoadmapSmith: Sync Dry Run',
-  'RoadmapSmith: Sync Audit',
-  'RoadmapSmith: Refresh Setup'
+  'RoadmapSmith: Sync Audit'
+];
+const ROADMAPSMITH_TASK_LABELS = [
+  ...ROADMAPSMITH_CANONICAL_TASK_LABELS,
+  ...ROADMAPSMITH_ADVANCED_TASK_LABELS
 ];
 const CLAUDE_HOOK_COMMAND = 'node .claude/hooks/roadmap-sync.js';
 const CLAUDE_HOOK_RELATIVE_PATH = '.claude/hooks/roadmap-sync.js';
@@ -32,6 +46,9 @@ const ROADMAPSMITH_PLUGIN_NAME = 'roadmapsmith';
 const LEGACY_ROADMAP_SYNC_SKILL_NAME = 'roadmap-sync';
 const EXPECTED_NATIVE_SKILL_NAMES = Object.freeze(getHostNativeSkillNames());
 const EXPECTED_NATIVE_SLASH_COMMANDS = Object.freeze(getHostNativeSlashCommands());
+const EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS = Object.freeze(getCanonicalHostNativeSlashCommands());
+const EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS = Object.freeze(getAdvancedHostNativeSlashCommands());
+const EXPECTED_COMPATIBILITY_NATIVE_SLASH_COMMANDS = Object.freeze(getCompatibilityHostNativeSlashCommands());
 const BUNDLE_ROOT_CANDIDATES = Object.freeze([
   { kind: 'package', root: PACKAGE_ROOT },
   { kind: 'repo', root: REPO_ROOT }
@@ -294,14 +311,15 @@ function createManagedTasks() {
     createTask('zero', 'RoadmapSmith: Zero Mode', 'Run the Zero Mode interview and generate the first roadmap in one command.'),
     createTask('maintain', 'RoadmapSmith: Maintain', 'Run the preserve-first existing-repo flow: generate, sync, and audit in one command.'),
     createTask('status', 'RoadmapSmith: Status', 'Inspect readiness and learn the slash entrypoints like /roadmap, /roadmap-update, and legacy /roadmap-sync <action>.'),
+    createTask('validate', 'RoadmapSmith: Validate', 'Inspect per-task evidence status as JSON.'),
+    createTask('update', 'RoadmapSmith: Update', 'Apply evidence-backed checklist refresh or complete one task with verified evidence.'),
+    createTask('setup', 'RoadmapSmith: Refresh Setup', 'Reapply RoadmapSmith VS Code and host integration files.'),
     createTask('explain', 'RoadmapSmith: Explain Workflow', 'Explain how zero, maintain, the skill, setup, slash routing, and VS Code tasks work together.'),
     createTask('init', 'RoadmapSmith: Init', 'Create ROADMAP.md and AGENTS.md when they are missing.'),
     createTask('generate', 'RoadmapSmith: Generate', 'Update ROADMAP.md and refuse destructive replacement unless rerun with --full-regen.'),
-    createTask('validate', 'RoadmapSmith: Validate', 'Inspect per-task evidence status as JSON.'),
     createTask('sync', 'RoadmapSmith: Sync', 'Apply evidence-backed checklist sync to ROADMAP.md.'),
     createTask('sync-dry-run', 'RoadmapSmith: Sync Dry Run', 'Preview the next roadmap sync without writing files.'),
-    createTask('sync-audit', 'RoadmapSmith: Sync Audit', 'Run sync and print the post-sync mismatch summary.'),
-    createTask('setup', 'RoadmapSmith: Refresh Setup', 'Reapply RoadmapSmith VS Code and host integration files.')
+    createTask('sync-audit', 'RoadmapSmith: Sync Audit', 'Run sync and print the post-sync mismatch summary.')
   ];
 }
 
@@ -568,7 +586,7 @@ function inspectSharedBundleSurface() {
     ? skillsManifest.skills.map((skill) => skill && skill.name).filter(Boolean)
     : [];
   const availableCommands = declaredSkillNames.map((name) => `/${name}`);
-  const missingCommands = EXPECTED_NATIVE_SLASH_COMMANDS.filter((command) => !availableCommands.includes(command));
+  const missingCommands = EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS.filter((command) => !availableCommands.includes(command));
 
   return {
     kind: bundleSurface.kind,
@@ -586,7 +604,9 @@ function inspectSharedBundleSurface() {
       hasCodexPluginManifest: bundleSurface.hasCodexPluginManifest
     },
     declaredSkillNames,
-    expectedCommands: EXPECTED_NATIVE_SLASH_COMMANDS.slice(),
+    expectedCommands: EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS.slice(),
+    advancedCommands: EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS.slice(),
+    compatibilityCommands: EXPECTED_COMPATIBILITY_NATIVE_SLASH_COMMANDS.slice(),
     availableCommands,
     missingCommands
   };
@@ -635,7 +655,7 @@ function inspectCodexPluginState(projectRoot, options = {}) {
     ? options.codexCommandPath
     : findCommandPath('codex', env);
   const legacySkill = inspectLegacyRoadmapSyncSkill(options, env);
-  const expectedCommands = EXPECTED_NATIVE_SLASH_COMMANDS.slice();
+  const expectedCommands = EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS.slice();
   const missingCommands = expectedCommands.slice();
   const baseState = {
     commandPath: codexCommandPath,
@@ -708,13 +728,15 @@ function inspectCodexPluginState(projectRoot, options = {}) {
     plugin,
     marketplace,
     expectedCommands,
+    advancedCommands: EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS.slice(),
+    compatibilityCommands: EXPECTED_COMPATIBILITY_NATIVE_SLASH_COMMANDS.slice(),
     availableCommands: expectedCommands,
     missingCommands: [],
     duplicates,
-    ready: duplicates.length === 0,
+    ready: true,
     source: `${plugin.pluginId || plugin.name}${plugin.marketplaceName ? ` (${plugin.marketplaceName})` : ''}`,
     message: duplicates.length > 0
-      ? 'RoadmapSmith is installed in Codex, but /roadmap-sync is duplicated by the legacy ~/.agents/skills install.'
+      ? 'RoadmapSmith is installed in Codex. The legacy ~/.agents/skills install still duplicates /roadmap-sync, but the canonical native surface is healthy.'
       : 'RoadmapSmith is installed and enabled in Codex. Interactive slash-menu visibility still needs manual host verification.',
     legacySkill
   };
@@ -783,14 +805,23 @@ function renderVsCodeLauncher() {
     '}',
     '',
     'function getNamespacedDirectSlash(actionId) {',
-    '  return actionId === \'sync\' ? \'/roadmap-update\' : `/roadmap-${actionId}`;',
+    '  return `/roadmap-${actionId}`;',
     '}',
     '',
     'const DIRECT_HOST_NATIVE_ALIAS_TO_ACTION = Object.fromEntries(',
     '  SLASH_ACTIONS.map((action) => [getNamespacedDirectSlash(action.id), action.id])',
     ');',
     'const DIRECT_DEPRECATED_CLI_ALIAS_TO_ACTION = Object.fromEntries(',
-    '  SLASH_ACTIONS.map((action) => [`/${action.id}`, action.id])',
+    '  SLASH_ACTIONS.flatMap((action) => {',
+    '    const aliases = Array.isArray(action.aliases) ? action.aliases : [];',
+    '    return [action.id, ...aliases].map((alias) => [`/${alias}`, action.id]);',
+    '  })',
+    ');',
+    'const ACTION_ALIAS_TO_ID = Object.fromEntries(',
+    '  SLASH_ACTIONS.flatMap((action) => {',
+    '    const aliases = Array.isArray(action.aliases) ? action.aliases : [];',
+    '    return [action.id, ...aliases].map((alias) => [alias, action.id]);',
+    '  })',
     ');',
     '',
     'function normalizeActionId(value) {',
@@ -798,19 +829,28 @@ function renderVsCodeLauncher() {
     '  if (normalized.startsWith(\'roadmap-\')) {',
     '    normalized = normalized.slice(\'roadmap-\'.length);',
     '  }',
-    '  if (normalized === \'update\') {',
-    '    normalized = \'sync\';',
-    '  }',
     '  return normalized;',
     '}',
     '',
+    'function canonicalizeActionId(value) {',
+    '  const normalized = normalizeActionId(value);',
+    '  return ACTION_ALIAS_TO_ID[normalized] || normalized;',
+    '}',
+    '',
+    'function actionSearchTerms(action) {',
+    '  return [action.id, ...(Array.isArray(action.aliases) ? action.aliases : [])];',
+    '}',
+    '',
     'function getSlashSuggestions(query) {',
     '  const normalized = normalizeActionId(query);',
     '  if (!normalized) {',
     '    return SLASH_ACTIONS.slice();',
     '  }',
-    '  const startsWithMatches = SLASH_ACTIONS.filter((action) => action.id.startsWith(normalized));',
-    '  const containsMatches = SLASH_ACTIONS.filter((action) => !action.id.startsWith(normalized) && action.id.includes(normalized));',
+    '  const startsWithMatches = SLASH_ACTIONS.filter((action) => actionSearchTerms(action).some((term) => term.startsWith(normalized)));',
+    '  const containsMatches = SLASH_ACTIONS.filter((action) => {',
+    '    return !actionSearchTerms(action).some((term) => term.startsWith(normalized))',
+    '      && actionSearchTerms(action).some((term) => term.includes(normalized));',
+    '  });',
     '  return [...startsWithMatches, ...containsMatches];',
     '}',
     '',
@@ -857,7 +897,7 @@ function renderVsCodeLauncher() {
     '}',
     '',
     'function getSlashAction(actionId) {',
-    '  const normalized = normalizeActionId(actionId);',
+    '  const normalized = canonicalizeActionId(actionId);',
     '  return SLASH_ACTIONS.find((action) => action.id === normalized) || null;',
     '}',
     '',
@@ -921,13 +961,13 @@ function renderVsCodeLauncher() {
     'function explain() {',
     '  console.log(\'RoadmapSmith layers:\\n\');',
     '  console.log(\'1. The roadmap-sync skill guides the agent. It does not add VS Code buttons or install the CLI.\');',
-    '  console.log(\'2. The roadmapsmith CLI executes zero/maintain plus init/generate/validate/sync/setup/status, with doctor kept as a compatibility alias and --full-regen reserved for destructive replacement.\');',
+    '  console.log(\'2. The roadmapsmith CLI executes zero/maintain plus the canonical update family, with sync kept as the advanced alias for manual refresh and doctor kept as a compatibility alias.\');',
     '  console.log(\'3. roadmapsmith setup makes the CLI visible in VS Code through tasks and optional Claude hook wiring.\\n\');',
     '  console.log(\'Typical VS Code workflow:\');',
     '  console.log(\'- Run "RoadmapSmith: Status" to inspect readiness.\');',
     '  console.log(\'- For empty repos, run "RoadmapSmith: Zero Mode" or use "/roadmap zero".\');',
     '  console.log(\'- For existing repos, run "RoadmapSmith: Maintain" or use "/roadmap maintain".\');',
-    '  console.log(\'- Use Init, Generate, Validate, and Sync when you want manual control.\\n\');',
+    '  console.log(\'- Use Update for the public checklist-refresh/task-completion family, and use Init, Generate, Validate, and Sync when you want manual control.\\n\');',
     '  console.log(\'If you installed only the skill, install the CLI as well and then run "RoadmapSmith: Refresh Setup".\');',
     '}',
     '',
@@ -954,6 +994,16 @@ function renderVsCodeLauncher() {
     '  }',
     '  console.log(`Codex readiness: ${payload.hosts.codex.ready ? \'ready\' : \'needs setup\'} (${payload.hosts.codex.message})`);',
     '  console.log(`Claude readiness: ${payload.hosts.claude.ready ? \'ready\' : \'needs setup\'} (${payload.hosts.claude.message})`);',
+    '  if (payload.summary) {',
+    '    console.log(\'\\nStructured readiness summary:\');',
+    '    console.log(`- Workspace readiness: ${payload.summary.workspaceReady ? \'ready\' : \'needs setup\'}`);',
+    '    console.log(`- Codex readiness: ${payload.summary.codexReady ? \'ready\' : \'needs setup\'}`);',
+    '    console.log(`- Claude readiness: ${payload.summary.claudeReady ? \'ready\' : \'needs setup\'}`);',
+    '    console.log(`- Canonical native surfaces: ${payload.summary.canonicalSurfaceReady ? \'ready\' : \'needs attention\'}`);',
+    '    if (Array.isArray(payload.summary.advancedSurfaceWarnings)) {',
+    '      payload.summary.advancedSurfaceWarnings.forEach((warning) => console.log(`- Advanced warning: ${warning}`));',
+    '    }',
+    '  }',
     '  if (payload.surfaces && typeof payload.surfaces === \'object\') {',
     '    console.log(\'\\nNative slash surfaces:\');',
     '    Object.entries(payload.surfaces).forEach(([surfaceKey, surface]) => {',
@@ -976,7 +1026,8 @@ function renderVsCodeLauncher() {
     '  if (!payload.runtime.ready) {',
     '    console.log(\'\\nThe VS Code task runtime is missing. Install Node.js or set ROADMAPSMITH_NODE, then rerun "RoadmapSmith: Status".\');',
     '  }',
-    '  console.log(\'\\nRecommended entrypoints: roadmapsmith zero, roadmapsmith maintain\');',
+    '  console.log(\'\\nRecommended entrypoints: roadmapsmith zero, roadmapsmith maintain, roadmapsmith update\');',
+    '  console.log(\'Compatibility note: roadmapsmith doctor mirrors this payload for existing automation.\');',
     '  console.log(\'Slash entrypoints: /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-init, /roadmap-generate, /roadmap-validate, /roadmap-update, /roadmap-audit, /roadmap-setup, plus legacy /roadmap-sync <action>.\');',
     '}',
     '',
@@ -1041,6 +1092,7 @@ function renderVsCodeLauncher() {
     '  maintain: [\'maintain\', \'--project-root\', PROJECT_ROOT],',
     '  init: [\'init\'],',
     '  generate: [\'generate\', \'--project-root\', PROJECT_ROOT],',
+    '  update: [\'update\', \'--project-root\', PROJECT_ROOT],',
     '  validate: [\'validate\', \'--json\', \'--project-root\', PROJECT_ROOT],',
     '  sync: [\'sync\', \'--project-root\', PROJECT_ROOT],',
     '  audit: [\'sync\', \'--audit\', \'--project-root\', PROJECT_ROOT],',
@@ -1228,10 +1280,12 @@ function inspectVsCodeTasks(projectRoot) {
     tasks: {
       path: tasksPath,
       exists: tasksConfig != null,
-      ready: ROADMAPSMITH_TASK_LABELS.every((label) => presentLabels.includes(label)) && fs.existsSync(launcherPath) && wrapperEntries.every((entry) => entry.exists),
-      expectedLabels: ROADMAPSMITH_TASK_LABELS.slice(),
+      ready: ROADMAPSMITH_CANONICAL_TASK_LABELS.every((label) => presentLabels.includes(label)) && fs.existsSync(launcherPath) && wrapperEntries.every((entry) => entry.exists),
+      expectedLabels: ROADMAPSMITH_CANONICAL_TASK_LABELS.slice(),
+      advancedLabels: ROADMAPSMITH_ADVANCED_TASK_LABELS.slice(),
       presentLabels: presentManagedLabels,
-      missingLabels: ROADMAPSMITH_TASK_LABELS.filter((label) => !presentLabels.includes(label))
+      missingLabels: ROADMAPSMITH_CANONICAL_TASK_LABELS.filter((label) => !presentLabels.includes(label)),
+      missingAdvancedLabels: ROADMAPSMITH_ADVANCED_TASK_LABELS.filter((label) => !presentLabels.includes(label))
     }
   };
 }
@@ -1359,14 +1413,29 @@ function inspectHostSetup(projectRoot, options = {}) {
           ? 'Claude PostToolUse hook is configured'
           : 'Run roadmapsmith setup with the claude host and verify node is available to Claude'
       }
+    },
+    summary: {
+      workspaceReady: cli.ready && runtime.ready && vscode.tasks.ready && Boolean(roadmapFile && fs.existsSync(roadmapFile)) && Boolean(agentsFile && fs.existsSync(agentsFile)),
+      codexReady,
+      claudeReady: cli.ready && claude.ready,
+      canonicalSurfaceReady: bundle.ready && vscode.tasks.ready,
+      advancedSurfaceWarnings: [
+        ...vscode.tasks.missingAdvancedLabels.map((label) => `Missing advanced VS Code task: ${label}`),
+        ...EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS.filter((command) => !bundle.advancedCommands.includes(command)).map((command) => `Missing advanced bundle slash command: ${command}`)
+      ]
     }
   };
 }
 
 module.exports = {
   CLAUDE_HOOK_COMMAND,
+  EXPECTED_ADVANCED_NATIVE_SLASH_COMMANDS,
+  EXPECTED_CANONICAL_NATIVE_SLASH_COMMANDS,
+  EXPECTED_COMPATIBILITY_NATIVE_SLASH_COMMANDS,
   EXPECTED_NATIVE_SKILL_NAMES,
   EXPECTED_NATIVE_SLASH_COMMANDS,
+  ROADMAPSMITH_ADVANCED_TASK_LABELS,
+  ROADMAPSMITH_CANONICAL_TASK_LABELS,
   ROADMAPSMITH_TASK_LABELS,
   applySetupFiles,
   assertSupportedEditor,