@shanepadgett/tau-agent 0.33.1 → 0.34.0

package/extensions/checkpoint/index.ts

@@ -0,0 +1,102 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
+import { setCheckpointRowsVisible } from "../../shared/checkpoint-visibility.ts";
+import { CHECKPOINT_TOOL, registerCheckpointTool } from "./checkpoint.ts";
+import { createCheckpointBudget, type CheckpointBudgetNoticeLevel } from "./checkpoint-budget.ts";
+import { projectContextMessages } from "./messages.ts";
+import { CHECKPOINT_SYSTEM_GUIDANCE, formatCheckpointMessage } from "./prompt.ts";
+import checkpointSettings from "./settings.ts";
+
+export default function checkpointExtension(pi: ExtensionAPI): void {
+	const budget = createCheckpointBudget();
+	let checkpointSucceeded = false;
+
+	const resetBudget = (): void => {
+		checkpointSucceeded = false;
+		budget.reset();
+	};
+
+	registerCheckpointTool(pi);
+	pi.on("session_start", async (_event, ctx) => {
+		const settings = await loadTauExtensionSettings(ctx, checkpointSettings);
+		budget.configure(settings.checkpointTokenLimit);
+		setCheckpointRowsVisible(settings.showToolRows);
+	});
+	pi.on("session_shutdown", () => {
+		setCheckpointRowsVisible(false);
+		resetBudget();
+	});
+	pi.on("session_compact", resetBudget);
+	pi.on("session_tree", resetBudget);
+	pi.on("session_before_fork", resetBudget);
+	pi.on("session_before_switch", resetBudget);
+	pi.on("before_agent_start", (event) => ({
+		systemPrompt: `${event.systemPrompt}\n\n${CHECKPOINT_SYSTEM_GUIDANCE}`,
+	}));
+	pi.on("turn_start", (_event, ctx) => {
+		if (checkpointSucceeded) resetBudget();
+		const noticeLevel = budget.beginTurn(ctx.getContextUsage()?.tokens ?? null);
+		if (noticeLevel !== undefined) sendCheckpointBudgetNotice(pi, noticeLevel);
+	});
+	pi.on("turn_end", (_event, ctx) => {
+		if (checkpointSucceeded) {
+			resetBudget();
+			return;
+		}
+		const noticeLevel = budget.finishTurn(ctx.getContextUsage()?.tokens ?? null);
+		if (noticeLevel !== undefined) sendCheckpointBudgetNotice(pi, noticeLevel);
+	});
+	pi.on("tool_result", (event) => {
+		if (event.toolName === CHECKPOINT_TOOL && !event.isError) checkpointSucceeded = true;
+	});
+	pi.on("tool_call", (event) => {
+		if (!budget.shouldBlockTool(event.toolName, CHECKPOINT_TOOL)) return;
+		return {
+			block: true,
+			reason: formatCheckpointMessage(
+				"block",
+				"Checkpoint required before using other tools. Call checkpoint, then continue the user's work.",
+			),
+		};
+	});
+	pi.on("context", (event, ctx) => ({
+		messages: projectContextMessages(event.messages, ctx.sessionManager.buildContextEntries()),
+	}));
+}
+
+function sendCheckpointBudgetNotice(pi: ExtensionAPI, level: CheckpointBudgetNoticeLevel): void {
+	pi.sendMessage({
+		customType: "tau.checkpoint",
+		content: checkpointBudgetMessage(level),
+		display: false,
+		details: {
+			v: 1,
+			kind: "checkpoint.checkpoint-budget",
+			source: "checkpoint",
+			level,
+		},
+	});
+}
+
+function checkpointBudgetMessage(level: CheckpointBudgetNoticeLevel): string {
+	switch (level) {
+		case 50:
+			return formatCheckpointMessage(
+				"budget",
+				"Context usage reached 50% of the configured checkpoint limit. Continue current work and checkpoint when convenient.",
+				{ level: "50" },
+			);
+		case 75:
+			return formatCheckpointMessage(
+				"budget",
+				"Context usage reached 75% of the configured checkpoint limit. Run checkpoint soon. At 100%, non-checkpoint tool calls will be blocked until checkpoint succeeds.",
+				{ level: "75" },
+			);
+		case 100:
+			return formatCheckpointMessage(
+				"budget",
+				"Checkpoint budget reached. Call checkpoint now before using any other tool. Do not call other tools.",
+				{ level: "100" },
+			);
+	}
+}

package/extensions/checkpoint/messages.ts

@@ -0,0 +1,169 @@
+import type { AssistantMessage, TextContent, UserMessage } from "@earendil-works/pi-ai";
+import { sessionEntryToContextMessages, type ContextEvent, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { formatCheckpointMessage } from "./prompt.ts";
+
+type AgentMessage = ContextEvent["messages"][number];
+type ContextPair = { entry: SessionEntry; message: AgentMessage };
+
+const CHECKPOINT_KIND = "checkpoint.checkpoint";
+const MESSAGE_ID_METADATA_TYPE = "tau.checkpoint.message-id";
+
+type CheckpointMetadataMessage = Extract<AgentMessage, { role: "custom" }>;
+
+type CheckpointAnchor = {
+	call: ContextPair;
+	result: ContextPair;
+	resultIndex: number;
+	toolCallIds: Set<string>;
+};
+
+function pairsAlignWithMessages(pairs: readonly ContextPair[], messages: readonly AgentMessage[]): boolean {
+	if (pairs.length !== messages.length) return false;
+	return !pairs.some((pair, index) => {
+		const expected = messageKey(pair.message);
+		const actual = messageKey(messages[index]);
+		return expected === undefined || actual === undefined || expected !== actual;
+	});
+}
+
+function findCheckpointResult(
+	pairs: readonly ContextPair[],
+): { result: ContextPair; resultIndex: number; checkpointId: string; fileBatchId: string } | undefined {
+	for (let resultIndex = pairs.length - 1; resultIndex >= 0; resultIndex--) {
+		const result = pairs[resultIndex];
+		if (result.entry.type !== "message" || result.message.role !== "toolResult") continue;
+		const details = checkpointDetails(result.message.details);
+		if (details === undefined) continue;
+		return { result, resultIndex, checkpointId: details.checkpointId, fileBatchId: details.fileBatchId };
+	}
+	return undefined;
+}
+
+function resolveCheckpointCall(
+	pairs: readonly ContextPair[],
+	resultIndex: number,
+	checkpointId: string,
+): { call: ContextPair; toolCallIds: Set<string> } | "misaligned" {
+	let callIndex = resultIndex - 1;
+	while (callIndex >= 0 && !hasCheckpointToolCall(pairs[callIndex].message, checkpointId)) callIndex--;
+	if (callIndex < 0) return "misaligned";
+	const call = pairs[callIndex];
+	if (call.message.role !== "assistant") return "misaligned";
+	const toolCallIds = new Set<string>();
+	for (const part of call.message.content) {
+		if (part.type === "toolCall") toolCallIds.add(part.id);
+	}
+	return { call, toolCallIds };
+}
+
+function findCheckpointAnchor(pairs: readonly ContextPair[]): CheckpointAnchor | "misaligned" | undefined {
+	const found = findCheckpointResult(pairs);
+	if (found === undefined) return undefined;
+	const resolved = resolveCheckpointCall(pairs, found.resultIndex, found.checkpointId);
+	if (resolved === "misaligned") return "misaligned";
+	return {
+		call: resolved.call,
+		result: found.result,
+		resultIndex: found.resultIndex,
+		toolCallIds: resolved.toolCallIds,
+	};
+}
+
+function keepCheckpointPair(
+	checkpoint: CheckpointAnchor | undefined,
+	entry: SessionEntry,
+	message: AgentMessage,
+	index: number,
+): boolean {
+	if (checkpoint === undefined) return true;
+	if (index > checkpoint.resultIndex) return true;
+	if (entry.id === checkpoint.call.entry.id || entry.id === checkpoint.result.entry.id) return true;
+	return message.role === "toolResult" && checkpoint.toolCallIds.has(message.toolCallId);
+}
+
+function expandPairMessages(entry: SessionEntry, message: AgentMessage): AgentMessage[] {
+	if (entry.type === "message" && (entry.message.role === "user" || entry.message.role === "assistant")) {
+		return [createMessageIdMetadata(entry.id, message), message];
+	}
+	return [message];
+}
+
+/** Prunes completed checkpoint history and adds hidden provider-context message IDs. */
+export function projectContextMessages(
+	messages: readonly AgentMessage[],
+	entries: readonly SessionEntry[],
+): AgentMessage[] {
+	const pairs: ContextPair[] = [];
+	for (const entry of entries) {
+		for (const message of sessionEntryToContextMessages(entry)) pairs.push({ entry, message });
+	}
+
+	const checkpoint = findCheckpointAnchor(pairs);
+	if (checkpoint === "misaligned") return [...messages];
+	if (checkpoint === undefined && !pairsAlignWithMessages(pairs, messages)) return [...messages];
+
+	return pairs
+		.filter(({ entry, message }, index) => keepCheckpointPair(checkpoint, entry, message, index))
+		.flatMap(({ entry, message }) => expandPairMessages(entry, message));
+}
+
+/** Extracts only the original text from a user or assistant message. */
+export function extractConversationText(message: AgentMessage): string | undefined {
+	if (message.role === "user") return userText(message);
+	if (message.role === "assistant") return assistantText(message);
+	return undefined;
+}
+
+function messageKey(message: AgentMessage): string | undefined {
+	return JSON.stringify(message, (key, value) => (key === "timestamp" ? undefined : value));
+}
+
+function checkpointDetails(details: unknown): { checkpointId: string; fileBatchId: string } | undefined {
+	if (typeof details !== "object" || details === null) return undefined;
+	const value = details as Record<string, unknown>;
+	if (
+		value.v !== 1 ||
+		value.kind !== CHECKPOINT_KIND ||
+		typeof value.checkpointId !== "string" ||
+		typeof value.fileBatchId !== "string"
+	)
+		return undefined;
+	return { checkpointId: value.checkpointId, fileBatchId: value.fileBatchId };
+}
+
+function hasCheckpointToolCall(message: AgentMessage, checkpointId: string): boolean {
+	return (
+		message.role === "assistant" &&
+		message.content.some((part) => part.type === "toolCall" && part.name === "checkpoint" && part.id === checkpointId)
+	);
+}
+
+function createMessageIdMetadata(id: string, message: AgentMessage): CheckpointMetadataMessage {
+	const role = message.role === "user" ? "user" : "assistant";
+	return {
+		role: "custom",
+		customType: MESSAGE_ID_METADATA_TYPE,
+		content: formatCheckpointMessage(
+			"message-id",
+			`<message-id>${JSON.stringify(id)}</message-id>\n<message-role>${role}</message-role>`,
+		),
+		display: false,
+		details: { v: 1, kind: "checkpoint.message-id", id, role },
+		timestamp: message.timestamp,
+	};
+}
+
+function userText(message: UserMessage): string {
+	if (typeof message.content === "string") return message.content;
+	return message.content
+		.filter((part): part is TextContent => part.type === "text")
+		.map((part) => part.text)
+		.join("");
+}
+
+function assistantText(message: AssistantMessage): string {
+	return message.content
+		.filter((part): part is TextContent => part.type === "text")
+		.map((part) => part.text)
+		.join("");
+}

package/extensions/checkpoint/prompt.ts

@@ -0,0 +1,24 @@
+/** Standing checkpoint guidance appended to the system prompt. */
+export const CHECKPOINT_SYSTEM_GUIDANCE = `## Checkpoint
+
+Checkpoint is a hidden context-management system. It retires disposable history so long-running work can continue without user-visible ceremony.
+
+Messages wrapped in \`<checkpoint>...</checkpoint>\` are internal control signals, not conversation with the user.
+
+- Never acknowledge checkpoint system messages, budget notices, blocked tools, checkpoint metadata or IDs, injected checkpoint files as a transition, or context replacement.
+- Never mention the checkpoint system itself.
+- When checkpoint asks you to run the checkpoint tool, or when non-checkpoint tools are blocked, call \`checkpoint\` and continue the user's work immediately. Do not narrate the system.
+- Stay focused on the work the user wants done.
+- Use exact IDs from \`<checkpoint kind="message-id">\` metadata only in \`checkpoint.keepMessages\`.`;
+
+/** Wraps an internal checkpoint control payload for the model. */
+export function formatCheckpointMessage(
+	kind: string,
+	body: string,
+	attributes: Readonly<Record<string, string>> = {},
+): string {
+	const attrs = Object.entries(attributes)
+		.map(([key, value]) => ` ${key}=${JSON.stringify(value)}`)
+		.join("");
+	return `<checkpoint kind=${JSON.stringify(kind)}${attrs}>\n${body}\n</checkpoint>`;
+}

package/extensions/checkpoint/settings.ts

@@ -0,0 +1,27 @@
+import { Type } from "typebox";
+import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
+import { DEFAULT_CHECKPOINT_TOKEN_LIMIT } from "./checkpoint-budget.ts";
+
+export default defineTauExtensionSettings({
+	key: "checkpoint",
+	defaults: {
+		showToolRows: false as boolean,
+		checkpointTokenLimit: DEFAULT_CHECKPOINT_TOKEN_LIMIT,
+	},
+	schema: Type.Object(
+		{
+			showToolRows: Type.Optional(
+				Type.Boolean({
+					default: false,
+					description: "Show checkpoint and injected-file rows in the TUI for debugging.",
+				}),
+			),
+			checkpointTokenLimit: Type.Integer({
+				minimum: 1,
+				default: DEFAULT_CHECKPOINT_TOKEN_LIMIT,
+				description: "Context-token ceiling before a checkpoint is required.",
+			}),
+		},
+		{ additionalProperties: false },
+	),
+});

package/extensions/commit/commit-effort.ts

@@ -6,9 +6,9 @@ const LOW_EFFORT_MAX_CHANGED_LINES = 500;
 export function commitEffort(files: readonly Pick<DirtyFile, "changeSize">[]): ModelEffort {
 	let changedLines = 0;
 	for (const file of files) {
-		if (file.changeSize === "binary") return "medium";
+		if (file.changeSize === "binary") return "standard";
 		changedLines += file.changeSize;
-		if (changedLines > LOW_EFFORT_MAX_CHANGED_LINES) return "medium";
+		if (changedLines > LOW_EFFORT_MAX_CHANGED_LINES) return "standard";
 	}
-	return "low";
+	return "quick";
 }

package/extensions/context/README.md

@@ -1,12 +1,12 @@
 # Context
 
-Context stores reusable repository work scopes in `.pi/contexts`. Folder names become selector tabs, TOML files become concepts, and TOML sections become selectable entries.
+Context stores reusable repository work scopes in `.pi/contexts`. Domain folders use `NN_slug` (`01_extensions`, `02_core`, …) so `/context` can order tabs; the UI shows the slug only. TOML files become concepts, and TOML sections become selectable entries.
 
 See [Context management](../../docs/context.md) for catalog structure and taxonomy guidance.
 
-Use `/context` to set active entries for the current session branch. Tau stores only the selected entry IDs. Before each model call it rebuilds one ephemeral projection from current files, so repeated selections do not accumulate snapshots in conversation history. Open `/context`, press `Ctrl+C`, then confirm to clear active context.
+Use `/context` to inject entries into the conversation. Selecting entries reads `read` paths in full, resolves `show` targets to current declaration slices, outlines `outline` paths, and adds one hidden note listing `references` and instructing the agent to treat the injected material as current. Injection happens once, immediately, before your next prompt; nothing is rebuilt on later model calls. Prefer complete reads for bounded work files; use `show` for thin contracts from larger neighbors; reserve `outline` for large or noisy files.
 
-After meaningful uncommitted work (new/moved ownership, not trivial already-covered polish), the coding agent should run the `context-sync` subagent so `.pi/contexts` stays aligned. Context sync catalogs durable code and long-lived documentation. Scratch pads, working plans, interviews, rough ideas, and other temporary artifacts should stay out; add recurring transient paths to `validation.ignoreGlobs`. Humans can also run `/context-sync` or `/context-sync <nudge>` and press Escape to cancel a running sync. It walks domain → concept → entry → membership, edits only `.pi/contexts` with `patch`, and the harness verifies write scope plus catalog invariants afterward. Out-of-scope writes are restored and the run fails. Optional nudge text soft-steers judgment without skipping evidence.
+After meaningful uncommitted work (new/moved ownership, not trivial already-covered polish), the coding agent should run the `context-sync` subagent so `.pi/contexts` stays aligned. Context sync catalogs durable code and long-lived documentation as **work packs** (job-shaped entries an agent can start from), not bare path indexes. Scratch pads, working plans, interviews, rough ideas, and other temporary artifacts should stay out; add recurring transient paths to `validation.ignoreGlobs`. Humans can also run `/context-sync` or `/context-sync <nudge>`; the command replaces the editor with a status panel (Escape / Ctrl+C cancel). It uses normal repo tools, walks domain → concept → entry → start-pack modes, and prefers `patch` under `.pi/contexts`. The harness verifies catalog coverage afterward. Optional nudge text soft-steers judgment (including quality rewrites of weak bags) without skipping the ladder or coverage.
 
 Sync surface is configurable:
 
@@ -37,15 +37,19 @@ description = "Player-owned gameplay systems"
 
 [input]
 description = "Input mapping and command handling"
-read = []
-outline = ["src/player/input.ts"]
+read = ["src/player/input.ts"]
+show = []
+outline = []
 references = []
 
 [movement]
 description = "Player locomotion and collision"
-read = []
-outline = ["src/player/movement.ts"]
+read = ["src/player/movement.ts"]
+show = [
+  { path = "src/runtime/fetch-handler.ts", name = "handleFetch" },
+]
+outline = []
 references = ["src/runtime/fetch-handler.ts"]
 ```
 
-Every entry must declare all three loading arrays. `read` supplies exact complete contents, `outline` asks Explore for current structural outlines, and `references` lists unloaded paths. If selected entries classify the same path differently, precedence is `read`, then `outline`, then `references`.
+Every entry must declare all four loading arrays. `read` supplies exact complete contents, `show` resolves path+name declaration slices, `outline` asks Explore for structural outlines, and `references` lists unloaded paths. If selected entries classify the same path differently, precedence is `read`, then `show`, then `outline`, then `references`.

package/extensions/context/definitions.ts

@@ -4,6 +4,14 @@ import { basename, dirname, extname, join, relative, resolve, sep } from "node:p
 import { parse } from "smol-toml";
 import { matchGlob } from "../../shared/glob.ts";
 
+export type ContextShowView = "signature" | "signatureWithDocs" | "declaration" | "declarationWithImports";
+
+export interface ContextShowTarget {
+	path: string;
+	name: string;
+	view: ContextShowView;
+}
+
 export interface ContextEntry {
 	id: string;
 	tab: string;
@@ -13,6 +21,7 @@ export interface ContextEntry {
 	name: string;
 	description: string;
 	read: string[];
+	show: ContextShowTarget[];
 	outline: string[];
 	references: string[];
 	path: string;
@@ -38,7 +47,14 @@ const CONTEXT_IGNORED_FILENAMES = new Set([
 	"uv.lock",
 	"yarn.lock",
 ]);
-const CONTEXT_ENTRY_FIELDS = new Set(["description", "read", "outline", "references"]);
+const CONTEXT_ENTRY_FIELDS = new Set(["description", "read", "show", "outline", "references"]);
+const CONTEXT_SHOW_VIEWS = new Set<ContextShowView>([
+	"signature",
+	"signatureWithDocs",
+	"declaration",
+	"declarationWithImports",
+]);
+const CONTEXT_SHOW_TARGET_FIELDS = new Set(["path", "name", "view"]);
 
 export function isContextEligiblePath(path: string, ignoreGlobs: readonly string[] = []): boolean {
 	return (
@@ -84,12 +100,48 @@ export async function findProjectRoot(cwd: string): Promise<string> {
 	return gitRoot ?? resolve(cwd);
 }
 
+const TAB_FOLDER_PATTERN = /^(\d{2})_([a-z0-9]+(?:-[a-z0-9]+)*)$/;
+
 function validSlug(value: string, label: string): string {
 	const slug = value.trim();
 	if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) throw new Error(`${label} must use lowercase kebab-case: ${value}`);
 	return slug;
 }
 
+/** Domain folder: `01_extensions` → order 1, tab slug `extensions` (id/label). */
+function parseContextTabFolder(name: string): { order: number; slug: string; folder: string } {
+	const match = TAB_FOLDER_PATTERN.exec(name);
+	const digits = match?.[1];
+	const slug = match?.[2];
+	if (!match || digits === undefined || slug === undefined) {
+		throw new Error(
+			`Context tab folder must be NN_kebab-slug with a two-digit order starting at 01 (e.g. 01_extensions): ${name}`,
+		);
+	}
+	const order = Number(digits);
+	if (!Number.isInteger(order) || order < 1 || order > 99) {
+		throw new Error(`Context tab order must be an integer from 01 to 99: ${name}`);
+	}
+	return { order, slug, folder: name };
+}
+
+function assertContiguousTabOrders(tabs: readonly { order: number; slug: string; folder: string }[]): void {
+	const byOrder = [...tabs].sort((left, right) => left.order - right.order);
+	const seenSlugs = new Set<string>();
+	for (let index = 0; index < byOrder.length; index++) {
+		const tab = byOrder[index];
+		if (!tab) continue;
+		const expected = index + 1;
+		if (tab.order !== expected) {
+			throw new Error(
+				`Context tab orders must be contiguous from 01 (expected ${String(expected).padStart(2, "0")}_…, found ${tab.folder})`,
+			);
+		}
+		if (seenSlugs.has(tab.slug)) throw new Error(`Duplicate context tab slug: ${tab.slug}`);
+		seenSlugs.add(tab.slug);
+	}
+}
+
 function normalizeProjectPath(root: string, input: string): string {
 	const absolute = resolve(root, input.trim().replace(/^@/, ""));
 	const path = relative(root, absolute).split(sep).join("/");
@@ -102,8 +154,126 @@ function sortedUnique(values: readonly string[]): string[] {
 	return [...new Set(values)].sort((a, b) => a.localeCompare(b));
 }
 
-export function contextEntryPaths(entry: Pick<ContextEntry, "read" | "outline" | "references">): string[] {
-	return sortedUnique([...entry.read, ...entry.outline, ...entry.references]);
+export function contextEntryPaths(entry: Pick<ContextEntry, "read" | "show" | "outline" | "references">): string[] {
+	return sortedUnique([
+		...entry.read,
+		...entry.show.map((target) => target.path),
+		...entry.outline,
+		...entry.references,
+	]);
+}
+
+function parseOneShowTarget(root: string, catalogPath: string, entryName: string, item: unknown): ContextShowTarget {
+	const record = item as Record<string, unknown>;
+	const unknownField = Object.keys(record).find((field) => !CONTEXT_SHOW_TARGET_FIELDS.has(field));
+	if (unknownField) throw new Error(`Invalid context show field: ${catalogPath} [${entryName}] ${unknownField}`);
+	if (typeof record.path !== "string" || !record.path.trim() || typeof record.name !== "string" || !record.name.trim())
+		throw new Error(`Invalid context show target: ${catalogPath} [${entryName}]`);
+	let view: ContextShowView = "declaration";
+	if (record.view !== undefined) {
+		if (typeof record.view !== "string" || !CONTEXT_SHOW_VIEWS.has(record.view as ContextShowView))
+			throw new Error(`Invalid context show view: ${catalogPath} [${entryName}] ${String(record.view)}`);
+		view = record.view as ContextShowView;
+	}
+	return {
+		path: normalizeProjectPath(root, record.path),
+		name: record.name.trim(),
+		view,
+	};
+}
+
+function dedupeShowTargets(catalogPath: string, entryName: string, targets: ContextShowTarget[]): ContextShowTarget[] {
+	const seen = new Map<string, ContextShowTarget>();
+	for (const target of targets) {
+		const key = `${target.path}\0${target.name}`;
+		const existing = seen.get(key);
+		if (existing && existing.view !== target.view)
+			throw new Error(
+				`Context show target has multiple views: ${catalogPath} [${entryName}] ${target.path} ${target.name}`,
+			);
+		if (!existing) seen.set(key, target);
+	}
+	return [...seen.values()].sort(
+		(left, right) => left.path.localeCompare(right.path) || left.name.localeCompare(right.name),
+	);
+}
+
+function parseShowTargets(root: string, catalogPath: string, entryName: string, raw: unknown): ContextShowTarget[] {
+	if (!Array.isArray(raw) || raw.some((item) => !item || typeof item !== "object" || Array.isArray(item)))
+		throw new Error(`Invalid context entry show list: ${catalogPath} [${entryName}]`);
+	return dedupeShowTargets(
+		catalogPath,
+		entryName,
+		raw.map((item) => parseOneShowTarget(root, catalogPath, entryName, item)),
+	);
+}
+
+function parseContextEntryRecord(
+	root: string,
+	path: string,
+	tab: string,
+	concept: string,
+	conceptName: string,
+	conceptDescription: string,
+	name: string,
+	value: unknown,
+): ContextEntry {
+	if (!value || typeof value !== "object" || Array.isArray(value))
+		throw new Error(`Invalid context entry: ${path} [${name}]`);
+	const record = value as Record<string, unknown>;
+	const unknownField = Object.keys(record).find((field) => !CONTEXT_ENTRY_FIELDS.has(field));
+	if (unknownField) throw new Error(`Invalid context entry field: ${path} [${name}] ${unknownField}`);
+	if (
+		typeof record.description !== "string" ||
+		!record.description.trim() ||
+		!Array.isArray(record.read) ||
+		record.read.some((item) => typeof item !== "string") ||
+		!Array.isArray(record.outline) ||
+		record.outline.some((item) => typeof item !== "string") ||
+		!Array.isArray(record.references) ||
+		record.references.some((item) => typeof item !== "string")
+	)
+		throw new Error(`Invalid context entry: ${path} [${name}]`);
+	const entry = validSlug(name, "Context entry");
+	const entryRead = sortedUnique((record.read as string[]).map((item) => normalizeProjectPath(root, item)));
+	const entryShow = parseShowTargets(root, path, name, record.show ?? []);
+	const entryOutline = sortedUnique((record.outline as string[]).map((item) => normalizeProjectPath(root, item)));
+	const entryReferences = sortedUnique(
+		(record.references as string[]).map((item) => normalizeProjectPath(root, item)),
+	);
+	if (entryRead.length === 0 && entryShow.length === 0 && entryOutline.length === 0 && entryReferences.length === 0)
+		throw new Error(`Invalid context entry: ${path} [${name}]`);
+	const classified = [...entryRead, ...entryOutline, ...entryReferences];
+	const overlap = classified.find((item, index) => classified.indexOf(item) !== index);
+	if (overlap) throw new Error(`Context path has multiple loading modes: ${path} [${name}] ${overlap}`);
+	return {
+		id: `${tab}/${concept}/${entry}`,
+		tab,
+		concept,
+		conceptName,
+		conceptDescription,
+		name: entry,
+		description: record.description.trim(),
+		read: entryRead,
+		show: entryShow,
+		outline: entryOutline,
+		references: entryReferences,
+		path,
+	};
+}
+
+async function loadConceptFile(root: string, tab: string, folder: string, fileName: string): Promise<ContextEntry[]> {
+	const path = join(root, ".pi", "contexts", folder, fileName);
+	const concept = validSlug(basename(fileName, ".toml"), "Context concept");
+	const raw = parse(await readFile(path, "utf8")) as Record<string, unknown>;
+	const conceptName = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim() : concept;
+	const conceptDescription = typeof raw.description === "string" ? raw.description.trim() : "";
+	const entries: ContextEntry[] = [];
+	for (const [name, value] of Object.entries(raw)) {
+		if (name === "name" || name === "description") continue;
+		entries.push(parseContextEntryRecord(root, path, tab, concept, conceptName, conceptDescription, name, value));
+	}
+	return entries;
 }
 
 export async function loadContextEntries(root: string): Promise<ContextEntry[]> {
@@ -111,63 +281,16 @@ export async function loadContextEntries(root: string): Promise<ContextEntry[]>
 	if (!(await pathExists(contextsRoot))) return [];
 	const tabs = (await readdir(contextsRoot, { withFileTypes: true }))
 		.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
-		.sort((a, b) => a.name.localeCompare(b.name));
+		.map((entry) => parseContextTabFolder(entry.name));
+	assertContiguousTabOrders(tabs);
+	tabs.sort((left, right) => left.order - right.order);
 	const result: ContextEntry[] = [];
 	for (const tabEntry of tabs) {
-		const tab = validSlug(tabEntry.name, "Context tab");
-		const files = (await readdir(join(contextsRoot, tab), { withFileTypes: true }))
+		const files = (await readdir(join(contextsRoot, tabEntry.folder), { withFileTypes: true }))
 			.filter((entry) => entry.isFile() && extname(entry.name) === ".toml")
 			.sort((a, b) => a.name.localeCompare(b.name));
 		for (const file of files) {
-			const path = join(contextsRoot, tab, file.name);
-			const concept = validSlug(basename(file.name, ".toml"), "Context concept");
-			const raw = parse(await readFile(path, "utf8")) as Record<string, unknown>;
-			const conceptName = typeof raw.name === "string" && raw.name.trim() ? raw.name.trim() : concept;
-			const conceptDescription = typeof raw.description === "string" ? raw.description.trim() : "";
-			for (const [name, value] of Object.entries(raw)) {
-				if (name === "name" || name === "description") continue;
-				if (!value || typeof value !== "object" || Array.isArray(value))
-					throw new Error(`Invalid context entry: ${path} [${name}]`);
-				const record = value as Record<string, unknown>;
-				const unknownField = Object.keys(record).find((field) => !CONTEXT_ENTRY_FIELDS.has(field));
-				if (unknownField) throw new Error(`Invalid context entry field: ${path} [${name}] ${unknownField}`);
-				if (
-					typeof record.description !== "string" ||
-					!record.description.trim() ||
-					!Array.isArray(record.read) ||
-					record.read.some((item) => typeof item !== "string") ||
-					!Array.isArray(record.outline) ||
-					record.outline.some((item) => typeof item !== "string") ||
-					!Array.isArray(record.references) ||
-					record.references.some((item) => typeof item !== "string") ||
-					(record.read.length === 0 && record.outline.length === 0 && record.references.length === 0)
-				)
-					throw new Error(`Invalid context entry: ${path} [${name}]`);
-				const entry = validSlug(name, "Context entry");
-				const entryRead = sortedUnique((record.read as string[]).map((item) => normalizeProjectPath(root, item)));
-				const entryOutline = sortedUnique(
-					(record.outline as string[]).map((item) => normalizeProjectPath(root, item)),
-				);
-				const entryReferences = sortedUnique(
-					(record.references as string[]).map((item) => normalizeProjectPath(root, item)),
-				);
-				const classified = [...entryRead, ...entryOutline, ...entryReferences];
-				const overlap = classified.find((item, index) => classified.indexOf(item) !== index);
-				if (overlap) throw new Error(`Context path has multiple loading modes: ${path} [${name}] ${overlap}`);
-				result.push({
-					id: `${tab}/${concept}/${entry}`,
-					tab,
-					concept,
-					conceptName,
-					conceptDescription,
-					name: entry,
-					description: record.description.trim(),
-					read: entryRead,
-					outline: entryOutline,
-					references: entryReferences,
-					path,
-				});
-			}
+			result.push(...(await loadConceptFile(root, tabEntry.slug, tabEntry.folder, file.name)));
 		}
 	}
 	return result;