@saibolla/ada 0.1.2

package/extensions/research-tools/header.ts

@@ -0,0 +1,284 @@
+import { readdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { execFileSync } from "node:child_process";
+import { resolve as resolvePath } from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+import { isLoggedIn as isAlphaLoggedIn } from "@ada/alpha-hub/lib";
+import {
+	APP_ROOT,
+	ADA_AGENT_LOGO,
+	ADA_VERSION,
+} from "./shared.js";
+
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function visibleLength(text: string): number {
+	return text.replace(ANSI_RE, "").length;
+}
+
+function formatHeaderPath(path: string): string {
+	const home = homedir();
+	return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+
+function truncateVisible(text: string, maxVisible: number): string {
+	const raw = text.replace(ANSI_RE, "");
+	if (raw.length <= maxVisible) return text;
+	if (maxVisible <= 3) return ".".repeat(maxVisible);
+	return `${raw.slice(0, maxVisible - 3)}...`;
+}
+
+function padRight(text: string, width: number): string {
+	const gap = Math.max(0, width - visibleLength(text));
+	return `${text}${" ".repeat(gap)}`;
+}
+
+function getCurrentModelLabel(ctx: ExtensionContext): string {
+	if (ctx.model) return `${ctx.model.provider}/${ctx.model.id}`;
+	const branch = ctx.sessionManager.getBranch();
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const entry = branch[index]!;
+		if (entry.type === "model_change") return `${(entry as any).provider}/${(entry as any).modelId}`;
+	}
+	return "not set";
+}
+
+async function buildAgentCatalogSummary(): Promise<{ agents: string[]; chains: string[] }> {
+	const agents: string[] = [];
+	const chains: string[] = [];
+	try {
+		const entries = await readdir(resolvePath(APP_ROOT, ".ada", "agents"), { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+			if (entry.name.endsWith(".chain.md")) {
+				chains.push(entry.name.replace(/\.chain\.md$/i, ""));
+			} else {
+				agents.push(entry.name.replace(/\.md$/i, ""));
+			}
+		}
+	} catch {
+		return { agents: [], chains: [] };
+	}
+	agents.sort();
+	chains.sort();
+	return { agents, chains };
+}
+
+async function countSkills(): Promise<number> {
+	try {
+		const entries = await readdir(resolvePath(APP_ROOT, "skills"), { withFileTypes: true });
+		return entries.filter((e) => e.isDirectory()).length;
+	} catch {
+		return 0;
+	}
+}
+
+function detectDocker(): boolean {
+	try {
+		execFileSync("docker", ["--version"], { timeout: 500, stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+type WorkflowInfo = { name: string; description: string };
+
+function getResearchWorkflows(pi: ExtensionAPI): WorkflowInfo[] {
+	return pi.getCommands()
+		.filter((cmd) => cmd.source === "prompt")
+		.map((cmd) => ({ name: `/${cmd.name}`, description: cmd.description ?? "" }))
+		.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function shortDescription(desc: string): string {
+	const lower = desc.toLowerCase();
+	for (const prefix of ["run a ", "run an ", "set up a ", "build a ", "build the ", "turn ", "design the ", "produce a ", "compare ", "simulate ", "inspect ", "write a ", "plan or execute a ", "prepare a "]) {
+		if (lower.startsWith(prefix)) return desc.slice(prefix.length);
+	}
+	return desc;
+}
+
+function briefDesc(desc: string, maxWords = 8): string {
+	const words = shortDescription(desc).split(" ");
+	if (words.length <= maxWords) return words.join(" ");
+	return `${words.slice(0, maxWords).join(" ")}...`;
+}
+
+export function installAdaHeader(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	cache: { agentSummaryPromise?: Promise<{ agents: string[]; chains: string[] }>; skillCountPromise?: Promise<number> },
+): void | Promise<void> {
+	if (!ctx.hasUI) return;
+
+	cache.agentSummaryPromise ??= buildAgentCatalogSummary();
+	cache.skillCountPromise ??= countSkills();
+
+	return Promise.all([cache.agentSummaryPromise, cache.skillCountPromise]).then(([agentData, skillCount]) => {
+		const workflows = getResearchWorkflows(pi);
+		const toolCount = pi.getAllTools().length;
+		const agentCount = agentData.agents.length + agentData.chains.length;
+		const hasDocker = detectDocker();
+
+		ctx.ui.setHeader((_tui, theme) => ({
+			render(width: number): string[] {
+				const cardW = Math.min(width - 4, 120);
+				const innerW = cardW - 2;
+				const contentW = innerW - 2;
+				const lines: string[] = [];
+
+				const push = (line: string) => { lines.push(line); };
+				const border = (ch: string) => theme.fg("borderMuted", ch);
+
+				const row = (content: string): string =>
+					`${border("│")} ${padRight(content, contentW)} ${border("│")}`;
+				const emptyRow = (): string =>
+					`${border("│")}${" ".repeat(innerW)}${border("│")}`;
+				const sep = (): string =>
+					`${border("├")}${border("─".repeat(innerW))}${border("┤")}`;
+
+				const useWideLayout = contentW >= 90;
+				const leftW = useWideLayout ? Math.min(38, Math.floor(contentW * 0.35)) : 0;
+				const divColW = useWideLayout ? 3 : 0;
+				const rightW = useWideLayout ? contentW - leftW - divColW : contentW;
+
+				const twoCol = (left: string, right: string): string => {
+					if (!useWideLayout) return row(left || right);
+					return row(
+						`${padRight(left, leftW)}${border(" │ ")}${padRight(right, rightW)}`,
+					);
+				};
+
+				const modelLabel = getCurrentModelLabel(ctx);
+				const dirLabel = formatHeaderPath(ctx.cwd);
+
+				// ── Logo ──
+				push("");
+				if (cardW >= 70) {
+					for (const logoLine of ADA_AGENT_LOGO) {
+						push(theme.fg("accent", theme.bold(` ${logoLine}`)));
+					}
+				}
+
+				// ── Tagline ──
+				push(theme.fg("dim", " The AI research agent. Type naturally or use /commands."));
+				push("");
+
+				// ── Version border ──
+				const versionTag = ` v${ADA_VERSION} `;
+				const vGap = Math.max(0, innerW - versionTag.length);
+				const vGapL = Math.floor(vGap / 2);
+				push(
+					border(`╭${"─".repeat(vGapL)}`) +
+					theme.fg("dim", versionTag) +
+					border(`${"─".repeat(vGap - vGapL)}╮`),
+				);
+
+				if (useWideLayout) {
+					const cmdNameW = 16;
+					const leftValueW = Math.max(1, leftW - 11);
+					const leftLines: string[] = [""];
+
+					// ── Left: Model + Directory ──
+					leftLines.push(`${theme.fg("dim", "model".padEnd(10))} ${theme.fg("text", truncateVisible(modelLabel, leftValueW))}`);
+					leftLines.push(`${theme.fg("dim", "directory".padEnd(10))} ${theme.fg("text", truncateVisible(dirLabel, leftValueW))}`);
+
+					// ── Left: Stats ──
+					leftLines.push("");
+					leftLines.push(theme.fg("dim", truncateVisible(`${toolCount} tools · ${agentCount} agents`, leftW)));
+					leftLines.push(theme.fg("dim", truncateVisible(`${workflows.length} workflows · ${skillCount} skills`, leftW)));
+
+					// ── Left: Services ──
+					leftLines.push("");
+					leftLines.push(theme.fg("accent", theme.bold("Services")));
+					const ok = (v: boolean) => v ? theme.fg("success", "✓") : theme.fg("dim", "✗");
+
+					// Required
+					leftLines.push(`alphaXiv ${ok(isAlphaLoggedIn())}  docker ${ok(hasDocker)}`);
+
+					// Optional — collect configured ones, show two per line
+					const configured: string[] = [];
+					if (process.env.ZOTERO_API_KEY) configured.push("zotero");
+					if (process.env.TAVILY_API_KEY) configured.push("tavily");
+					if (process.env.S2_API_KEY) configured.push("s2");
+					if (process.env.OPENALEX_API_KEY) configured.push("openalex");
+					if (process.env.OPENROUTER_API_KEY) configured.push("openrouter");
+					if (process.env.MODAL_TOKEN_ID) configured.push("modal");
+					if (process.env.RUNPOD_API_KEY) configured.push("runpod");
+					if (process.env.NCBI_API_KEY) configured.push("ncbi");
+					for (let i = 0; i < configured.length; i += 2) {
+						const a = `${configured[i]} ${ok(true)}`;
+						const b = configured[i + 1] ? `  ${configured[i + 1]} ${ok(true)}` : "";
+						leftLines.push(a + b);
+					}
+
+					// ── Right: Quick Start (workflows + help) ──
+					const qsW = 16;
+					const wfDescs: Record<string, string> = {
+						"/audit": "verify paper claims against its codebase",
+						"/autoresearch": "autonomous experiment loop",
+						"/compare": "compare sources on a topic",
+						"/deepresearch": "thorough multi-source investigation",
+						"/draft": "write a paper-style draft",
+						"/litreview": "literature review with citations",
+						"/replicate": "replicate a paper's experiments",
+						"/review": "simulated peer review",
+						"/watch": "recurring research watch",
+					};
+					const rightLines: string[] = [
+						"",
+						`${theme.fg("accent", theme.bold("Quick Start"))}  ${theme.fg("text", '"just ask anything"')}`,
+						"",
+					];
+					const wfDescMaxW = Math.max(5, rightW - qsW);
+					for (const wf of workflows) {
+						if (wf.name === "/jobs" || wf.name === "/log" || wf.name === "/watch") continue;
+						const desc = wfDescs[wf.name] ?? shortDescription(wf.description);
+						rightLines.push(
+							`${theme.fg("accent", wf.name.padEnd(qsW))}${theme.fg("dim", truncateVisible(desc, wfDescMaxW))}`,
+						);
+					}
+					rightLines.push("");
+					rightLines.push(`${theme.fg("accent", "/help".padEnd(qsW))}${theme.fg("dim", "all commands")}`);
+
+					const maxRows = Math.max(leftLines.length, rightLines.length);
+					for (let i = 0; i < maxRows; i++) {
+						push(twoCol(leftLines[i] ?? "", rightLines[i] ?? ""));
+					}
+				} else {
+					// ── Narrow layout ──
+					const narrowValW = Math.max(1, contentW - 11);
+					push(emptyRow());
+					push(row(`${theme.fg("dim", "model".padEnd(10))} ${theme.fg("text", truncateVisible(modelLabel, narrowValW))}`));
+					push(row(`${theme.fg("dim", "directory".padEnd(10))} ${theme.fg("text", truncateVisible(dirLabel, narrowValW))}`));
+					push(emptyRow());
+					push(row(theme.fg("dim", `${toolCount} tools · ${agentCount} agents · ${skillCount} skills · ${workflows.length} workflows`)));
+					push(emptyRow());
+
+					push(sep());
+					push(row(theme.fg("accent", theme.bold("Quick Start"))));
+					push(row(`  ${theme.fg("text", '"ask anything"')}`));
+					push(row(`  ${theme.fg("accent", "/deepresearch")} ${theme.fg("dim", "<topic>")}`));
+					push(row(`  ${theme.fg("accent", "/lit")} ${theme.fg("dim", "<topic>")}`));
+					push(row(`  ${theme.fg("accent", "/help")} ${theme.fg("dim", "all commands")}`));
+
+					push(sep());
+					push(row(theme.fg("accent", theme.bold("Workflows"))));
+					const narrowDescW = Math.max(1, contentW - 17);
+					for (const wf of workflows) {
+						if (wf.name === "/jobs" || wf.name === "/log" || wf.name === "/watch") continue;
+						push(row(`${theme.fg("accent", wf.name.padEnd(16))} ${theme.fg("dim", truncateVisible(briefDesc(wf.description), narrowDescW))}`));
+					}
+				}
+
+				push(border(`╰${"─".repeat(innerW)}╯`));
+				push("");
+				return lines;
+			},
+			invalidate() {},
+		}));
+	});
+}

package/extensions/research-tools/help.ts

@@ -0,0 +1,93 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+	extensionCommandSpecs,
+	formatSlashUsage,
+	getExtensionCommandSpec,
+	livePackageCommandGroups,
+	readPromptSpecs,
+} from "../../metadata/commands.mjs";
+import { APP_ROOT } from "./shared.js";
+
+type HelpCommand = { usage: string; description: string };
+type HelpSection = { title: string; commands: HelpCommand[] };
+
+function buildHelpSections(pi: ExtensionAPI): HelpSection[] {
+	const liveCommands = new Map(pi.getCommands().map((command) => [command.name, command]));
+	const promptSpecs = readPromptSpecs(APP_ROOT);
+	const sections = new Map<string, HelpCommand[]>();
+
+	for (const command of promptSpecs.filter((entry) => entry.section !== "Internal")) {
+		const live = liveCommands.get(command.name);
+		if (!live) continue;
+		const items = sections.get(command.section) ?? [];
+		items.push({
+			usage: formatSlashUsage(command),
+			description: live.description ?? command.description,
+		});
+		sections.set(command.section, items);
+	}
+
+	for (const command of extensionCommandSpecs.filter((entry) => entry.publicDocs)) {
+		const live = liveCommands.get(command.name);
+		if (!live) continue;
+		const items = sections.get(command.section) ?? [];
+		items.push({
+			usage: formatSlashUsage(command),
+			description: live.description ?? command.description,
+		});
+		sections.set(command.section, items);
+	}
+
+	const ownedNames = new Set([
+		...promptSpecs.filter((entry) => entry.section !== "Internal").map((entry) => entry.name),
+		...extensionCommandSpecs.filter((entry) => entry.publicDocs).map((entry) => entry.name),
+	]);
+
+	for (const group of livePackageCommandGroups) {
+		const commands: HelpCommand[] = [];
+		for (const spec of group.commands) {
+			const command = liveCommands.get(spec.name);
+			if (!command || ownedNames.has(command.name)) continue;
+			commands.push({
+				usage: spec.usage,
+				description: command.description ?? "",
+			});
+		}
+
+		if (commands.length > 0) {
+			sections.set(group.title, commands);
+		}
+	}
+
+	return [
+		"Research Workflows",
+		"Project & Session",
+		"Setup",
+		"Agents & Delegation",
+		"Bundled Package Commands",
+	]
+		.map((title) => ({ title, commands: sections.get(title) ?? [] }))
+		.filter((section) => section.commands.length > 0);
+}
+
+export function registerHelpCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("help", {
+		description:
+			getExtensionCommandSpec("help")?.description ??
+			"Show grouped Ada commands and prefill the editor with a selected command.",
+		handler: async (_args, ctx) => {
+			const sections = buildHelpSections(pi);
+			const items = sections.flatMap((section) => [
+				`--- ${section.title} ---`,
+				...section.commands.map((cmd) => `${cmd.usage} — ${cmd.description}`),
+			]);
+
+			const selected = await ctx.ui.select("Ada Help", items);
+			if (!selected || selected.startsWith("---")) return;
+
+			const usage = selected.split(" — ")[0];
+			ctx.ui.setEditorText(usage);
+			ctx.ui.notify(`Prefilled ${usage}`, "info");
+		},
+	});
+}

package/extensions/research-tools/project-scaffold.ts

@@ -0,0 +1,64 @@
+export function buildProjectAgentsTemplate(): string {
+	return `# Ada Project Guide
+
+This file is read automatically at startup. It is the durable project memory for Ada.
+
+## Project Overview
+- State the research question, target artifact, target venue, and key datasets or benchmarks here.
+
+## AI Research Context
+- Problem statement:
+- Core hypothesis:
+- Closest prior work:
+- Required baselines:
+- Required ablations:
+- Primary metrics:
+- Datasets / benchmarks:
+
+## Ground Rules
+- Do not modify raw data in \`Data/Raw/\` or equivalent raw-data folders.
+- Read first, act second: inspect project structure and existing notes before making changes.
+- Prefer durable artifacts in \`notes/\`, \`outputs/\`, \`experiments/\`, and \`papers/\`.
+- Keep strong claims source-grounded. Include direct URLs in final writeups.
+
+## Current Status
+- Replace this section with the latest project status, known issues, and next steps.
+
+## Task Ledger
+- Track concrete tasks with IDs, owner, status, and output path.
+- Mark tasks as \`todo\`, \`in_progress\`, \`done\`, \`blocked\`, or \`superseded\`.
+- Do not silently merge or skip tasks; record the decision here.
+
+## Verification Gates
+- List the checks that must pass before delivery.
+- For each critical claim, figure, or metric, record how it will be verified and where the raw artifact lives.
+- Do not use words like \`verified\`, \`confirmed\`, or \`reproduced\` unless the underlying check actually ran.
+
+## Honesty Contract
+- Separate direct observations from inferences.
+- If something is uncertain, say so explicitly.
+- If a result looks cleaner than expected, assume it needs another check before it goes into the final artifact.
+
+## Session Logging
+- Use \`/log\` at the end of meaningful sessions to write a durable session note into \`notes/session-logs/\`.
+
+## Review Readiness
+- Known reviewer concerns:
+- Missing experiments:
+- Missing writing or framing work:
+`;
+}
+
+export function buildSessionLogsReadme(): string {
+	return `# Session Logs
+
+Use \`/log\` to write one durable note per meaningful Ada session.
+
+Recommended contents:
+- what was done
+- strongest findings
+- artifacts written
+- unresolved questions
+- next steps
+`;
+}

package/extensions/research-tools/project.ts

@@ -0,0 +1,123 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative, resolve as resolvePath } from "node:path";
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { getExtensionCommandSpec } from "../../metadata/commands.mjs";
+import { buildProjectAgentsTemplate, buildSessionLogsReadme } from "./project-scaffold.js";
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+const ARTIFACT_DIRS = ["papers", "outputs", "experiments", "notes"];
+const ARTIFACT_EXTS = new Set([".md", ".tex", ".pdf", ".py", ".csv", ".json", ".html", ".txt", ".log"]);
+
+async function collectArtifacts(cwd: string): Promise<{ label: string; path: string }[]> {
+	const items: { label: string; path: string; mtime: number }[] = [];
+
+	for (const dir of ARTIFACT_DIRS) {
+		const dirPath = resolvePath(cwd, dir);
+		if (!(await pathExists(dirPath))) continue;
+
+		const walk = async (current: string): Promise<void> => {
+			let entries;
+			try {
+				entries = await readdir(current, { withFileTypes: true });
+			} catch {
+				return;
+			}
+			for (const entry of entries) {
+				const full = join(current, entry.name);
+				if (entry.isDirectory()) {
+					await walk(full);
+				} else if (ARTIFACT_EXTS.has(entry.name.slice(entry.name.lastIndexOf(".")))) {
+					const rel = relative(cwd, full);
+					let title = "";
+					try {
+						const head = await readFile(full, "utf8").then((c) => c.slice(0, 200));
+						const match = head.match(/^#\s+(.+)/m);
+						if (match) title = match[1]!.trim();
+					} catch {}
+					const info = await stat(full).catch(() => null);
+					const mtime = info?.mtimeMs ?? 0;
+					const size = info ? formatSize(info.size) : "";
+					const titlePart = title ? ` — ${title}` : "";
+					items.push({ label: `${rel}${titlePart}  (${size})`, path: rel, mtime });
+				}
+			}
+		};
+
+		await walk(dirPath);
+	}
+
+	items.sort((a, b) => b.mtime - a.mtime);
+	return items;
+}
+
+function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)}KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+export function registerInitCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("init", {
+		description: getExtensionCommandSpec("init")?.description ?? "Initialize AGENTS.md and session-log folders for a research project.",
+		handler: async (_args, ctx) => {
+			const agentsPath = resolvePath(ctx.cwd, "AGENTS.md");
+			const notesDir = resolvePath(ctx.cwd, "notes");
+			const sessionLogsDir = resolvePath(notesDir, "session-logs");
+			const sessionLogsReadmePath = resolvePath(sessionLogsDir, "README.md");
+			const created: string[] = [];
+			const skipped: string[] = [];
+
+			await mkdir(notesDir, { recursive: true });
+			await mkdir(sessionLogsDir, { recursive: true });
+
+			if (!(await pathExists(agentsPath))) {
+				await writeFile(agentsPath, buildProjectAgentsTemplate(), "utf8");
+				created.push("AGENTS.md");
+			} else {
+				skipped.push("AGENTS.md");
+			}
+
+			if (!(await pathExists(sessionLogsReadmePath))) {
+				await writeFile(sessionLogsReadmePath, buildSessionLogsReadme(), "utf8");
+				created.push("notes/session-logs/README.md");
+			} else {
+				skipped.push("notes/session-logs/README.md");
+			}
+
+			const createdSummary = created.length > 0 ? `created: ${created.join(", ")}` : "created: nothing";
+			const skippedSummary = skipped.length > 0 ? `; kept existing: ${skipped.join(", ")}` : "";
+			ctx.ui.notify(`${createdSummary}${skippedSummary}`, "info");
+		},
+	});
+}
+
+export function registerOutputsCommand(pi: ExtensionAPI): void {
+	pi.registerCommand("outputs", {
+		description: "Browse all research artifacts (papers, outputs, experiments, notes).",
+		handler: async (_args, ctx) => {
+			const items = await collectArtifacts(ctx.cwd);
+			if (items.length === 0) {
+				ctx.ui.notify("No artifacts found. Use /lit, /draft, /review, or /deepresearch to create some.", "info");
+				return;
+			}
+
+			const selected = await ctx.ui.select(`Artifacts (${items.length})`, items.map((i) => i.label));
+			if (!selected) return;
+
+			const match = items.find((i) => i.label === selected);
+			if (match) {
+				ctx.ui.setEditorText(`read ${match.path}`);
+			}
+		},
+	});
+}

package/extensions/research-tools/shared.ts

@@ -0,0 +1,16 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const APP_ROOT = resolvePath(dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export const ADA_VERSION = (() => {
+	try {
+		const pkg = JSON.parse(readFileSync(resolvePath(APP_ROOT, "package.json"), "utf8")) as { version?: string };
+		return pkg.version ?? "dev";
+	} catch {
+		return "dev";
+	}
+})();
+
+export { ADA_ASCII_LOGO as ADA_AGENT_LOGO } from "../../logo.mjs";

package/extensions/research-tools.ts

@@ -0,0 +1,42 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { registerAlphaTools } from "./research-tools/alpha.js";
+import { installAdaHeader } from "./research-tools/header.js";
+import { registerHelpCommand } from "./research-tools/help.js";
+import { registerInitCommand, registerOutputsCommand } from "./research-tools/project.js";
+
+export default function researchTools(pi: ExtensionAPI): void {
+	const cache: { agentSummaryPromise?: Promise<{ agents: string[]; chains: string[] }> } = {};
+
+	pi.on("session_start", async (_event, ctx) => {
+		await installAdaHeader(pi, ctx, cache);
+	});
+
+	pi.on("session_switch", async (_event, ctx) => {
+		await installAdaHeader(pi, ctx, cache);
+	});
+
+	registerAlphaTools(pi);
+	registerHelpCommand(pi);
+
+	const gracefulExit = () => {
+		// Reset terminal: show cursor, disable alt screen, reset attributes
+		process.stdout.write("\x1b[?25h\x1b[?1049l\x1b[0m\n");
+		if (process.stdin.isTTY) {
+			process.stdin.setRawMode?.(false);
+		}
+		process.exit(0);
+	};
+
+	pi.registerCommand("exit", {
+		description: "Exit ada",
+		handler: gracefulExit,
+	});
+
+	pi.registerCommand("quit", {
+		description: "Exit ada",
+		handler: gracefulExit,
+	});
+	registerInitCommand(pi);
+	registerOutputsCommand(pi);
+}

package/logo.d.mts

@@ -0,0 +1,3 @@
+export declare const ADA_ASCII_LOGO: string[];
+export declare const ADA_ASCII_LOGO_TEXT: string;
+export declare const ADA_LOGO_HTML: string;

package/logo.mjs

@@ -0,0 +1,14 @@
+export const ADA_ASCII_LOGO = [
+	"               █████",
+	"              ░░███",
+	"  ██████    ███████   ██████",
+	" ░░░░░███  ███░░███  ░░░░░███",
+	"  ███████ ░███ ░███   ███████",
+	" ███░░███ ░███ ░███  ███░░███",
+	"░░████████░░████████░░████████",
+	" ░░░░░░░░  ░░░░░░░░  ░░░░░░░░",
+];
+
+export const ADA_ASCII_LOGO_TEXT = ADA_ASCII_LOGO.join("\n");
+
+export const ADA_LOGO_HTML = `<style>@import url('https://fonts.googleapis.com/css2?family=VT323&display=swap');.logo{width:auto!important;height:auto!important;margin-bottom:16px!important}</style><span style="font-family:'VT323',monospace;font-size:48px;color:#687B4E">ada</span>`;

package/metadata/commands.d.mts

@@ -0,0 +1,46 @@
+export type PromptSpec = {
+	name: string;
+	description: string;
+	args: string;
+	section: string;
+	topLevelCli: boolean;
+};
+
+export type ExtensionCommandSpec = {
+	name: string;
+	args: string;
+	section: string;
+	description: string;
+	publicDocs: boolean;
+};
+
+export type LivePackageCommandSpec = {
+	name: string;
+	usage: string;
+};
+
+export type LivePackageCommandGroup = {
+	title: string;
+	commands: LivePackageCommandSpec[];
+};
+
+export type CliCommand = {
+	usage: string;
+	description: string;
+};
+
+export type CliCommandSection = {
+	title: string;
+	commands: CliCommand[];
+};
+
+export declare function readPromptSpecs(appRoot: string): PromptSpec[];
+export declare const extensionCommandSpecs: ExtensionCommandSpec[];
+export declare const livePackageCommandGroups: LivePackageCommandGroup[];
+export declare const cliCommandSections: CliCommandSection[];
+export declare const legacyFlags: CliCommand[];
+export declare const topLevelCommandNames: string[];
+
+export declare function formatSlashUsage(command: { name: string; args?: string }): string;
+export declare function formatCliWorkflowUsage(command: { name: string; args?: string }): string;
+export declare function getExtensionCommandSpec(name: string): ExtensionCommandSpec | undefined;