feat(cli): shell completion for commands, flags, and entity names (#244)

* feat(completion): complete known argument values

* fix(completion): hide Commander-hidden subcommands from completions

Replace the `__`-prefix name heuristic with Commander's `_hidden` flag so
internal subcommands registered with { hidden: true } (e.g. `mcp serve-internal`)
are excluded from completions, mirroring `ktx --help`.

* test: cover wiki and sl read command routing

* test: cover raw wiki and sl reads

* feat: add wiki read command

* feat: add sl read command

* feat: complete read command entity names

* docs: document wiki and sl read commands

* test: include read commands in command tree

* feat(sl): read and validate unique sources by name

* feat(sl): make read and validate connection id optional

* fix(completion): dedupe semantic source names

* docs(sl): document connection-optional read and validate

* fix(sl): require connection id for query command

* docs(sl): clarify query connection requirement

* fix(completion): don't resolve option values as subcommands

resolveCommand skipped flag tokens but not the value consumed by a
value-taking option in the `--flag value` form, so a connection id like
`query` was matched as the `sl query` subcommand and yielded no `sl`
completions. Track value-taking options and skip their consumed value
before matching subcommands.

* test(telemetry): assert first-run notice via TELEMETRY_NOTICE constant

CI (which tests this branch merged with main) failed because #243 changed
the first-run notice wording in identity.ts (dropped "anonymous") but left
this test grepping for the old literal 'ktx collects anonymous usage data',
so indexOf returned -1. Assert against the exported TELEMETRY_NOTICE
constant instead so the test tracks the source of truth and cannot drift
when the notice text changes again.

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

@@ -0,0 +1,44 @@
+import { Argument, type Command } from '@commander-js/extra-typings';
+import type { KtxCliCommandContext } from '../cli-program.js';
+import { computeCompletions } from '../completion/complete-engine.js';
+import { completionScript } from '../completion/completion-scripts.js';
+import { createProjectCompletionProviders } from '../completion/dynamic-candidates.js';
+import { profileMark } from '../startup-profile.js';
+
+profileMark('module:commands/completion-commands');
+
+export function registerCompletionCommands(program: Command, context: KtxCliCommandContext): void {
+  program
+    .command('completion')
+    .description('Print a shell completion script for ktx')
+    .addArgument(new Argument('<shell>', 'Target shell').choices(['zsh', 'bash']))
+    .addHelpText(
+      'after',
+      '\nEnable completion by adding the matching line to your shell startup file:\n' +
+        '  zsh:  eval "$(ktx completion zsh)"\n' +
+        '  bash: eval "$(ktx completion bash)"\n',
+    )
+    .action((shell) => {
+      context.io.stdout.write(completionScript(shell));
+    });
+
+  // Hidden command invoked by the generated shell scripts. It must only ever
+  // print newline-separated candidates to stdout and exit 0, so a TAB press is
+  // never disrupted by an error, a telemetry notice, or a parse failure.
+  program
+    .command('__complete', { hidden: true })
+    .argument('[words...]')
+    .allowUnknownOption(true)
+    .helpOption(false)
+    .action(async (words: string[]) => {
+      try {
+        const candidates = await computeCompletions(program, words, createProjectCompletionProviders());
+        if (candidates.length > 0) {
+          context.io.stdout.write(`${candidates.join('\n')}\n`);
+        }
+      } catch {
+        // Swallow: completion must never break the shell.
+      }
+      context.setExitCode(0);
+    });
+}

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

@@ -21,9 +21,9 @@ function isDebugEnabled(command: CommandWithGlobalOptions): boolean {
 }
 
 export function registerWikiCommands(program: Command, context: KtxCliCommandContext): void {
-  program
+  const wiki = program
     .command('wiki')
-    .description('List or search local wiki pages')
+    .description('List, search, or read local wiki pages')
     .usage('[options] [query...]')
     .argument('[query...]', 'Search query; omit to list all pages')
     .option('--user-id <id>', 'Local user id', 'local')
@@ -76,4 +76,18 @@ export function registerWikiCommands(program: Command, context: KtxCliCommandCon
         });
       },
     );
+
+  wiki
+    .command('read')
+    .description('Read a wiki page file by key')
+    .argument('<key>', 'Wiki page key')
+    .action(async (key: string, _options, command) => {
+      const parentOpts = command.parent?.opts() as { userId?: string } | undefined;
+      await runKnowledgeArgs(context, {
+        command: 'read',
+        projectDir: resolveCommandProjectDir(command),
+        key,
+        userId: parentOpts?.userId ?? 'local',
+      });
+    });
 }

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

@@ -94,19 +94,28 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
       },
     );
 
-  sl.command('validate')
-    .description('Validate a semantic-layer source (set --connection-id on `ktx sl`)')
+  sl.command('read')
+    .description('Read a semantic-layer source YAML file')
+    .argument('<sourceName>', 'Semantic-layer source name')
+    .action(async (sourceName: string, _options, command) => {
+      const parentOpts = command.parent?.opts() as { connectionId?: string } | undefined;
+      await runSlArgs(context, {
+        command: 'read',
+        projectDir: resolveCommandProjectDir(command),
+        connectionId: parentOpts?.connectionId,
+        sourceName,
+      });
+    });
+
+  sl.command('validate')
+    .description('Validate a semantic-layer source')
     .argument('<sourceName>', 'Semantic-layer source name')
     .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: connectionId as string,
+        connectionId: parentOpts?.connectionId,
         sourceName,
       });
     });
@@ -131,10 +140,14 @@ export function registerSlCommands(program: Command, context: KtxCliCommandConte
         throw new Error('sl query requires at least one --measure');
       }
       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");
+      }
       const args = slQueryCommandSchema.parse({
         command: 'query',
         projectDir: resolveCommandProjectDir(command),
-        connectionId: parentOpts?.connectionId,
+        connectionId,
         ...(options.queryFile
           ? { queryFile: options.queryFile }
           : {