@laitszkin/apollo-toolkit 3.11.7 → 3.12.0

package/init-project-html/scripts/architecture.js

@@ -29,30 +29,7 @@ const DEFAULT_OUT_REL = path.join('.apollo-toolkit', 'architecture-diff');
 
 const LEGACY_VERBS = new Set(['open', 'diff']);
 
-const USAGE = `apltk architecture — declarative atlas CLI.
-
-Usage:
-  apltk architecture                          Open resources/project-architecture/index.html
-  apltk architecture open                     Same as above
-  apltk architecture diff                     Render every architecture_diff/ as one paginated viewer
-  apltk architecture render                   Regenerate atlas HTML from current YAML state
-  apltk architecture validate                 Run schema + referential checks
-  apltk architecture feature add|set|remove   Manage feature modules
-  apltk architecture submodule add|set|remove Manage sub-modules
-  apltk architecture function|variable|dataflow|error|edge add|remove
-                                              Manage component rows and edges
-  apltk architecture meta set                 Update meta.title / meta.summary
-  apltk architecture actor add|remove         Manage top-level actors
-  apltk architecture undo [--steps <n>]      Revert the most recent mutation or roll back multiple steps
-  apltk architecture --help                   Show this help
-
-Global flags:
-  --project <root>   Project root (default: nearest ancestor with resources/project-architecture/, else cwd); missing layout dirs are created when needed
-  --spec <spec_dir>  Single specs write locally; batch member paths write to the coordination.md root architecture_diff/atlas/
-  --no-render        Skip auto-render after a mutation
-  --no-open          For open/diff: skip launching the browser
-  --out <dir>        For diff: override viewer output directory
-  -h, --help         Show this help`;
+const USAGE = newCli.buildArchitectureHelpPage();
 
 function parseArgs(argv) {
   const args = [...argv];
@@ -277,7 +254,9 @@ function main(argv, io = { stdout: process.stdout, stderr: process.stderr }) {
     return 1;
   }
   if (opts.help) {
-    io.stdout.write(`${USAGE}\n`);
+    const explicitLegacyVerb = argv.length > 0 && !argv[0].startsWith('-') && LEGACY_VERBS.has(argv[0]);
+    const helpText = explicitLegacyVerb ? newCli.buildArchitectureHelpPage(argv[0]) : USAGE;
+    io.stdout.write(`${helpText}\n`);
     return 0;
   }
   if (opts.subcommand === 'open') return runOpen(opts, io);

package/lib/cli.js

@@ -15,7 +15,7 @@ const {
   getTargetRoots,
   getUninstallTargetRoots,
 } = require('./installer');
-const { formatToolList, getToolCommand, runTool } = require('./tool-runner');
+const { buildToolDiscoveryHelp, formatToolList, getToolCommand, runTool } = require('./tool-runner');
 const { checkForPackageUpdate } = require('./updater');
 
 const TARGET_OPTIONS = [
@@ -132,6 +132,25 @@ async function animateWelcomeScreen({ output, version, env }) {
 }
 
 function buildHelpText({ version, colorEnabled }) {
+  const examples = [
+    {
+      command: 'apltk --help',
+      result: 'Shows the top-level Apollo Toolkit guide, including install modes and bundled task-tool discovery.',
+    },
+    {
+      command: 'apltk tools --help',
+      result: 'Lists bundled tools by task so you can decide which CLI helper to inspect next.',
+    },
+    {
+      command: 'apltk architecture --help',
+      result: 'Shows the architecture atlas command tree, task guidance, and action-specific follow-up help paths.',
+    },
+    {
+      command: 'apltk tools architecture --help',
+      result: 'Shows what the architecture atlas tool is for, then prints its native command tree and examples.',
+    },
+    { command: 'apltk filter-logs app.log --start 2026-03-24T10:00:00Z', result: 'Prints only the log lines whose timestamps fall within the requested time window.' },
+  ];
   return [
     buildBanner({ version, colorEnabled }),
     '',
@@ -145,35 +164,44 @@ function buildHelpText({ version, colorEnabled }) {
     '  apltk --help',
     '  apollo-toolkit --help',
     '',
-    'Examples:',
-    '  apltk',
-    '  apltk codex openclaw',
-    '  apltk uninstall',
-    '  apltk uninstall codex agents --yes',
-    '  npx @laitszkin/apollo-toolkit',
-    '  npx @laitszkin/apollo-toolkit codex openclaw',
-    '  npm i -g @laitszkin/apollo-toolkit',
-    '  apltk agents',
-    '  apltk claude-code',
-    '  apltk all',
-    '  apltk filter-logs app.log --start 2026-03-24T10:00:00Z',
-    '  apltk create-specs "Membership upgrade flow" --change-name membership-upgrade-flow',
-    '  apltk architecture                       # open resources/project-architecture/index.html',
-    '  apltk architecture diff                  # paginated before/after view of all docs/plans/.../architecture_diff/',
-    '  apltk tools',
-    '  apollo-toolkit all',
+    'Common goals:',
+    '  - Install or refresh skills in one or more agent targets: `apltk install --help`',
+    '  - Remove manifest-tracked installs from selected targets: `apltk uninstall --help`',
+    '  - Discover which bundled helper tool matches a task: `apltk tools --help`',
+    '  - Inspect one tool deeply before running it: `apltk tools <tool> --help`',
     '',
     'Bundled tools:',
     formatToolList(),
     '',
+    buildToolDiscoveryHelp(),
+    '',
     'Options:',
     '  --home <path>  Override Apollo Toolkit home directory',
+    '  --symlink      Install skills as symlinks instead of copied directories',
+    '  --copy         Install skills as copied directories instead of symlinks',
     '  --yes, -y      Skip uninstall confirmation',
     '  --help         Show this help text',
+    '',
+    'Examples:',
+    ...examples.flatMap(({ command, result }) => [`  ${command}`, `    Result: ${result}`]),
   ].join('\n');
 }
 
 function buildToolsHelp({ version, colorEnabled }) {
+  const examples = [
+    {
+      command: 'apltk tools',
+      result: 'Lists all bundled tools plus the task-oriented discovery guide.',
+    },
+    {
+      command: 'apltk tools open-github-issue --help',
+      result: 'Shows when to use the GitHub issue publisher, then prints its exact script flags and examples.',
+    },
+    {
+      command: 'apltk tools architecture --help',
+      result: 'Shows when to use the architecture atlas CLI, then prints its native command tree.',
+    },
+  ];
   return [
     buildBanner({ version, colorEnabled }),
     '',
@@ -182,11 +210,107 @@ function buildToolsHelp({ version, colorEnabled }) {
     '  apltk <tool> [...args]',
     '  apltk tools <tool> [...args]',
     '',
+    buildToolDiscoveryHelp(),
+    '',
     'Bundled tools:',
     formatToolList(),
     '',
     'Tip:',
-    '  Pass `--help` after a tool name to view the original script flags.',
+    '  Pass `--help` after a tool name to view task guidance, native script flags, and concrete examples.',
+    '',
+    'Examples:',
+    ...examples.flatMap(({ command, result }) => [`  ${command}`, `    Result: ${result}`]),
+  ].join('\n');
+}
+
+function buildInstallHelpText({ version, colorEnabled }) {
+  const examples = [
+    {
+      command: 'apltk',
+      result: 'Launches the interactive installer, opens the target selector, and then walks through link-mode confirmation.',
+    },
+    {
+      command: 'apltk codex openclaw --symlink',
+      result: 'Performs a non-interactive install into `codex` and `openclaw` targets using symlinks.',
+    },
+    {
+      command: 'npx @laitszkin/apollo-toolkit all --copy',
+      result: 'Installs a copied snapshot into every supported target instead of symlinking.',
+    },
+  ];
+
+  return [
+    buildBanner({ version, colorEnabled }),
+    '',
+    'Usage:',
+    `  apltk [install] [${buildModeUsagePattern()}]...`,
+    `  apollo-toolkit [install] [${buildModeUsagePattern()}]...`,
+    '',
+    'Use this when:',
+    '  - You want to install or refresh Apollo Toolkit skills in one or more agent targets.',
+    '  - You need to choose between symlink mode (auto-updating) and copy mode (stable snapshot).',
+    '',
+    'Supported targets:',
+    buildSupportedTargetLines({ colorEnabled }),
+    '',
+    'Behavior notes:',
+    '  - Running `apltk` with no targets opens the interactive installer and target selector.',
+    '  - `--symlink` keeps installed skills connected to the managed toolkit checkout in `~/.apollo-toolkit`.',
+    '  - `--copy` installs a snapshot that only changes when you run the installer again.',
+    '  - The installer can optionally include codex-exclusive skills in non-codex targets after prompting.',
+    '',
+    'Options:',
+    '  --home <path>  Override Apollo Toolkit home directory',
+    '  --symlink      Install skills as symlinks (recommended)',
+    '  --copy         Install skills as copied directories',
+    '  --help         Show this install help',
+    '',
+    'Examples:',
+    ...examples.flatMap(({ command, result }) => [`  ${command}`, `    Result: ${result}`]),
+  ].join('\n');
+}
+
+function buildUninstallHelpText({ version, colorEnabled }) {
+  const examples = [
+    {
+      command: 'apltk uninstall',
+      result: 'Opens the interactive uninstall selector when running in a TTY and then asks for confirmation before removal.',
+    },
+    {
+      command: 'apltk uninstall codex agents --yes',
+      result: 'Removes Apollo Toolkit-managed installs from `codex` and `agents` without another confirmation prompt.',
+    },
+    {
+      command: 'apltk uninstall codex --home /tmp/custom-home',
+      result: 'Uses the custom managed toolkit home while removing manifest-tracked installs from the selected target.',
+    },
+  ];
+
+  return [
+    buildBanner({ version, colorEnabled }),
+    '',
+    'Usage:',
+    `  apltk uninstall [${buildModeUsagePattern()}]... [--yes]`,
+    '',
+    'Use this when:',
+    '  - You want to remove Apollo Toolkit-managed skills from one or more agent targets.',
+    '  - You need to clean up manifest-tracked historical installs as well as the current installed skills.',
+    '',
+    'Supported targets:',
+    buildSupportedTargetLines({ colorEnabled }),
+    '',
+    'Behavior notes:',
+    '  - With no explicit targets, uninstall opens the interactive selector in a TTY and otherwise falls back to all targets.',
+    '  - Uninstall removes manifest-tracked current and historical Apollo Toolkit skill directories.',
+    '  - `--yes` skips the confirmation prompt after the target list is resolved.',
+    '',
+    'Options:',
+    '  --home <path>  Override Apollo Toolkit home directory',
+    '  --yes, -y      Skip uninstall confirmation',
+    '  --help         Show this uninstall help',
+    '',
+    'Examples:',
+    ...examples.flatMap(({ command, result }) => [`  ${command}`, `    Result: ${result}`]),
   ].join('\n');
 }
 
@@ -206,6 +330,8 @@ function parseArguments(argv) {
     toolArgs: [],
     linkMode: null, // 'copy' | 'symlink' | null (prompt)
     assumeYes: false,
+    explicitInstallCommand: false,
+    helpTopic: 'overview',
   };
 
   if (args[0] === 'uninstall') {
@@ -227,6 +353,9 @@ function parseArguments(argv) {
         result.modes.push(arg);
       }
     }
+    if (result.showHelp) {
+      result.helpTopic = 'uninstall';
+    }
     return result;
   }
 
@@ -279,12 +408,21 @@ function parseArguments(argv) {
     }
 
     if (arg === 'install') {
+      result.explicitInstallCommand = true;
       continue;
     }
 
     result.modes.push(arg);
   }
 
+  if (result.showHelp) {
+    const installContextRequested = result.explicitInstallCommand
+      || result.modes.length > 0
+      || result.linkMode !== null
+      || result.toolkitHome !== null;
+    result.helpTopic = installContextRequested ? 'install' : 'overview';
+  }
+
   return result;
 }
 
@@ -585,7 +723,13 @@ async function run(argv, context = {}) {
     const parsed = parseArguments(argv);
 
     if (parsed.showHelp) {
-      stdout.write(`${buildHelpText({ version: packageJson.version, colorEnabled: supportsColor(stdout, env) })}\n`);
+      const colorEnabled = supportsColor(stdout, env);
+      const helpText = parsed.helpTopic === 'install'
+        ? buildInstallHelpText({ version: packageJson.version, colorEnabled })
+        : parsed.helpTopic === 'uninstall'
+          ? buildUninstallHelpText({ version: packageJson.version, colorEnabled })
+          : buildHelpText({ version: packageJson.version, colorEnabled });
+      stdout.write(`${helpText}\n`);
       return 0;
     }
 
@@ -741,7 +885,9 @@ module.exports = {
   buildBanner,
   buildWelcomeScreen,
   buildHelpText,
+  buildInstallHelpText,
   buildToolsHelp,
+  buildUninstallHelpText,
   parseArguments,
   promptForModes,
   promptForUninstallModes,