@danypops/papyrus 0.11.4 → 0.13.0

package/README.md

@@ -56,6 +56,20 @@ It blocks every Papyrus push whose destination is not `DanyPops/papyrus`, includ
 
 The daemon uses WAL, foreign keys, a bounded busy timeout, versioned migrations, periodic passive checkpoints, and periodic `PRAGMA optimize`. Keep the database on a local filesystem; SQLite WAL does not support network filesystems.
 
+### Context Mesh persistence model
+
+`artifacts` is the shared graph-identity supertype, not a second copy of every application's database. `edges` references that single identity table at both endpoints, preserving foreign-key integrity for cross-domain links. Domain extension tables exist only where application invariants require indexed relational state: Task chronology/focus/scope and Discourse posts/events/session cursors/projection checkpoints. This is a class-table/table-per-type variant with explicit child-to-parent foreign keys; Papyrus does not use SQLite table inheritance or orphan-prone `(target_type, target_id)` links.
+
+The owning application remains the mutation authority. Discourse commits its extension rows and `context-thread`/`context-message` Doc projections atomically through `discourse.store`; generic artifact, document, Skill-template, lifecycle, and graph-link operations reject those owned subtypes and the `reply_to`/`discusses` relations. SQLite triggers additionally verify that each extension row references the expected Doc subtype. Domain tables are canonical for domain invariants; graph bodies and metadata are read-oriented projections committed in the same transaction.
+
+The authenticated CLI exposes the same operation for diagnostics and adapter parity:
+
+```bash
+papyrus discourse store read_thread --store-id team-forum \
+  --input-json '{"forumId":"engineering","topicId":"reviews","threadId":"mesh","limit":25}' \
+  --json
+```
+
 ## Schema protocol (enforceable)
 
 Papyrus enforces four artifact kinds:
@@ -217,10 +231,10 @@ packed install npm:@danypops/papyrus
 ~/.pi/agent/npm/node_modules/.bin/papyrus service install
 ```
 
-Existing databases are never migrated on daemon boot. After upgrading to focus-driven Task continuation, run the authenticated CLI migration explicitly. Older databases receive prerequisite schemas in one transaction. Existing Tasks are deliberately marked **unscoped**: Papyrus does not guess ownership from titles, labels, historical cwd, or repository names. They remain visible in **All projects** until explicitly assigned with `papyrus tasks assign-project <task-id> [project-root]`:
+Existing databases are never migrated on daemon boot. After upgrading to a newer schema, run the authenticated CLI migration explicitly. Older databases receive prerequisite schemas—including Task continuation and Context Mesh extensions—in one transaction. Existing Tasks are deliberately marked **unscoped**: Papyrus does not guess ownership from titles, labels, historical cwd, or repository names. They remain visible in **All projects** until explicitly assigned with `papyrus tasks assign-project <task-id> [project-root]`:
 
 ```bash
-~/.pi/agent/npm/node_modules/.bin/papyrus migrate task-focus
+~/.pi/agent/npm/node_modules/.bin/papyrus migrate schema
 ```
 
 Until that command succeeds, health reports `migrationRequired` and normal domain operations are rejected with actionable guidance. Migration is not exposed as a Pi tool or MCP action. New empty databases bootstrap directly at the current schema.

package/extension/src/active-task-continuation.ts

@@ -41,6 +41,8 @@ function continuationPrompt(task: ActiveTaskMarker): string {
 	return [
 		"Continue the active Papyrus Task now; do not hand off merely because the previous Pi run settled.",
 		"Reconcile its lifecycle, take the next concrete action, use tools, submit it for review when implementation effort is ready, and run gates plus checklist review before completion.",
+		"Do not shrink the task's scope to whatever fits in this turn, and do not treat a status update or summary as a substitute for doing the work or as proof of completion.",
+		"If something blocks progress, do not reject or pause on the first obstacle -- only after it genuinely recurs, and only when the task truly cannot proceed without external input.",
 		`Active task: ${task.id}: ${task.title.slice(0, TITLE_LIMIT)}`,
 	].join("\n");
 }
@@ -97,6 +99,10 @@ export class ActiveTaskContinuation {
 		this.queued = false;
 	}
 
+	onCompaction(): void {
+		this.queued = false;
+	}
+
 	onHumanInput(): void {
 		this.resetProgress();
 	}

package/extension/src/artifact-browser.ts

@@ -1,9 +1,10 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder, rawKeyHint } from "@earendil-works/pi-coding-agent";
 import { Container, Input, Spacer, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { SEED_RELATIONS } from "../../src/constants.ts";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import type { OperationName } from "../../src/service.ts";
+import type { StatusPresentation } from "./artifact-status-presentation.ts";
 import { artifactDetailsText } from "./artifact-detail-format.ts";
 import { showArtifactDetailView } from "./artifact-detail-view.ts";
 import { callService } from "./service-client.ts";
@@ -19,10 +20,10 @@ export interface ArtifactBrowserConfig {
 	kind: string;
 	title: string;
 	statusOrder: string[];
-	glyphs: Record<string, string>;
+	presentation: Record<string, StatusPresentation>;
 	listOperation?: OperationName;
 	listInput?: Record<string, unknown>;
-	rowMeta(row: Artifact): string;
+	rowMeta(row: Artifact, theme: Theme): string;
 	actions(row: Artifact): string[];
 	handleAction(choice: string, row: Artifact, ctx: ExtensionCommandContext): Promise<void>;
 }
@@ -156,7 +157,11 @@ function renderPanel(
 						.join(theme.fg("muted", " · "));
 				const spacing = Math.max(1, width - visibleWidth(title) - visibleWidth(hint));
 				const summary = statusSummary(rows, config.statusOrder)
-					.map(({ status, count }) => `${config.glyphs[status] ?? status} ${count} ${status}`)
+					.map(({ status, count }) => {
+						const presentation = config.presentation[status];
+						const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : status;
+						return `${glyph} ${count} ${status}`;
+					})
 					.join(", ");
 				return [
 					truncateToWidth(`${title}${" ".repeat(spacing)}${hint}`, width, ""),
@@ -176,10 +181,11 @@ function renderPanel(
 					const row = filtered[index]!;
 					const selected = index === selectedIndex;
 					const cursor = selected ? theme.fg("accent", "❯") : " ";
-					const glyph = config.glyphs[row.status] ?? "?";
+					const presentation = config.presentation[row.status];
+					const glyph = presentation ? theme.fg(presentation.color, presentation.glyph) : "?";
 					const title = selected ? theme.bold(row.title) : row.title;
-					const meta = config.rowMeta(row);
-					lines.push(truncateToWidth(`${cursor} ${glyph} ${title}${meta ? theme.fg("dim", ` · ${meta}`) : ""}`, width, ""));
+					const meta = config.rowMeta(row, theme);
+					lines.push(truncateToWidth(`${cursor} ${glyph} ${title}${meta ? `${theme.fg("dim", " · ")}${meta}` : ""}`, width, ""));
 				}
 				lines.push(theme.fg("muted", `  ${selectedIndex + 1}/${filtered.length} ${config.kind}`));
 				return lines;

package/extension/src/artifact-status-presentation.ts

@@ -0,0 +1,53 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Shared {label, glyph, color} shape, mirroring task-presentation.ts's TASK_STATUS_PRESENTATION
+ * for every other artifact kind's status. Centralizing this closes a real gap: every artifact
+ * browser (Rules, Docs, Notes, Skills) previously rendered status as a bare glyph with no color at
+ * all, which is exactly why "hard to understand which rules are active" was a real complaint --
+ * an active rule's "●" and a deprecated rule's "○" differ only by one filled-vs-hollow pixel shape,
+ * easy to miss at a glance across a scrolling list.
+ */
+export interface StatusPresentation {
+	label: string;
+	glyph: string;
+	color: ThemeColor;
+}
+
+export const RULE_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "success" },
+	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
+};
+
+export const DOC_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	draft: { label: "draft", glyph: "○", color: "muted" },
+	active: { label: "active", glyph: "●", color: "success" },
+	archived: { label: "archived", glyph: "■", color: "dim" },
+};
+
+export const NOTE_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	draft: { label: "draft", glyph: "○", color: "muted" },
+	active: { label: "active", glyph: "●", color: "success" },
+	archived: { label: "archived", glyph: "■", color: "dim" },
+};
+
+export const SKILL_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "success" },
+	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
+};
+
+/** Rule severity gets its own color independent of status -- block is the loudest, info the quietest. */
+export const RULE_SEVERITY_PRESENTATION: Record<string, ThemeColor> = {
+	block: "error",
+	warn: "warning",
+	info: "accent",
+};
+
+export function severityColor(severity: string): ThemeColor {
+	return RULE_SEVERITY_PRESENTATION[severity.toLowerCase()] ?? "muted";
+}
+
+/** Plain glyph lookup, for callers that build uncolored text first and colorize it later (e.g. task-graph's colorizeTaskGraphLine pattern). */
+export function glyphOf(presentation: Record<string, StatusPresentation>, status: string): string {
+	return presentation[status]?.glyph ?? "?";
+}

package/extension/src/context-budget.ts

@@ -0,0 +1,173 @@
+import { homedir } from "node:os";
+import { readFileSync } from "node:fs";
+import { CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN } from "../../src/constants.ts";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import { discoverSkillDirectories, scanSkillCatalogFootprint, type SkillCatalogFootprint } from "./skill-catalog-footprint.ts";
+import { ruleInjectionPreview } from "./rules.ts";
+
+const REPORT_MAX_ROWS = 5;
+
+export interface RuleBudgetEntry {
+	id: string;
+	title: string;
+	characters: number;
+	estimatedTokens: number;
+}
+
+export interface ContextBudget {
+	rules: {
+		entries: RuleBudgetEntry[]; // sorted descending by characters
+		totalCharacters: number;
+		totalEstimatedTokens: number;
+	};
+	skills: SkillCatalogFootprint;
+	totalEstimatedTokens: number;
+}
+
+/** Active Rules are injected into every relevant turn -- the same permanent tax role as a Pi-native skill's catalog entry. */
+export function computeRuleBudget(rules: ReadonlyArray<Pick<Artifact, "id" | "title" | "body" | "extra">>): ContextBudget["rules"] {
+	const entries = rules
+		.map((rule) => {
+			const characters = ruleInjectionPreview(rule).length;
+			return { id: rule.id, title: rule.title, characters, estimatedTokens: Math.ceil(characters / CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN) };
+		})
+		.sort((a, b) => b.characters - a.characters);
+	return {
+		entries,
+		totalCharacters: entries.reduce((sum, entry) => sum + entry.characters, 0),
+		totalEstimatedTokens: entries.reduce((sum, entry) => sum + entry.estimatedTokens, 0),
+	};
+}
+
+/** Best-effort: a missing, unreadable, or malformed settings.json contributes no extra skill directories rather than failing the whole report. */
+function readSettingsSkillPaths(settingsPath: string): string[] {
+	try {
+		const raw = JSON.parse(readFileSync(settingsPath, "utf8")) as { skills?: unknown };
+		if (!Array.isArray(raw.skills)) return [];
+		return raw.skills.filter((entry): entry is string => typeof entry === "string");
+	} catch {
+		return [];
+	}
+}
+
+export function computeContextBudget(
+	rules: ReadonlyArray<Pick<Artifact, "id" | "title" | "body" | "extra">>,
+	cwd: string,
+	homeDirectory: string = homedir(),
+): ContextBudget {
+	const settingsSkills = readSettingsSkillPaths(`${homeDirectory}/.pi/agent/settings.json`);
+	const directories = discoverSkillDirectories(homeDirectory, cwd, settingsSkills);
+	const skills = scanSkillCatalogFootprint(directories);
+	const ruleBudget = computeRuleBudget(rules);
+	return { rules: ruleBudget, skills, totalEstimatedTokens: ruleBudget.totalEstimatedTokens + skills.totalEstimatedTokens };
+}
+
+/** Pi's own documented compaction-reserve default (docs/compaction.md): headroom kept free for the model's response. */
+export const DEFAULT_RESERVE_TOKENS = 16_384;
+
+export interface ContextSegmentItem {
+	label: string;
+	estimatedTokens: number;
+}
+
+export interface ContextSegment {
+	key: "rules" | "tasks" | "skills" | "other";
+	label: string;
+	estimatedTokens: number;
+	/** Drill-down items, when this segment can be broken down further. Absent for "other" -- an opaque remainder, not a real category. */
+	items?: ContextSegmentItem[];
+}
+
+export interface ContextBreakdown {
+	/** Real usage from ctx.getContextUsage() -- ground truth, not estimated. Null only when Pi has no usage yet (e.g. before the first turn). */
+	totalTokens: number | null;
+	/** From ctx.model.contextWindow. Null when the active model's context window is unknown. */
+	contextWindow: number | null;
+	/** contextWindow - reserveTokens, mirroring Pi's own compaction-trigger formula. Null when contextWindow is unknown. */
+	effectiveBudget: number | null;
+	/** rules, tasks, skills, then "other" absorbing whatever real usage the first three don't account for. */
+	segments: ContextSegment[];
+}
+
+export interface BuildContextBreakdownInput {
+	totalTokens: number | null;
+	contextWindow: number | null;
+	reserveTokens?: number;
+	ruleBudget: ContextBudget["rules"];
+	taskEstimatedTokens: number;
+	skills: SkillCatalogFootprint;
+}
+
+/**
+ * Composes Papyrus's own estimated segments (rules/tasks/skills) against the real total Pi
+ * reports, deriving "everything else" (base system prompt, message history, tool definitions
+ * -- none of which Papyrus can see or estimate) as the remainder. The remainder is clamped to
+ * zero rather than shown negative: char/4 token estimation is approximate, and a small
+ * overshoot in the known segments must not display as a nonsensical negative "other" bucket.
+ * When the real total is unavailable, "other" is reported as zero and totalTokens surfaces as
+ * null so callers can label the whole breakdown as estimate-only rather than silently treating
+ * a partial sum as ground truth.
+ */
+export function buildContextBreakdown(input: BuildContextBreakdownInput): ContextBreakdown {
+	const reserveTokens = input.reserveTokens ?? DEFAULT_RESERVE_TOKENS;
+	const rules: ContextSegment = {
+		key: "rules",
+		label: "Papyrus Rules",
+		estimatedTokens: input.ruleBudget.totalEstimatedTokens,
+		items: input.ruleBudget.entries.map((entry) => ({ label: entry.title, estimatedTokens: entry.estimatedTokens })),
+	};
+	const tasks: ContextSegment = { key: "tasks", label: "Papyrus Tasks", estimatedTokens: input.taskEstimatedTokens };
+	const skills: ContextSegment = {
+		key: "skills",
+		label: "Pi Skills catalog",
+		estimatedTokens: input.skills.totalEstimatedTokens,
+		items: input.skills.entries.map((entry) => ({ label: entry.name, estimatedTokens: entry.estimatedTokens })),
+	};
+	const knownTokens = rules.estimatedTokens + tasks.estimatedTokens + skills.estimatedTokens;
+	const other: ContextSegment = {
+		key: "other",
+		label: "Everything else (base prompt, message history, tool definitions)",
+		estimatedTokens: input.totalTokens === null ? 0 : Math.max(0, input.totalTokens - knownTokens),
+	};
+	return {
+		totalTokens: input.totalTokens,
+		contextWindow: input.contextWindow,
+		effectiveBudget: input.contextWindow === null ? null : Math.max(0, input.contextWindow - reserveTokens),
+		segments: [rules, tasks, skills, other],
+	};
+}
+
+function truncate(text: string, max: number): string {
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/** Pure text formatter, independent of live daemon/filesystem state, for direct unit testing. */
+export function formatContextBudgetReport(budget: ContextBudget): string {
+	const lines: string[] = ["Papyrus passive context budget", ""];
+
+	lines.push(`Rules (active, injected every relevant turn): ${budget.rules.entries.length} rules · ${budget.rules.totalCharacters} chars · ~${budget.rules.totalEstimatedTokens} tokens`);
+	if (budget.rules.entries.length > 0) {
+		lines.push("  Largest:");
+		for (const entry of budget.rules.entries.slice(0, REPORT_MAX_ROWS)) {
+			lines.push(`  ${entry.characters.toString().padStart(5)} chars (~${entry.estimatedTokens} tok)  ${truncate(entry.title, 60)}`);
+		}
+	}
+	lines.push("");
+
+	lines.push(`Skills (Pi-native catalog, injected at startup): ${budget.skills.entries.length} skills · ${budget.skills.totalCharacters} chars · ~${budget.skills.totalEstimatedTokens} tokens`);
+	if (budget.skills.entries.length > 0) {
+		lines.push("  Largest:");
+		for (const entry of budget.skills.entries.slice(0, REPORT_MAX_ROWS)) {
+			lines.push(`  ${entry.characters.toString().padStart(5)} chars (~${entry.estimatedTokens} tok)  ${truncate(entry.name, 40)}`);
+		}
+	}
+	if (budget.skills.scannedDirectories.length > 0) {
+		lines.push(`  Scanned: ${budget.skills.scannedDirectories.join(", ")}`);
+	} else {
+		lines.push("  No skill directories found (checked Pi's documented global/project locations and settings.json's skills array).");
+	}
+	lines.push("");
+
+	lines.push(`Total passive tax: ~${budget.totalEstimatedTokens} tokens across ${budget.rules.entries.length + budget.skills.entries.length} items, before a single user message or tool call.`);
+	return lines.join("\n");
+}

package/extension/src/context-view.ts

@@ -0,0 +1,172 @@
+import type { ExtensionCommandContext, Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, type TUI } from "@earendil-works/pi-tui";
+import type { ContextBreakdown, ContextSegment, ContextSegmentItem } from "./context-budget.ts";
+import { formatContextBudgetReport, type ContextBudget } from "./context-budget.ts";
+
+const DRILLDOWN_VISIBLE_ROWS = 15;
+
+const SEGMENT_COLORS: Record<ContextSegment["key"], ThemeColor> = {
+	rules: "accent",
+	tasks: "success",
+	skills: "mdLink",
+	other: "muted",
+};
+
+function formatTokenCount(tokens: number): string {
+	return tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens);
+}
+
+function percentOf(part: number, whole: number): string {
+	return whole > 0 ? `${((part / whole) * 100).toFixed(1)}%` : "—";
+}
+
+/**
+ * Renders the context window as one proportional stacked bar, one colored run of block
+ * characters per segment, matching each row's own swatch color below it. A zero-token
+ * breakdown (nothing observed yet) renders an empty dim track rather than a divide-by-zero.
+ */
+export function renderContextBar(theme: Theme, segments: ReadonlyArray<ContextSegment>, width: number): string {
+	const total = segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+	if (total <= 0 || width <= 0) return theme.fg("dim", "░".repeat(Math.max(0, width)));
+	let used = 0;
+	let output = "";
+	segments.forEach((segment, index) => {
+		const isLast = index === segments.length - 1;
+		const cells = isLast ? width - used : Math.round((segment.estimatedTokens / total) * width);
+		used += cells;
+		if (cells > 0) output += theme.fg(SEGMENT_COLORS[segment.key], "█".repeat(cells));
+	});
+	return output;
+}
+
+class ContextViewport {
+	private selectedIndex = 0;
+	private drillDown: ContextSegment | null = null;
+	private drillIndex = 0;
+
+	constructor(
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly breakdown: ContextBreakdown,
+		private readonly close: () => void,
+	) {}
+
+	invalidate(): void {}
+
+	render(width: number): string[] {
+		const theme = this.theme;
+		const contentWidth = Math.max(1, width);
+		const border = theme.fg("borderMuted", "─".repeat(contentWidth));
+		const lines: string[] = [border, truncateToWidth(theme.fg("accent", theme.bold("Context")), contentWidth, "")];
+
+		if (this.breakdown.totalTokens !== null && this.breakdown.effectiveBudget !== null) {
+			const percent = percentOf(this.breakdown.totalTokens, this.breakdown.effectiveBudget);
+			lines.push(truncateToWidth(
+				`${formatTokenCount(this.breakdown.totalTokens)} / ${formatTokenCount(this.breakdown.effectiveBudget)} tokens (${percent} of usable budget)`,
+				contentWidth,
+				"",
+			));
+		} else if (this.breakdown.totalTokens !== null) {
+			lines.push(truncateToWidth(`${formatTokenCount(this.breakdown.totalTokens)} tokens (model context window unknown)`, contentWidth, ""));
+		} else {
+			lines.push(theme.fg("dim", "No real usage reported yet — segment sizes below are Papyrus's own estimates only"));
+		}
+		lines.push(renderContextBar(theme, this.breakdown.segments, contentWidth));
+		lines.push("");
+
+		if (this.drillDown) {
+			lines.push(...this.renderDrillDown(contentWidth));
+		} else {
+			lines.push(...this.renderSegments(contentWidth));
+		}
+		lines.push(border);
+		return lines;
+	}
+
+	private renderSegments(width: number): string[] {
+		const theme = this.theme;
+		const lines: string[] = [];
+		const denominator = this.breakdown.totalTokens ?? this.breakdown.segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+		this.breakdown.segments.forEach((segment, index) => {
+			const selected = index === this.selectedIndex;
+			const cursor = selected ? theme.fg("accent", "❯") : " ";
+			const swatch = theme.fg(SEGMENT_COLORS[segment.key], "██");
+			const title = selected ? theme.bold(segment.label) : segment.label;
+			const percent = percentOf(segment.estimatedTokens, denominator);
+			const drillHint = segment.items && segment.items.length > 0 ? theme.fg("dim", ` (${segment.items.length} items — enter to expand)`) : "";
+			lines.push(truncateToWidth(`${cursor} ${swatch} ${segment.estimatedTokens.toString().padStart(6)} tok  ${percent.padStart(5)}  ${title}${drillHint}`, width, ""));
+		});
+		lines.push("");
+		lines.push(theme.fg("dim", "↑↓ select · enter expand · esc close"));
+		return lines;
+	}
+
+	private renderDrillDown(width: number): string[] {
+		const theme = this.theme;
+		const segment = this.drillDown!;
+		const items: ContextSegmentItem[] = segment.items ?? [];
+		const lines: string[] = [truncateToWidth(theme.fg("muted", `${segment.label} — largest first`), width, "")];
+		if (items.length === 0) {
+			lines.push(theme.fg("dim", "  (nothing to break down further)"));
+		} else {
+			const start = Math.max(0, Math.min(this.drillIndex - Math.floor(DRILLDOWN_VISIBLE_ROWS / 2), items.length - DRILLDOWN_VISIBLE_ROWS));
+			const end = Math.min(start + DRILLDOWN_VISIBLE_ROWS, items.length);
+			for (let index = start; index < end; index++) {
+				const item = items[index]!;
+				const selected = index === this.drillIndex;
+				const cursor = selected ? theme.fg("accent", "❯") : " ";
+				const title = selected ? theme.bold(item.label) : item.label;
+				lines.push(truncateToWidth(`${cursor} ${item.estimatedTokens.toString().padStart(6)} tok  ${title}`, width, ""));
+			}
+			lines.push(theme.fg("muted", `  ${this.drillIndex + 1}/${items.length}`));
+		}
+		lines.push("");
+		lines.push(theme.fg("dim", "↑↓ scroll · esc back"));
+		return lines;
+	}
+
+	handleInput(data: string): void {
+		if (this.drillDown) {
+			const items = this.drillDown.items ?? [];
+			if (matchesKey(data, "escape")) this.drillDown = null;
+			else if (matchesKey(data, "up")) this.drillIndex = Math.max(0, this.drillIndex - 1);
+			else if (matchesKey(data, "down")) this.drillIndex = Math.min(Math.max(0, items.length - 1), this.drillIndex + 1);
+			else return;
+		} else {
+			if (matchesKey(data, "escape")) { this.close(); return; }
+			if (matchesKey(data, "up")) this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+			else if (matchesKey(data, "down")) this.selectedIndex = Math.min(this.breakdown.segments.length - 1, this.selectedIndex + 1);
+			else if (matchesKey(data, "enter")) {
+				const segment = this.breakdown.segments[this.selectedIndex];
+				if (segment?.items && segment.items.length > 0) {
+					this.drillDown = segment;
+					this.drillIndex = 0;
+				}
+			} else return;
+		}
+		this.tui.requestRender();
+	}
+}
+
+/** Non-interactive fallback (print mode, RPC, etc.) reuses the existing plain-text report shape. */
+function fallbackReport(breakdown: ContextBreakdown, ruleBudget: ContextBudget["rules"]): string {
+	const skillsSegment = breakdown.segments.find((segment) => segment.key === "skills");
+	const other = breakdown.segments.find((segment) => segment.key === "other")!;
+	const totalLine = breakdown.totalTokens !== null
+		? `Real usage: ${breakdown.totalTokens} tokens${breakdown.effectiveBudget !== null ? ` / ${breakdown.effectiveBudget} usable budget (${percentOf(breakdown.totalTokens, breakdown.effectiveBudget)})` : ""}`
+		: "Real usage: not yet reported";
+	return [
+		totalLine,
+		`Everything else (base prompt, message history, tool defs): ~${other.estimatedTokens} tokens`,
+		"",
+		formatContextBudgetReport({ rules: ruleBudget, skills: { entries: [], totalCharacters: 0, totalEstimatedTokens: skillsSegment?.estimatedTokens ?? 0, scannedDirectories: [] }, totalEstimatedTokens: ruleBudget.totalEstimatedTokens }),
+	].join("\n");
+}
+
+export async function showContextView(ctx: ExtensionCommandContext, breakdown: ContextBreakdown, ruleBudget: ContextBudget["rules"]): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify(fallbackReport(breakdown, ruleBudget), "info");
+		return;
+	}
+	await ctx.ui.custom<void>((tui, theme, _keybindings, done) => new ContextViewport(tui, theme, breakdown, done));
+}

package/extension/src/docs.ts

@@ -1,9 +1,9 @@
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { DOC_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
 import { callService } from "./service-client.ts";
 
-const DOC_GLYPHS: Record<string, string> = { draft: "○", active: "●", archived: "■" };
 const DOC_ACTIONS: Record<string, string[]> = {
 	draft: ["Activate", "Archive"],
 	active: ["Archive"],
@@ -11,8 +11,9 @@ const DOC_ACTIONS: Record<string, string[]> = {
 };
 const DOC_RELATIONS = ["references", "documents", "supersedes", "relates_to", "contains", "part_of"];
 
-export function documentRowMeta(document: Artifact): string {
-	return [document.subtype, document.labels.join(", ")].filter(Boolean).join(" · ");
+export function documentRowMeta(document: Artifact, theme: Theme): string {
+	const subtype = document.subtype ? theme.fg("accent", document.subtype) : "";
+	return [subtype, document.labels.join(", ")].filter(Boolean).join(" · ");
 }
 
 export async function showDocs(ctx: ExtensionCommandContext): Promise<void> {
@@ -21,7 +22,7 @@ export async function showDocs(ctx: ExtensionCommandContext): Promise<void> {
 		title: "Documents",
 		listOperation: "docs.list",
 		statusOrder: ["draft", "active", "archived"],
-		glyphs: DOC_GLYPHS,
+		presentation: DOC_STATUS_PRESENTATION,
 		rowMeta: documentRowMeta,
 		actions: (document) => ["Show details", "Link artifact", ...(DOC_ACTIONS[document.status] ?? [])],
 		handleAction: async (choice, document, commandCtx) => {