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/context/sl/local-sl.ts

@@ -50,6 +50,7 @@ export interface LocalSlSearchInput {
   pglite?: PgliteSlSearchPrototypeOwnerOptions;
 }
 
+/** @internal */
 export interface LocalSlSource extends LocalSlSourceSummary {
   yaml: string;
 }
@@ -63,6 +64,11 @@ export interface LocalSlValidationResult {
   errors: string[];
 }
 
+export type ResolvedSlSource =
+  | { kind: 'found'; source: LocalSlSource }
+  | { kind: 'not-found' }
+  | { kind: 'ambiguous'; connectionIds: string[] };
+
 const LOCAL_AUTHOR = 'ktx';
 const LOCAL_AUTHOR_EMAIL = 'ktx@example.com';
 
@@ -311,6 +317,7 @@ export async function writeLocalSlSource(
   );
 }
 
+/** @internal */
 export async function readLocalSlSource(
   project: KtxLocalProject,
   input: { connectionId: string; sourceName: string },
@@ -331,6 +338,41 @@ export async function readLocalSlSource(
   }
 }
 
+export async function resolveLocalSlSource(
+  project: KtxLocalProject,
+  input: { sourceName: string; connectionId?: string },
+): Promise<ResolvedSlSource> {
+  if (input.connectionId !== undefined) {
+    const source = await readLocalSlSource(project, {
+      connectionId: input.connectionId,
+      sourceName: input.sourceName,
+    });
+    return source ? { kind: 'found', source } : { kind: 'not-found' };
+  }
+
+  const summaries = await listLocalSlSources(project, {});
+  const matches = summaries.filter((summary) => summary.name === input.sourceName);
+  if (matches.length === 0) {
+    return { kind: 'not-found' };
+  }
+  if (matches.length > 1) {
+    return {
+      kind: 'ambiguous',
+      connectionIds: [...new Set(matches.map((match) => match.connectionId))].sort(),
+    };
+  }
+
+  const match = matches[0];
+  if (match === undefined) {
+    return { kind: 'not-found' };
+  }
+  const source = await readLocalSlSource(project, {
+    connectionId: match.connectionId,
+    sourceName: input.sourceName,
+  });
+  return source ? { kind: 'found', source } : { kind: 'not-found' };
+}
+
 export async function listLocalSlSources(
   project: KtxLocalProject,
   input: { connectionId?: string } = {},

packages/cli/src/context/wiki/local-knowledge.ts

@@ -201,6 +201,32 @@ export async function listLocalKnowledgePages(
   return pages.sort((left, right) => left.path.localeCompare(right.path));
 }
 
+/**
+ * List wiki page keys without reading or parsing file contents.
+ *
+ * Keys are derived purely from file paths, so this stays cheap enough for
+ * shell tab-completion (unlike `listLocalKnowledgePages`, which reads every
+ * page to populate summaries).
+ */
+export async function listLocalKnowledgePageKeys(
+  project: KtxLocalProject,
+  input: { userId?: string } = {},
+): Promise<string[]> {
+  const userId = input.userId ?? 'local';
+  const keys = new Set<string>();
+  for (const scope of ['GLOBAL', 'USER'] as const) {
+    const root = scope === 'GLOBAL' ? 'wiki/global' : `wiki/user/${assertSafePathToken('user id', userId)}`;
+    const listed = await project.fileStore.listFiles(root);
+    for (const path of listed.files.filter((file) => file.endsWith('.md'))) {
+      const key = keyFromKnowledgePath(path, scope, userId);
+      if (key) {
+        keys.add(key);
+      }
+    }
+  }
+  return [...keys].sort();
+}
+
 function scorePage(page: LocalKnowledgePage, terms: string[]): number {
   const haystack = buildKnowledgeSearchText(page.key, page.summary, page.content, page.tags).toLowerCase();
   return terms.some((term) => haystack.includes(term)) ? 3 : 0;