@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/src/cli/telegram-cli.ts

@@ -0,0 +1,156 @@
+/**
+ * `skc telegram` command handlers — start/status/env for the Telegram Remote
+ * integration, driven entirely by the `telegram.*` settings group.
+ */
+
+import { logger } from "@sayknow-cli/utils";
+import { isSettingsInitialized, Settings, settings } from "../config/settings";
+import type { TelegramSettings } from "../config/settings-schema";
+import { telegramSettingsToEnv, validateTelegramSettings } from "../config/telegram-env-bridge";
+import { resolveSkcRuntimeSpawnInfo } from "../daemon/runtime";
+
+export type TelegramAction = "start" | "status" | "env" | "__gateway";
+
+export interface TelegramCommandArgs {
+	action: TelegramAction;
+	flags: {
+		json?: boolean;
+	};
+}
+
+export const TELEGRAM_ACTIONS: readonly TelegramAction[] = ["start", "status", "env", "__gateway"];
+
+/** Read the full telegram settings group from the settings singleton. */
+function readTelegramSettings(): TelegramSettings {
+	return {
+		enabled: settings.get("telegram.enabled"),
+		botToken: settings.get("telegram.botToken"),
+		allowedUserIds: settings.get("telegram.allowedUserIds"),
+		allowedChatIds: settings.get("telegram.allowedChatIds"),
+		backend: settings.get("telegram.backend"),
+		enableStop: settings.get("telegram.enableStop"),
+		enableRich: settings.get("telegram.enableRich"),
+		enablePush: settings.get("telegram.enablePush"),
+		registerCommands: settings.get("telegram.registerCommands"),
+		presets: settings.get("telegram.presets"),
+		rpcSocket: settings.get("telegram.rpcSocket"),
+		stateDir: settings.get("telegram.stateDir"),
+		pollTimeoutSec: settings.get("telegram.pollTimeoutSec"),
+		apiBase: settings.get("telegram.apiBase"),
+		coordinatorCommand: settings.get("telegram.coordinatorCommand") ?? "skc",
+		coordinatorArgs: settings.get("telegram.coordinatorArgs") ?? "mcp-serve,coordinator",
+		enableEditMessageText: settings.get("telegram.enableEditMessageText"),
+		richCallbackTtlMs: settings.get("telegram.richCallbackTtlMs"),
+		richCallbackMaxTokens: settings.get("telegram.richCallbackMaxTokens"),
+		defaultTaskMaxLen: settings.get("telegram.defaultTaskMaxLen"),
+		livenessMs: settings.get("telegram.livenessMs"),
+		followTtlMs: settings.get("telegram.followTtlMs"),
+		subscriptionsMax: settings.get("telegram.subscriptionsMax"),
+		longPollMs: settings.get("telegram.longPollMs"),
+		digestThreshold: settings.get("telegram.digestThreshold"),
+		allowAttachSocketArg: settings.get("telegram.allowAttachSocketArg"),
+	};
+}
+
+/** Resolve the gateway spawn command by re-invoking skc's own hidden
+ *  `telegram __gateway` subcommand: a compiled binary self-spawns the bundled
+ *  gateway entrypoint, and a source run re-executes cli.ts under bun. */
+function resolveGatewayCommand(): { cmd: string; args: string[] } {
+	const rt = resolveSkcRuntimeSpawnInfo();
+	return { cmd: rt.execPath, args: [...rt.argsPrefix, "telegram", "__gateway"] };
+}
+
+async function runStart(): Promise<void> {
+	const config = readTelegramSettings();
+
+	if (!config.enabled) {
+		process.stderr.write(
+			"Telegram Remote is disabled. Enable it in Settings → Integrations, or set telegram.enabled.\n",
+		);
+		process.exit(1);
+	}
+
+	const errors = validateTelegramSettings(config);
+	if (errors.length > 0) {
+		process.stderr.write("Telegram configuration is incomplete:\n");
+		for (const err of errors) process.stderr.write(`  • ${err}\n`);
+		process.exit(1);
+	}
+
+	const env = telegramSettingsToEnv(config);
+	const { cmd, args } = resolveGatewayCommand();
+
+	logger.info("telegram-remote starting", { cmd });
+
+	const proc = Bun.spawn([cmd, ...args], {
+		env: { ...process.env, ...env },
+		stdio: ["inherit", "inherit", "inherit"],
+	});
+
+	// Forward termination signals to the child.
+	const forward = (sig: NodeJS.Signals): void => void proc.kill(sig);
+	process.on("SIGINT", forward);
+	process.on("SIGTERM", forward);
+
+	const code = await proc.exited;
+	process.off("SIGINT", forward);
+	process.off("SIGTERM", forward);
+	process.exit(code);
+}
+
+async function runStatus(flags: TelegramCommandArgs["flags"]): Promise<void> {
+	const config = readTelegramSettings();
+	const errors = config.enabled ? validateTelegramSettings(config) : [];
+
+	if (flags.json) {
+		process.stdout.write(`${JSON.stringify({ enabled: config.enabled, valid: errors.length === 0, errors })}\n`);
+		return;
+	}
+
+	process.stdout.write(`Telegram Remote: ${config.enabled ? "enabled" : "disabled"}\n`);
+	process.stdout.write(`Backend: ${config.backend}\n`);
+
+	if (config.botToken) process.stdout.write(`Bot Token: ✓ set\n`);
+	else process.stdout.write(`Bot Token: ✗ missing\n`);
+
+	if (config.allowedUserIds || config.allowedChatIds) {
+		process.stdout.write(`Allowlist: ✓ configured\n`);
+	} else {
+		process.stdout.write(`Allowlist: ✗ missing\n`);
+	}
+
+	if (errors.length > 0) {
+		process.stdout.write("\nConfiguration issues:\n");
+		for (const err of errors) process.stdout.write(`  • ${err}\n`);
+	}
+}
+
+async function runEnv(): Promise<void> {
+	const config = readTelegramSettings();
+	const env = telegramSettingsToEnv(config);
+	for (const [key, value] of Object.entries(env)) {
+		process.stdout.write(`${key}=${value}\n`);
+	}
+}
+
+export async function runTelegramCommand(cmd: TelegramCommandArgs): Promise<void> {
+	if (!isSettingsInitialized()) await Settings.init();
+	switch (cmd.action) {
+		case "start":
+			await runStart();
+			return;
+		case "status":
+			await runStatus(cmd.flags);
+			return;
+		case "env":
+			await runEnv();
+			return;
+		case "__gateway": {
+			// Hidden entrypoint: run the Telegram Remote gateway in-process. Reached
+			// only via the self-spawn from runStart()/autostart, never by users.
+			const { loadConfigFromEnv, runService } = await import("../../../telegram-remote/src/index");
+			await runService(loadConfigFromEnv(process.env));
+			return;
+		}
+	}
+}

package/src/cli/update-cli.ts

@@ -10,6 +10,7 @@ import { pipeline } from "node:stream/promises";
 import { $which, APP_NAME, isEnoent, VERSION } from "@sayknow-cli/utils";
 import { $ } from "bun";
 import chalk from "chalk";
+import { installDefaultSkcDefinitions } from "../defaults/skc-defaults";
 import { theme } from "../modes/theme/theme";
 
 const RELEASE_REPO = "jaybeyond/Sayknow_CLI";
@@ -551,31 +552,107 @@ async function updateViaNpm(packageName: string, expectedVersion: string): Promi
 }
 
 /**
- * Download a release binary to a target path, replacing an existing file.
+ * Flush a freshly written file's data to stable storage.
+ *
+ * Critical on network filesystems (e.g. NFS home directories): `pipeline`
+ * resolving does not guarantee the downloaded bytes are durable on the
+ * server, so the post-install `skc --version` check can exec a binary whose
+ * pages are not yet consistent. The child then faults, the version check
+ * fails, and the update is rolled back with "could not verify updated
+ * version" even though the download itself succeeded. Explicitly fsyncing
+ * before the rename/exec avoids the race.
  */
-async function updateViaBinaryAt(targetPath: string, expectedVersion: string): Promise<void> {
-	const binaryName = getBinaryName();
-	const url = buildReleaseBinaryUrl(expectedVersion);
+async function fsyncFile(filePath: string): Promise<void> {
+	const handle = await fs.promises.open(filePath, "r+");
+	try {
+		await handle.sync();
+	} finally {
+		await handle.close();
+	}
+}
 
-	const tempPath = `${targetPath}.new`;
-	const backupPath = `${targetPath}.bak`;
-	console.log(chalk.dim(`Downloading ${binaryName}…`));
+export async function fsyncFileForTest(filePath: string): Promise<void> {
+	return fsyncFile(filePath);
+}
 
+/**
+ * Download a release binary to a temp path, throwing a friendly error when the
+ * release asset cannot be fetched.
+ */
+async function downloadBinaryTo(url: string, tempPath: string, binaryName: string): Promise<void> {
 	const response = await fetch(url, { redirect: "follow" });
 	if (!response.ok || !response.body) {
 		throw new Error(formatBinaryDownloadFailureMessage(binaryName, url, response.statusText || response.status));
 	}
 	const fileStream = fs.createWriteStream(tempPath, { mode: 0o755 });
 	await pipeline(response.body, fileStream);
+}
+
+/** Injectable steps of the binary update flow (seams for testing ordering). */
+export interface BinaryUpdateFlow {
+	download(url: string, tempPath: string): Promise<void>;
+	fsync(filePath: string): Promise<void>;
+	replace(options: BinaryReplacementOptions): Promise<InstalledVersionVerification>;
+	verifyInstalledVersion(expectedVersion: string): Promise<InstalledVersionVerification>;
+	/** Best-effort cleanup of the temp file when the flow aborts before replace. */
+	removeTemp?(filePath: string): Promise<void>;
+	/** Called once fsync has succeeded, right before replacement begins. */
+	beforeReplace?(): void;
+}
 
-	console.log(chalk.dim("Installing update..."));
-	const verification = await replaceBinaryForUpdate({
+/**
+ * Orchestrate download → fsync → replace → verify with a strict ordering
+ * contract: the downloaded temp binary MUST be flushed to stable storage
+ * before it is published (renamed into place) or exec'd for verification.
+ *
+ * If fsync fails the temp bytes are not durable, so we abort before
+ * replacement/verification and clean up the temp file rather than installing a
+ * possibly-truncated binary.
+ */
+export async function runBinaryUpdateFlow(
+	targetPath: string,
+	url: string,
+	expectedVersion: string,
+	flow: BinaryUpdateFlow,
+): Promise<InstalledVersionVerification> {
+	const tempPath = `${targetPath}.new`;
+	const backupPath = `${targetPath}.bak`;
+
+	await flow.download(url, tempPath);
+	try {
+		await flow.fsync(tempPath);
+	} catch (err) {
+		if (flow.removeTemp) await flow.removeTemp(tempPath);
+		throw err;
+	}
+
+	flow.beforeReplace?.();
+	return flow.replace({
 		targetPath,
 		tempPath,
 		backupPath,
 		expectedVersion,
+		verifyInstalledVersion: flow.verifyInstalledVersion,
+	});
+}
+
+/**
+ * Download a release binary to a target path, replacing an existing file.
+ */
+async function updateViaBinaryAt(targetPath: string, expectedVersion: string): Promise<void> {
+	const binaryName = getBinaryName();
+	const url = buildReleaseBinaryUrl(expectedVersion);
+	console.log(chalk.dim(`Downloading ${binaryName}…`));
+
+	const verification = await runBinaryUpdateFlow(targetPath, url, expectedVersion, {
+		download: (downloadUrl, tempPath) => downloadBinaryTo(downloadUrl, tempPath, binaryName),
+		fsync: fsyncFile,
+		replace: replaceBinaryForUpdate,
 		verifyInstalledVersion: verifyInstalledRuntime,
+		removeTemp: unlinkIfExists,
+		beforeReplace: () => console.log(chalk.dim("Installing update...")),
 	});
+
 	printVerifiedVersion(expectedVersion);
 	if (verification.cleanupWarning) console.warn(chalk.yellow(verification.cleanupWarning));
 	printRestartGuidance();
@@ -628,6 +705,29 @@ export async function runUpdateCommand(opts: { force: boolean; check: boolean })
 		console.error(chalk.red(`Update failed: ${err}`));
 		process.exit(1);
 	}
+
+	await refreshInstalledDefaultSkills();
+}
+
+/**
+ * Refresh opted-in on-disk default workflow skill copies after a successful
+ * update. The four default skills ship embedded in the binary, so most users
+ * need nothing here. But users who ran `skc setup defaults` have on-disk copies
+ * under the agent dir that shadow the embedded defaults; those would otherwise
+ * go stale after an update. Only rewrite files that already exist and differ —
+ * never materialize new copies for users who never opted in.
+ */
+async function refreshInstalledDefaultSkills(): Promise<void> {
+	try {
+		const result = await installDefaultSkcDefinitions({ refreshOnly: true });
+		if (result.written > 0) {
+			console.log(
+				chalk.dim(`Refreshed ${result.written} local default workflow skill file(s) at ${result.targetRoot}`),
+			);
+		}
+	} catch (err) {
+		console.error(chalk.yellow(`Warning: failed to refresh local default workflow skills: ${err}`));
+	}
 }
 
 /**

package/src/cli/web-search-cli.ts

@@ -9,13 +9,14 @@ import chalk from "chalk";
 import { Settings } from "../config/settings";
 import { initTheme, theme } from "../modes/theme/theme";
 import {
+	getConfiguredSearchProviderPreference,
 	isConfigurableSearchProviderId,
 	isSearchProviderPreference,
 	runSearchQuery,
 	type SearchQueryParams,
 } from "../web/search/index";
 import { SEARCH_PROVIDER_ORDER, setPreferredSearchProvider, setSearchFallbackProviders } from "../web/search/provider";
-import { setSearchHardTimeoutMs } from "../web/search/providers/utils";
+import { applyConfiguredSearchTimeout } from "../web/search/providers/utils";
 import { renderSearchResult } from "../web/search/render";
 import type { SearchProviderId } from "../web/search/types";
 
@@ -170,8 +171,8 @@ export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 
 	await initTheme();
 	const settings = await Settings.init();
-	const configuredProvider = settings.get("providers.webSearch");
-	if (typeof configuredProvider === "string" && isSearchProviderPreference(configuredProvider)) {
+	const configuredProvider = getConfiguredSearchProviderPreference(settings);
+	if (isSearchProviderPreference(configuredProvider)) {
 		setPreferredSearchProvider(configuredProvider);
 	}
 	const configuredFallback = settings.get("web_search.fallback");
@@ -180,10 +181,7 @@ export async function runSearchCommand(cmd: SearchCommandArgs): Promise<void> {
 			configuredFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
 		);
 	}
-	const configuredTimeout = settings.get("web_search.timeout");
-	if (typeof configuredTimeout === "number" && Number.isFinite(configuredTimeout) && configuredTimeout > 0) {
-		setSearchHardTimeoutMs(configuredTimeout * 1000);
-	}
+	applyConfiguredSearchTimeout(settings);
 
 	const params: SearchQueryParams = {
 		query: cmd.query,

package/src/cli.ts

@@ -6,6 +6,7 @@
  */
 import { Args, type CliConfig, Command, type CommandEntry, Flags, run } from "@sayknow-cli/utils/cli";
 import { APP_NAME, formatBunRuntimeError, MIN_BUN_VERSION, VERSION } from "@sayknow-cli/utils/dirs";
+import { runFixtureReport } from "./cli/fixture-report";
 
 if (Bun.semver.order(Bun.version, MIN_BUN_VERSION) < 0) {
 	process.stderr.write(
@@ -35,6 +36,7 @@ export const commands: CommandEntry[] = [
 	{ name: "gc", load: () => import("./commands/gc").then(m => m.default) },
 	{ name: "ralplan", load: () => import("./commands/ralplan").then(m => m.default) },
 	{ name: "config", load: () => import("./commands/config").then(m => m.default) },
+	{ name: "stats", load: () => import("./commands/stats").then(m => m.default) },
 	{ name: "notify", load: () => import("./commands/notify").then(m => m.default) },
 	{ name: "daemon", load: () => import("./commands/daemon").then(m => m.default) },
 	{ name: "web-search", aliases: ["q"], load: () => import("./commands/web-search").then(m => m.default) },
@@ -51,7 +53,9 @@ export const commands: CommandEntry[] = [
 	{ name: "rlm", load: () => import("./commands/rlm").then(m => m.default) },
 	{ name: "update", load: () => import("./commands/update").then(m => m.default) },
 	{ name: "plugin", load: () => import("./commands/plugin").then(m => m.default) },
+	{ name: "completion", load: () => import("./commands/completion").then(m => m.default) },
 	{ name: "launch", load: () => import("./commands/launch").then(m => m.default) },
+	{ name: "telegram", load: () => import("./commands/telegram").then(m => m.default) },
 ];
 
 async function showHelp(config: CliConfig): Promise<void> {
@@ -73,6 +77,9 @@ async function installRuntimeGlobals(): Promise<void> {
 	// `HTTP2Unsupported`. See @sayknow-cli/ai/utils/h2-fetch for details.
 	installH2Fetch();
 
+	const { warnIfMacOSNoFileLimitTooLow } = await import("./cli/nofile-limit");
+	warnIfMacOSNoFileLimitTooLow();
+
 	// Strip macOS malloc-stack-logging env vars before any subprocess is spawned.
 	// Otherwise every child bun process (subagents, plugin installs, ptree spawns,
 	// etc.) prints a `MallocStackLogging: can't turn off …` warning to stderr.
@@ -93,6 +100,17 @@ async function runNotifyDaemonInternalFastPath(argv: string[]): Promise<void> {
 	await runNotifyCommand(cmd);
 }
 
+function rootFixtureArg(argv: string[]): { present: boolean; id: string | undefined } {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		// Stop at the first subcommand token so a `--fixture` flag belonging to a
+		// subcommand never hijacks the root fast-path into fixture-report mode.
+		if (isSubcommand(arg)) return { present: false, id: undefined };
+		if (arg === "--fixture") return { present: true, id: argv[i + 1] };
+	}
+	return { present: false, id: undefined };
+}
+
 function hasRootFastFlag(argv: string[], flags: readonly string[]): boolean {
 	for (const arg of argv) {
 		if (isSubcommand(arg)) return false;
@@ -109,7 +127,7 @@ function hasRootVersionFlag(argv: string[]): boolean {
 	return hasRootFastFlag(argv, versionFlags);
 }
 
-class RootHelpCommand extends Command {
+export class RootHelpCommand extends Command {
 	static description = "Sayknow-CLI — an AI coding assistant";
 	static hidden = true;
 	static args = {
@@ -140,7 +158,7 @@ class RootHelpCommand extends Command {
 		resume: Flags.string({ char: "r", description: "Resume a session (by ID prefix, path, or picker if omitted)" }),
 		"session-dir": Flags.string({ description: "Directory for session storage and lookup" }),
 		"no-session": Flags.boolean({ description: "Don't save session (ephemeral)" }),
-		models: Flags.string({ description: "Comma-separated model patterns for Ctrl+P cycling" }),
+		models: Flags.string({ description: "Comma-separated model patterns for Alt+N cycling" }),
 		"no-tools": Flags.boolean({ description: "Disable all built-in tools" }),
 		"no-lsp": Flags.boolean({ description: "Disable LSP tools, formatting, and diagnostics" }),
 		"no-pty": Flags.boolean({ description: "Disable PTY-based interactive bash execution" }),
@@ -230,6 +248,17 @@ export async function runCli(argv: string[]): Promise<void> {
 		await runSmokeTest();
 		return;
 	}
+	const fixtureArg = rootFixtureArg(argv);
+	if (fixtureArg.present) {
+		const id = fixtureArg.id;
+		if (!id || id.startsWith("-")) {
+			process.stderr.write(`${APP_NAME} --fixture requires a fixture id\n`);
+			process.exitCode = 1;
+			return;
+		}
+		process.exitCode = await runFixtureReport(id);
+		return;
+	}
 	if (hasRootHelpFlag(argv)) {
 		const { renderRootHelp } = await import("@sayknow-cli/utils/cli");
 		const { getExtraHelpText } = await import("./cli/fast-help");

package/src/commands/completion.ts

@@ -0,0 +1,84 @@
+/**
+ * Generate shell completion specs for external completion engines.
+ */
+import { Args, Command, Flags } from "@sayknow-cli/utils/cli";
+import { commands, RootHelpCommand } from "../cli";
+import {
+	buildSkcFigSpec,
+	defaultInshellisenseSpecDir,
+	type InstallSkcInshellisenseSpecResult,
+	installSkcInshellisenseSpec,
+	renderFigSpecModule,
+} from "../cli/completion-cli";
+
+const TARGETS = ["inshellisense", "fig"] as const;
+
+type CompletionTarget = (typeof TARGETS)[number];
+
+function normalizeTarget(target: CompletionTarget): "inshellisense" {
+	return target === "fig" ? "inshellisense" : target;
+}
+
+function formatInstallResult(result: InstallSkcInshellisenseSpecResult, customDir: boolean): string {
+	const lines = [
+		"Installed SKC inshellisense completion spec:",
+		`  spec:  ${result.specPath}`,
+		`  index: ${result.indexPath} (${result.indexStatus})`,
+	];
+	if (customDir) {
+		lines.push(
+			"Add the install directory to inshellisense's [specs].path setting, then restart the inshellisense session.",
+		);
+	} else {
+		lines.push("Restart the inshellisense session, or run `is reinit` if your shell integration needs a refresh.");
+	}
+	return `${lines.join("\n")}\n`;
+}
+
+export default class Completion extends Command {
+	static description = "Generate shell completion specs";
+
+	static args = {
+		target: Args.string({
+			description: "Completion format",
+			required: false,
+			options: TARGETS,
+		}),
+	};
+
+	static flags = {
+		install: Flags.boolean({ description: "Install the generated spec for inshellisense" }),
+		dir: Flags.string({ description: "Install directory (defaults to ~/.fig/autocomplete/build)" }),
+		force: Flags.boolean({ description: "Overwrite an existing non-SKC inshellisense index.js" }),
+		json: Flags.boolean({ description: "Output JSON instead of JavaScript or status text" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Completion);
+		const target = normalizeTarget((args.target ?? "inshellisense") as CompletionTarget);
+		if (target !== "inshellisense") {
+			process.stderr.write(`Unsupported completion target: ${target}\n`);
+			process.exitCode = 1;
+			return;
+		}
+		if ((flags.dir || flags.force) && !flags.install) {
+			process.stderr.write("--dir and --force only apply with --install\n");
+			process.exitCode = 1;
+			return;
+		}
+
+		const spec = await buildSkcFigSpec(commands, RootHelpCommand);
+		if (!flags.install) {
+			process.stdout.write(flags.json ? `${JSON.stringify(spec, null, 2)}\n` : renderFigSpecModule(spec));
+			return;
+		}
+
+		const directory = flags.dir ?? defaultInshellisenseSpecDir();
+		const result = await installSkcInshellisenseSpec(spec, { dir: directory, force: flags.force });
+		if (flags.json) {
+			process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+			return;
+		}
+		process.stdout.write(formatInstallResult(result, flags.dir !== undefined));
+	}
+}

package/src/commands/config.ts

@@ -29,6 +29,7 @@ export default class Config extends Command {
 
 	static flags = {
 		json: Flags.boolean({ description: "Output JSON" }),
+		"show-secrets": Flags.boolean({ description: "Show secret-like setting values without redaction (unsafe)" }),
 	};
 
 	async run(): Promise<void> {
@@ -42,6 +43,7 @@ export default class Config extends Command {
 			value,
 			flags: {
 				json: flags.json,
+				showSecrets: flags["show-secrets"],
 			},
 		};
 

package/src/commands/contribution-prep.ts

@@ -1,5 +1,4 @@
 import { Command, Flags } from "@sayknow-cli/utils/cli";
-import { prepareContributionPrep } from "../session/contribution-prep";
 
 function writeText(lines: string[]): void {
 	process.stdout.write(`${lines.join("\n")}\n`);
@@ -19,6 +18,7 @@ export default class ContributionPrep extends Command {
 
 	async run(): Promise<void> {
 		const { flags } = await this.parse(ContributionPrep);
+		const { prepareContributionPrep } = await import("../session/contribution-prep");
 		const cwd = process.cwd();
 		const result = await prepareContributionPrep(
 			{

package/src/commands/deep-interview.ts

@@ -8,6 +8,7 @@ export default class DeepInterview extends Command {
 		quick: Flags.boolean({ description: "Seed a quick deep-interview run" }),
 		standard: Flags.boolean({ description: "Seed a standard deep-interview run" }),
 		deep: Flags.boolean({ description: "Seed a deep deep-interview run" }),
+		trace: Flags.boolean({ description: "Run a bounded trace evidence pre-step before interview questions" }),
 		threshold: Flags.string({ description: "Override ambiguity threshold for kickoff" }),
 		"threshold-source": Flags.string({ description: "Describe the threshold override source" }),
 		"session-id": Flags.string({
@@ -25,7 +26,7 @@ export default class DeepInterview extends Command {
 		json: Flags.boolean({ description: "Output JSON" }),
 	};
 	static examples = [
-		'$ skc deep-interview --standard "<idea>"',
+		'$ skc deep-interview --trace --standard "<idea>"',
 		"$ skc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md",
 		"$ skc deep-interview --write --stage final --slug my-feature --spec ./final-spec.md --deliberate",
 	];

package/src/commands/launch.ts

@@ -119,7 +119,7 @@ export default class Index extends Command {
 			description: "Don't save session (ephemeral)",
 		}),
 		models: Flags.string({
-			description: "Comma-separated model patterns for Ctrl+P cycling",
+			description: "Comma-separated model patterns for Alt+N cycling",
 		}),
 		"no-tools": Flags.boolean({
 			description: "Disable all built-in tools",

package/src/commands/ralplan.ts

@@ -8,6 +8,7 @@ export default class Ralplan extends Command {
 		'$ skc ralplan "<task description>"',
 		'$ skc ralplan --interactive --deliberate "<task description>"',
 		'$ skc ralplan --write --stage planner --stage_n 1 --artifact "<markdown or path>"',
+		"$ skc ralplan --write --stage critic --stage_n 1 --artifact-env SKC_RALPLAN_ARTIFACT",
 	];
 
 	async run(): Promise<void> {

package/src/commands/telegram.ts

@@ -0,0 +1,47 @@
+/**
+ * `skc telegram` — manage the Telegram Remote integration.
+ */
+import { Args, Command, Flags, renderCommandHelp } from "@sayknow-cli/utils/cli";
+import {
+	runTelegramCommand,
+	TELEGRAM_ACTIONS,
+	type TelegramAction,
+	type TelegramCommandArgs,
+} from "../cli/telegram-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Telegram extends Command {
+	static description = "Manage the Telegram Remote integration (start/status/env)";
+
+	static args = {
+		action: Args.string({
+			description: "Sub-command",
+			required: false,
+			options: [...TELEGRAM_ACTIONS],
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON (status)" }),
+	};
+
+	static examples = [
+		"# Start the Telegram gateway with current settings\n  skc telegram start",
+		"# Show integration status\n  skc telegram status",
+		"# Show the env vars the gateway would receive\n  skc telegram env",
+	];
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Telegram);
+		if (!args.action) {
+			renderCommandHelp("skc", "telegram", Telegram);
+			return;
+		}
+		const cmd: TelegramCommandArgs = {
+			action: args.action as TelegramAction,
+			flags: { json: flags.json },
+		};
+		await initTheme();
+		await runTelegramCommand(cmd);
+	}
+}