feat(cli): smart defaults and flatter command surface for ktx (#177)

Bare invocations now do the obvious thing instead of erroring out, and mode-as-subcommand patterns collapse into flags on the parent. No new top-level commands.

- `ktx ingest` (bare) ingests every configured connection. The `text` subcommand is gone; capture inline notes with `ktx ingest --text "..."` and files with `ktx ingest --file path` (use `-` for stdin). `--text`/`--file` reject a positional connection id; pass `--connection-id` to tag captured notes.
- `ktx connection` (bare) lists; `ktx connection test` (bare) tests every configured connection.
- `ktx wiki` and `ktx sl` flatten `list`/`search`: bare lists, with a `[query...]` positional searches (multi-word joined with spaces). `sl validate` and `sl query` stay as distinct verbs and now read `--connection-id` from the parent.
- `ktx mcp` (bare) prints daemon status.

Adds a shared `resolveConnectionSelection` helper consumed by ingest and connection test. Updates README, docs-site cli-reference and guides, next-steps strings, agent SKILL templates, and all affected tests. Per-package type-check, unit tests (605), smoke tests, and dead-code checks all pass.

packages/cli/src/commands/connection-commands.ts

@@ -2,6 +2,7 @@ import { type Command } from '@commander-js/extra-typings';
 import { type KtxCliCommandContext, resolveCommandProjectDir } from '../cli-program.js';
 import type { KtxConnectionArgs } from '../connection.js';
 import { profileMark } from '../startup-profile.js';
+import { resolveConnectionSelection } from './connection-selection.js';
 
 profileMark('module:commands/connection-commands');
 
@@ -18,7 +19,10 @@ export function registerConnectionCommands(program: Command, context: KtxCliComm
     .addHelpText(
       'after',
       '\nProject directory defaults to KTX_PROJECT_DIR when set, otherwise the nearest ktx.yaml or current working directory.\n',
-    );
+    )
+    .action(async (_options: unknown, command) => {
+      await runConnectionArgs(context, { command: 'list', projectDir: resolveCommandProjectDir(command) });
+    });
   connection.hook('preAction', (_thisCommand, actionCommand) => {
     context.writeDebug?.(commandName, actionCommand);
   });
@@ -32,25 +36,22 @@ export function registerConnectionCommands(program: Command, context: KtxCliComm
 
   connection
     .command('test')
-    .description('Test a configured connection')
-    .argument('[connectionId]', 'KTX connection id (omit when --all is set)')
+    .description('Test one or all configured connections (default: all)')
+    .argument('[connectionId]', 'KTX connection id to test (omit to test all)')
     .option('--all', 'Test every configured connection and print a summary list')
     .action(async (connectionId: string | undefined, options: { all?: boolean }, command) => {
-      const all = options.all === true;
-      if (all && connectionId !== undefined) {
+      if (options.all === true && connectionId !== undefined) {
         command.error('error: --all cannot be combined with a connection id argument');
       }
-      if (!all && connectionId === undefined) {
-        command.error('error: missing required argument <connectionId> (or pass --all)');
-      }
-      if (all) {
+      const selection = resolveConnectionSelection({ connectionId, all: options.all === true });
+      if (selection.kind === 'all') {
         await runConnectionArgs(context, { command: 'test-all', projectDir: resolveCommandProjectDir(command) });
         return;
       }
       await runConnectionArgs(context, {
         command: 'test',
         projectDir: resolveCommandProjectDir(command),
-        connectionId: connectionId as string,
+        connectionId: selection.connectionId,
       });
     });
 }

packages/cli/src/commands/connection-selection.ts

@@ -0,0 +1,18 @@
+export type ConnectionSelection =
+  | { kind: 'all' }
+  | { kind: 'single'; connectionId: string };
+
+export interface ResolveConnectionSelectionInput {
+  connectionId?: string | undefined;
+  all: boolean;
+}
+
+export function resolveConnectionSelection(input: ResolveConnectionSelectionInput): ConnectionSelection {
+  if (input.all && input.connectionId !== undefined) {
+    throw new Error('--all cannot be combined with a connection id argument');
+  }
+  if (input.connectionId !== undefined) {
+    return { kind: 'single', connectionId: input.connectionId };
+  }
+  return { kind: 'all' };
+}

packages/cli/src/commands/ingest-commands.ts

@@ -10,6 +10,7 @@ import { runtimeInstallPolicyFromFlags } from '../managed-python-command.js';
 import type { KtxPublicIngestArgs } from '../public-ingest.js';
 import { profileMark } from '../startup-profile.js';
 import type { KtxTextIngestArgs } from '../text-ingest.js';
+import { resolveConnectionSelection } from './connection-selection.js';
 
 profileMark('module:commands/ingest-commands');
 
@@ -24,15 +25,20 @@ export function registerIngestCommands(
 ): void {
   const ingest = program
     .command('ingest')
-    .description('Build or inspect KTX context')
+    .description('Build or inspect KTX context, or capture text into memory')
     .usage('[options] [connectionId]')
-    .argument('[connectionId]', 'Configured connection id to ingest')
+    .argument('[connectionId]', 'Configured connection id to ingest (omit to ingest all)')
     .option('--all', 'Ingest all configured connections', false)
     .addOption(new Option('--fast', 'Use deterministic database schema ingest').conflicts('deep'))
     .addOption(new Option('--deep', 'Use AI-enriched database ingest').conflicts('fast'))
     .addOption(new Option('--query-history', 'Include database query-history usage patterns').conflicts('noQueryHistory'))
     .addOption(new Option('--no-query-history', 'Skip database query-history usage patterns'))
     .option('--query-history-window-days <days>', 'Query-history lookback window for this run', parsePositiveIntegerOption)
+    .option('--text <content>', 'Capture inline text into KTX memory; repeatable', collectOption, [])
+    .option('--file <path>', 'Capture a text file into KTX memory; use - for stdin; repeatable', collectOption, [])
+    .option('--connection-id <connectionId>', 'KTX connection id to tag captured text/file notes')
+    .option('--user-id <id>', 'Memory user id for text/file capture attribution', 'local-cli')
+    .option('--fail-fast', 'Stop after the first failed text/file item', false)
     .addOption(new Option('--plain', 'Print plain text output').conflicts(['json']))
     .addOption(new Option('--json', 'Print JSON output').conflicts(['plain']))
     .option('--yes', 'Install required managed runtime features without prompting')
@@ -40,14 +46,45 @@ export function registerIngestCommands(
     .showHelpAfterError();
 
   ingest.action(async (connectionId: string | undefined, options, command) => {
+    const projectDir = resolveCommandProjectDir(command);
+    const hasTextCapture = options.text.length > 0 || options.file.length > 0;
+
+    if (hasTextCapture) {
+      if (connectionId !== undefined) {
+        command.error(
+          'error: --text/--file does not accept a positional connection id; use --connection-id <id> to tag captured notes',
+        );
+      }
+      if (options.all === true) {
+        command.error('error: --all cannot be combined with --text or --file');
+      }
+      context.setExitCode(
+        await commandOptions.runTextIngest(
+          {
+            projectDir,
+            texts: options.text,
+            files: options.file,
+            ...(options.connectionId ? { connectionId: options.connectionId } : {}),
+            userId: options.userId,
+            json: options.json === true,
+            failFast: options.failFast === true,
+          },
+          context.io,
+          context.deps,
+        ),
+      );
+      return;
+    }
+
+    const selection = resolveConnectionSelection({ connectionId, all: options.all === true });
     const { runKtxPublicIngest } = await import('../public-ingest.js');
     const queryHistory =
       options.queryHistory === true ? 'enabled' : options.queryHistory === false ? 'disabled' : 'default';
     const args: KtxPublicIngestArgs = {
       command: 'run',
-      projectDir: resolveCommandProjectDir(command),
-      ...(connectionId ? { targetConnectionId: connectionId } : {}),
-      all: options.all === true,
+      projectDir,
+      ...(selection.kind === 'single' ? { targetConnectionId: selection.connectionId } : {}),
+      all: selection.kind === 'all',
       json: options.json === true,
       inputMode: options.input === false ? 'disabled' : 'auto',
       ...(options.fast === true ? { depth: 'fast' as const } : {}),
@@ -63,32 +100,4 @@ export function registerIngestCommands(
   ingest.hook('preAction', (_thisCommand, actionCommand) => {
     context.writeDebug?.('ingest', actionCommand);
   });
-
-  ingest
-    .command('text')
-    .description('Ingest free-form text artifacts into KTX memory')
-    .argument('[files...]', 'Files to ingest; use - to read one item from stdin')
-    .option('--text <content>', 'Text content to ingest; repeat for a batch', collectOption, [])
-    .option('--connection-id <connectionId>', 'Optional KTX connection id for semantic-layer capture')
-    .option('--user-id <id>', 'Memory user id for capture attribution', 'local-cli')
-    .option('--json', 'Print JSON output')
-    .option('--fail-fast', 'Stop after the first failed text item', false)
-    .action(async (files: string[], options, command) => {
-      const parentOptions = command.parent?.opts() as { json?: boolean } | undefined;
-      context.setExitCode(
-        await commandOptions.runTextIngest(
-          {
-            projectDir: resolveCommandProjectDir(command),
-            texts: options.text,
-            files,
-            ...(options.connectionId ? { connectionId: options.connectionId } : {}),
-            userId: options.userId,
-            json: options.json === true || parentOptions?.json === true,
-            failFast: options.failFast === true,
-          },
-          context.io,
-          context.deps,
-        ),
-      );
-    });
 }

packages/cli/src/commands/knowledge-commands.ts

@@ -21,59 +21,29 @@ function isDebugEnabled(command: CommandWithGlobalOptions): boolean {
 }
 
 export function registerWikiCommands(program: Command, context: KtxCliCommandContext): void {
-  const wiki = program
+  program
     .command('wiki')
     .description('List or search local wiki pages')
+    .usage('[options] [query...]')
+    .argument('[query...]', 'Search query; omit to list all pages')
+    .option('--user-id <id>', 'Local user id', 'local')
+    .option('--limit <number>', 'Maximum search results (search mode only)', parsePositiveIntegerOption)
+    .addOption(
+      new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
+        'pretty',
+        'plain',
+        'json',
+      ]),
+    )
+    .option('--json', 'Shortcut for --output=json (overrides --output)', false)
     .showHelpAfterError()
     .addHelpText(
       'after',
       '\nProject directory defaults to KTX_PROJECT_DIR when set, otherwise the current working directory.\n',
-    );
-
-  wiki
-    .command('list')
-    .description('List local wiki pages')
-    .option('--user-id <id>', 'Local user id', 'local')
-    .addOption(
-      new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
-        'pretty',
-        'plain',
-        'json',
-      ]),
     )
-    .option('--json', 'Shortcut for --output=json (overrides --output)', false)
     .action(
       async (
-        options: { userId: string; output?: 'pretty' | 'plain' | 'json'; json?: boolean },
-        command,
-      ) => {
-        await runKnowledgeArgs(context, {
-          command: 'list',
-          projectDir: resolveCommandProjectDir(command),
-          userId: options.userId,
-          output: options.output,
-          json: options.json,
-        });
-      },
-    );
-
-  wiki
-    .command('search')
-    .description('Search local wiki pages')
-    .argument('<query>', 'Search query')
-    .option('--user-id <id>', 'Local user id', 'local')
-    .option('--limit <number>', 'Maximum search results', parsePositiveIntegerOption)
-    .addOption(
-      new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
-        'pretty',
-        'plain',
-        'json',
-      ]),
-    )
-    .option('--json', 'Shortcut for --output=json (overrides --output)', false)
-    .action(
-      async (
-        query: string,
+        query: string[],
         options: {
           userId: string;
           limit?: number;
@@ -82,10 +52,20 @@ export function registerWikiCommands(program: Command, context: KtxCliCommandCon
         },
         command,
       ) => {
+        if (query.length === 0) {
+          await runKnowledgeArgs(context, {
+            command: 'list',
+            projectDir: resolveCommandProjectDir(command),
+            userId: options.userId,
+            output: options.output,
+            json: options.json,
+          });
+          return;
+        }
         await runKnowledgeArgs(context, {
           command: 'search',
           projectDir: resolveCommandProjectDir(command),
-          query,
+          query: query.join(' '),
           userId: options.userId,
           output: options.output,
           json: options.json,

packages/cli/src/commands/mcp-commands.ts

@@ -36,8 +36,24 @@ function formatMcpStartResultMessage(input: { status: 'started' | 'already-runni
   ].join('\n');
 }
 
+async function printMcpStatus(context: KtxCliCommandContext, projectDir: string): Promise<void> {
+  const status = await (context.deps.mcp?.readStatus ?? readKtxMcpDaemonStatus)({ projectDir });
+  context.io.stdout.write(`${status.detail}\n`);
+  if (status.kind === 'running') {
+    context.io.stdout.write(`URL: ${status.url}\n`);
+    context.io.stdout.write(`PID: ${status.state.pid}\n`);
+    context.io.stdout.write(`Token auth: ${status.state.tokenAuth ? 'enabled' : 'disabled'}\n`);
+    context.io.stdout.write(`Project: ${status.state.projectDir}\n`);
+  }
+}
+
 export function registerMcpCommands(program: Command, context: KtxCliCommandContext): void {
-  const mcp = program.command('mcp').description('Run the KTX MCP HTTP server');
+  const mcp = program
+    .command('mcp')
+    .description('Manage the KTX MCP HTTP server (bare command: show status)')
+    .action(async (_options, command) => {
+      await printMcpStatus(context, resolveCommandProjectDir(command));
+    });
 
   mcp
     .command('stdio')
@@ -110,16 +126,7 @@ export function registerMcpCommands(program: Command, context: KtxCliCommandCont
     .command('status')
     .description('Show KTX MCP daemon status')
     .action(async (_options, command) => {
-      const status = await (context.deps.mcp?.readStatus ?? readKtxMcpDaemonStatus)({
-        projectDir: resolveCommandProjectDir(command),
-      });
-      context.io.stdout.write(`${status.detail}\n`);
-      if (status.kind === 'running') {
-        context.io.stdout.write(`URL: ${status.url}\n`);
-        context.io.stdout.write(`PID: ${status.state.pid}\n`);
-        context.io.stdout.write(`Token auth: ${status.state.tokenAuth ? 'enabled' : 'disabled'}\n`);
-        context.io.stdout.write(`Project: ${status.state.projectDir}\n`);
-      }
+      await printMcpStatus(context, resolveCommandProjectDir(command));
     });
 
   mcp

packages/cli/src/commands/sl-commands.ts

@@ -42,59 +42,49 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
   const sl = program
     .command(commandName)
     .description('List, search, validate, or query local semantic-layer sources')
+    .usage('[options] [query...]')
+    .argument('[query...]', 'Search query; omit to list all sources')
+    .option('--connection-id <id>', 'KTX connection id')
+    .option('--limit <number>', 'Maximum search results (search mode only)', parsePositiveIntegerOption)
+    .addOption(
+      new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
+        'pretty',
+        'plain',
+        'json',
+      ]),
+    )
+    .option('--json', 'Shortcut for --output=json (overrides --output)', false)
     .showHelpAfterError()
     .addHelpText(
       'after',
       '\nProject directory defaults to KTX_PROJECT_DIR when set, otherwise the current working directory.\n',
-    );
-
-  sl.command('list')
-    .description('List semantic-layer sources')
-    .option('--connection-id <id>', 'KTX connection id')
-    .addOption(
-      new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
-        'pretty',
-        'plain',
-        'json',
-      ]),
     )
-    .option('--json', 'Shortcut for --output=json (overrides --output)', false)
-    .action(
-      async (options: { connectionId?: string; output?: 'pretty' | 'plain' | 'json'; json?: boolean }, command) => {
-        await runSlArgs(context, {
-          command: 'list',
-          projectDir: resolveCommandProjectDir(command),
-          connectionId: options.connectionId,
-          output: options.output,
-          json: options.json,
-        });
-      },
-    );
-
-  sl.command('search')
-    .description('Search semantic-layer sources')
-    .argument('<query>', 'Search query')
-    .option('--connection-id <id>', 'KTX connection id')
-    .option('--limit <number>', 'Maximum search results', parsePositiveIntegerOption)
-    .addOption(
-      new Option('--output <mode>', 'Output mode: pretty (default in TTY), plain (TSV), or json').choices([
-        'pretty',
-        'plain',
-        'json',
-      ]),
-    )
-    .option('--json', 'Shortcut for --output=json (overrides --output)', false)
     .action(
       async (
-        query: string,
-        options: { connectionId?: string; limit?: number; output?: 'pretty' | 'plain' | 'json'; json?: boolean },
+        query: string[],
+        options: {
+          connectionId?: string;
+          limit?: number;
+          output?: 'pretty' | 'plain' | 'json';
+          json?: boolean;
+        },
         command,
       ) => {
+        if (query.length === 0) {
+          await runSlArgs(context, {
+            command: 'list',
+            projectDir: resolveCommandProjectDir(command),
+            connectionId: options.connectionId,
+            output: options.output,
+            json: options.json,
+          });
+          return;
+        }
         await runSlArgs(context, {
           command: 'search',
           projectDir: resolveCommandProjectDir(command),
           connectionId: options.connectionId,
-          query,
+          query: query.join(' '),
           ...(options.limit !== undefined ? { limit: options.limit } : {}),
           output: options.output,
           json: options.json,
@@ -103,21 +93,24 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
     );
 
   sl.command('validate')
-    .description('Validate a semantic-layer source')
+    .description('Validate a semantic-layer source (set --connection-id on `ktx sl`)')
     .argument('<sourceName>', 'Semantic-layer source name')
-    .requiredOption('--connection-id <id>', 'KTX connection id')
-    .action(async (sourceName: string, options: { connectionId: string }, command) => {
+    .action(async (sourceName: string, _options, command) => {
+      const parentOpts = command.parent?.opts() as { connectionId?: string } | undefined;
+      const connectionId = parentOpts?.connectionId;
+      if (connectionId === undefined) {
+        command.error("error: required option '--connection-id <id>' not specified");
+      }
       await runSlArgs(context, {
         command: 'validate',
         projectDir: resolveCommandProjectDir(command),
-        connectionId: options.connectionId,
+        connectionId: connectionId as string,
         sourceName,
       });
     });
 
   sl.command('query')
-    .description('Compile or execute a semantic-layer query')
-    .option('--connection-id <id>', 'KTX connection id')
+    .description('Compile or execute a semantic-layer query (set --connection-id on `ktx sl`)')
     .option('--query-file <path>', 'JSON semantic-layer query file')
     .option('--measure <measure>', 'Measure to query; repeatable', collectOption, [])
     .option('--dimension <dimension>', 'Dimension to include; repeatable', collectOption, [])
@@ -135,10 +128,11 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
       if (options.measure.length === 0 && !options.queryFile) {
         throw new Error('sl query requires at least one --measure');
       }
+      const parentOpts = command.parent?.opts() as { connectionId?: string } | undefined;
       const args = slQueryCommandSchema.parse({
         command: 'query',
         projectDir: resolveCommandProjectDir(command),
-        connectionId: options.connectionId,
+        connectionId: parentOpts?.connectionId,
         ...(options.queryFile
           ? { queryFile: options.queryFile }
           : {