@infinitedusky/indusk-mcp 1.16.1 → 1.17.0

package/dist/bin/commands/extensions.js

@@ -374,7 +374,7 @@ export async function extensionsUpdate(projectRoot, names) {
             continue;
         try {
             if (!ext.manifest._source) {
-                if (names && names.includes(name)) {
+                if (names?.includes(name)) {
                     console.info(`  ${name}: built-in extension — updated via package update, not extensions update`);
                 }
                 continue;
@@ -633,7 +633,10 @@ function printMcpInstructions(name, manifest) {
     const needsAuth = server.headers && Object.keys(server.headers).length > 0;
     // Remove first, then add — ensures clean state
     try {
-        execSync(`claude mcp remove -s project ${name}`, { timeout: 10000, stdio: ["ignore", "pipe", "pipe"] });
+        execSync(`claude mcp remove -s project ${name}`, {
+            timeout: 10000,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
     }
     catch {
         // not registered yet, fine

package/dist/bin/commands/init-docs.js

@@ -24,7 +24,7 @@ export async function initDocs(projectRoot) {
         mkdirSync(join(docsDir, dir), { recursive: true });
     }
     // package.json
-    writeFileSync(join(docsDir, "package.json"), JSON.stringify({
+    writeFileSync(join(docsDir, "package.json"), `${JSON.stringify({
         name: `${projectName}-docs`,
         version: "0.1.0",
         private: true,
@@ -42,7 +42,7 @@ export async function initDocs(projectRoot) {
             "vitepress-plugin-mermaid": "^2.0.10",
             vue: "^3.4.15",
         },
-    }, null, "\t") + "\n");
+    }, null, "\t")}\n`);
     // .vitepress/config.ts
     writeFileSync(join(docsDir, "src/.vitepress/config.ts"), `import { defineConfig } from "vitepress";
 import llmstxt from "vitepress-plugin-llms";

package/dist/lib/eval/prompt-builder.js

@@ -12,9 +12,32 @@ export function buildJudgePrompt(opts) {
     const questionsBlock = opts.rubric
         .map((q, i) => `${i + 1}. **${q.id}**: ${q.question}\n   Guidance: ${q.guidance}`)
         .join("\n\n");
+    const highlightsInstructions = opts.mode === "eval"
+        ? `### Step 4: Process unprocessed highlights
+
+Before answering the rubric, process the working agent's highlights queue. Highlights are the working agent's flagged moments — brief acceptances, ADR acceptances, corrections, retrospective lessons — and the eval agent is responsible for materializing them into structured Graphiti episodes.
+
+Call \`mcp__indusk__highlights_unprocessed\` to get the list. For each highlight, the level drives effort and Graphiti edge weight:
+
+- **critical** (architectural decision, accepted ADR, accepted brief): extract full context from the transcript and the changed files, write a structured Graphiti episode with weight **1.0**.
+- **important** (correction, retro lesson, confirmed pattern): extract context, write a Graphiti episode with weight **0.6**.
+- **note** (observation, partially-formed thought): consider it. Write a low-weight (**0.3**) episode if it adds signal; skip if it's already captured in an existing episode.
+
+Write each episode using \`mcp__indusk__graph_capture\` so it attaches to the relevant file anchor in the semantic graph — not raw \`mcp__graphiti__add_memory\`. Pick the group sensibly: \`${opts.projectGroup}\` for project-specific facts, \`shared\` for cross-project conventions (e.g., "always use pnpm ce"). Use the level to set the edge weight in the body's metadata section so downstream context-beam queries can rank by importance.
+
+After processing each highlight (whether you wrote an episode or decided to skip), call \`mcp__indusk__highlight_mark_processed\` with the highlight ID and the action:
+- \`action: "wrote-episode"\`, \`detail: "{episode name}"\` — if you wrote an episode.
+- \`action: "skipped"\`, \`detail: "{brief reason}"\` — if you decided not to (e.g., already captured, or not meaningful enough).
+
+**Highlights are additive context, not a constraint.** Continue reading the full transcript and inferring knowledge independently — highlights ensure important moments aren't missed, but they don't bound your analysis. The transcript may contain insights the working agent didn't flag.
+
+If \`mcp__indusk__highlights_unprocessed\` is unavailable, skip this step silently and continue.`
+        : `### Step 4: Highlights (baseline mode)
+
+Baseline mode — do NOT process highlights or write to Graphiti. Skip to Step 5.`;
     const graphitiInstructions = opts.mode === "eval"
         ? `
-## Step 5: Write findings to the knowledge graph
+### Step 6: Write findings to the knowledge graph
 
 For each finding with severity "warning" or "critical", write it using \`mcp__indusk__graph_capture\`. This dual-writes to both Graphiti AND the semantic graph, connecting the finding to the existing file anchor — so the context beam can find it later.
 
@@ -33,10 +56,10 @@ mcp__indusk__graph_capture({
 \`\`\`
 
 Only write facts that would have changed the outcome. Be selective — quality over quantity.
-Count how many graph_capture calls you made for the scorecard.
+Count how many graph_capture calls you made for the scorecard (this count includes any highlight episodes written in Step 4).
 If the tool is unavailable, skip silently and set graphitiWrites to 0.`
         : `
-## Step 5: Graphiti writes
+### Step 6: Graphiti writes
 
 Baseline mode — do NOT write to Graphiti. Set graphitiWrites to 0.`;
     return `You are the InDusk evaluation judge. Your job is to evaluate the quality of work done by an AI agent on a software project.
@@ -65,7 +88,9 @@ Run \`jj diff -r ${opts.changeId}\` to see what was committed. This is the work
 
 Then read the specific files that were changed to understand the full context — not just the diff lines, but the surrounding code.
 
-### Step 4: Answer the evaluation questions
+${highlightsInstructions}
+
+### Step 5: Answer the evaluation questions
 
 For each question, investigate thoroughly using MCP tools — search the codebase, query the code graph, check Graphiti for relevant facts. Then answer with this exact JSON shape per question:
 
@@ -88,7 +113,7 @@ Questions:
 ${questionsBlock}
 ${graphitiInstructions}
 
-## Step 6: Output the scorecard
+### Step 7: Output the scorecard
 
 After completing all steps, output ONLY the following JSON object. No markdown wrapping, no commentary before or after — just the JSON:
 
@@ -99,7 +124,7 @@ After completing all steps, output ONLY the following JSON object. No markdown w
   "mode": "${opts.mode}",
   "changeId": "${opts.changeId}",
   "projectGroup": "${opts.projectGroup}",
-  "questions": [/* your answers from Step 4 */],
+  "questions": [/* your answers from Step 5 */],
   "summary": "{one paragraph overall assessment}",
   "graphitiWrites": {number of Graphiti writes made},
   "telemetryPosted": false

package/dist/lib/highlights/highlights.d.ts

@@ -0,0 +1,48 @@
+export type HighlightLevel = "critical" | "important" | "note";
+export type ProcessedAction = "wrote-episode" | "skipped";
+export interface Highlight {
+    id: string;
+    timestamp: string;
+    level: HighlightLevel;
+    tag: string;
+    note: string;
+}
+export interface ProcessedMark {
+    id: string;
+    processedAt: string;
+    action: ProcessedAction;
+    detail?: string;
+}
+export interface WriteHighlightInput {
+    tag: string;
+    note: string;
+    level: HighlightLevel;
+}
+/**
+ * Append a highlight to the plan-scoped `.indusk/highlights.jsonl` queue.
+ * Called by the working agent (via the `highlight` MCP tool) at trigger
+ * points — brief accepted, ADR accepted, correction confirmed, retro
+ * lesson, manual `/highlight` flag. The eval agent reads these later
+ * and turns them into structured Graphiti episodes.
+ *
+ * The ID is `h-{YYYYMMDD}-{seq}` where `seq` is a 3-digit counter that
+ * resets daily. The timestamp is ISO 8601 UTC.
+ */
+export declare function writeHighlight(projectRoot: string, input: WriteHighlightInput): Highlight;
+/**
+ * Return all highlights whose IDs don't yet appear in the processed log.
+ * Used by the eval agent (via the `highlights_unprocessed` MCP tool) to
+ * find highlights that haven't been written to Graphiti yet.
+ */
+export declare function readUnprocessedHighlights(projectRoot: string): Highlight[];
+/**
+ * Mark a highlight as processed. Called by the eval agent (via the
+ * `highlight_mark_processed` MCP tool) after handling a highlight —
+ * either writing a structured Graphiti episode (`wrote-episode`) or
+ * deciding the highlight doesn't warrant a new episode (`skipped`).
+ *
+ * The operation is idempotent by design — appending a processed mark
+ * for an already-processed ID just adds a duplicate entry, and
+ * `readUnprocessedHighlights` uses a Set so duplicates don't matter.
+ */
+export declare function markProcessed(projectRoot: string, id: string, action: ProcessedAction, detail?: string): ProcessedMark;

package/dist/lib/highlights/highlights.js

@@ -0,0 +1,136 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+function highlightsPath(projectRoot) {
+    return join(projectRoot, ".indusk", "highlights.jsonl");
+}
+function processedPath(projectRoot) {
+    return join(projectRoot, ".indusk", "highlights-processed.jsonl");
+}
+function ensureInduskDir(projectRoot) {
+    mkdirSync(join(projectRoot, ".indusk"), { recursive: true });
+}
+function todayStamp() {
+    return new Date().toISOString().slice(0, 10).replace(/-/g, "");
+}
+/**
+ * Read all highlights from the JSONL queue. Returns empty array if the
+ * file doesn't exist. Malformed lines are skipped with a silent warning
+ * (matching the semantic-graph / falsification log resilience pattern).
+ */
+function readAllHighlights(projectRoot) {
+    const path = highlightsPath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    const content = readFileSync(path, "utf-8");
+    const lines = content.split("\n").filter((l) => l.length > 0);
+    const highlights = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed.id === "string") {
+                highlights.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return highlights;
+}
+function readAllProcessed(projectRoot) {
+    const path = processedPath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    const content = readFileSync(path, "utf-8");
+    const lines = content.split("\n").filter((l) => l.length > 0);
+    const marks = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed.id === "string") {
+                marks.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return marks;
+}
+/**
+ * Compute the next sequence number for today's highlights. Reads all
+ * existing highlights, filters to entries whose ID starts with today's
+ * date, takes max seq, adds 1. Starts at 001 if none exist for today.
+ */
+function nextSeqForToday(projectRoot) {
+    const today = todayStamp();
+    const prefix = `h-${today}-`;
+    const highlights = readAllHighlights(projectRoot);
+    let maxSeq = 0;
+    for (const h of highlights) {
+        if (!h.id.startsWith(prefix))
+            continue;
+        const seqStr = h.id.slice(prefix.length);
+        const seq = Number.parseInt(seqStr, 10);
+        if (!Number.isNaN(seq) && seq > maxSeq) {
+            maxSeq = seq;
+        }
+    }
+    return maxSeq + 1;
+}
+/**
+ * Append a highlight to the plan-scoped `.indusk/highlights.jsonl` queue.
+ * Called by the working agent (via the `highlight` MCP tool) at trigger
+ * points — brief accepted, ADR accepted, correction confirmed, retro
+ * lesson, manual `/highlight` flag. The eval agent reads these later
+ * and turns them into structured Graphiti episodes.
+ *
+ * The ID is `h-{YYYYMMDD}-{seq}` where `seq` is a 3-digit counter that
+ * resets daily. The timestamp is ISO 8601 UTC.
+ */
+export function writeHighlight(projectRoot, input) {
+    ensureInduskDir(projectRoot);
+    const seq = nextSeqForToday(projectRoot);
+    const entry = {
+        id: `h-${todayStamp()}-${String(seq).padStart(3, "0")}`,
+        timestamp: new Date().toISOString(),
+        level: input.level,
+        tag: input.tag,
+        note: input.note,
+    };
+    appendFileSync(highlightsPath(projectRoot), `${JSON.stringify(entry)}\n`, "utf-8");
+    return entry;
+}
+/**
+ * Return all highlights whose IDs don't yet appear in the processed log.
+ * Used by the eval agent (via the `highlights_unprocessed` MCP tool) to
+ * find highlights that haven't been written to Graphiti yet.
+ */
+export function readUnprocessedHighlights(projectRoot) {
+    const highlights = readAllHighlights(projectRoot);
+    if (highlights.length === 0)
+        return [];
+    const processedIds = new Set(readAllProcessed(projectRoot).map((m) => m.id));
+    return highlights.filter((h) => !processedIds.has(h.id));
+}
+/**
+ * Mark a highlight as processed. Called by the eval agent (via the
+ * `highlight_mark_processed` MCP tool) after handling a highlight —
+ * either writing a structured Graphiti episode (`wrote-episode`) or
+ * deciding the highlight doesn't warrant a new episode (`skipped`).
+ *
+ * The operation is idempotent by design — appending a processed mark
+ * for an already-processed ID just adds a duplicate entry, and
+ * `readUnprocessedHighlights` uses a Set so duplicates don't matter.
+ */
+export function markProcessed(projectRoot, id, action, detail) {
+    ensureInduskDir(projectRoot);
+    const mark = {
+        id,
+        processedAt: new Date().toISOString(),
+        action,
+        detail,
+    };
+    appendFileSync(processedPath(projectRoot), `${JSON.stringify(mark)}\n`, "utf-8");
+    return mark;
+}

package/dist/lib/semantic-graph/index.d.ts

@@ -11,4 +11,4 @@ export { LogWriter } from "./log-writer.js";
 export * from "./paths.js";
 export { type ReplayOptions, type ReplayResult, replay } from "./replay.js";
 export { SemanticGraphClient, type SemanticGraphClientOptions } from "./runtime-client.js";
-export { type SyncResult, runSync } from "./sync-engine.js";
+export { runSync, type SyncResult } from "./sync-engine.js";

package/dist/lib/trajectory/audit.js

@@ -75,12 +75,12 @@ export function resolveTestIdCommand(trajectory, id) {
         return null;
     const backtickMatches = [...row.asserts.matchAll(/`([^`]+)`/g)].map((m) => m[1]);
     const identifiers = [...row.asserts.matchAll(/\b[a-zA-Z][a-zA-Z0-9_]{3,}\b/g)].map((m) => m[0]);
-    const keyword = backtickMatches
-        .filter((s) => /[a-zA-Z]/.test(s))
-        .sort((a, b) => b.length - a.length)[0] ??
+    const keyword = backtickMatches.filter((s) => /[a-zA-Z]/.test(s)).sort((a, b) => b.length - a.length)[0] ??
         identifiers.sort((a, b) => b.length - a.length)[0] ??
         null;
-    const fileGlob = keyword ? `**/*${keyword.toLowerCase().replace(/[^a-z0-9]/g, "")}*.test.ts` : null;
+    const fileGlob = keyword
+        ? `**/*${keyword.toLowerCase().replace(/[^a-z0-9]/g, "")}*.test.ts`
+        : null;
     const suggestedCommand = keyword
         ? `pnpm test -t "${keyword}"`
         : `pnpm test -t "${row.asserts.slice(0, 40)}"`;

package/dist/server/index.js

@@ -16,6 +16,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { registerContextTools } from "../tools/context-tools.js";
 import { registerDocumentTools } from "../tools/document-tools.js";
 import { registerGraphTools } from "../tools/graph-tools.js";
+import { registerHighlightTools } from "../tools/highlight-tools.js";
 import { registerLessonTools } from "../tools/lesson-tools.js";
 import { registerPlanTools } from "../tools/plan-tools.js";
 import { registerQualityTools } from "../tools/quality-tools.js";
@@ -58,6 +59,7 @@ export async function startServer() {
         registerSystemTools(server, projectRoot);
         registerGraphTools(server, projectRoot);
         registerLessonTools(server, projectRoot);
+        registerHighlightTools(server, projectRoot);
         console.error("[indusk] tools registered");
         const transport = new StdioServerTransport();
         await server.connect(transport);

package/dist/tools/highlight-tools.d.ts

@@ -0,0 +1,18 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Register the three highlight MCP tools:
+ *
+ * - `highlight` — the working agent writes a highlight at trigger points
+ *   (brief accepted, ADR accepted, correction confirmed, retro lesson,
+ *   manual /highlight). The highlight is append-only to
+ *   .indusk/highlights.jsonl.
+ * - `highlights_unprocessed` — the eval agent reads unprocessed
+ *   highlights to decide what to turn into Graphiti episodes.
+ * - `highlight_mark_processed` — the eval agent marks a highlight as
+ *   processed (either wrote-episode or skipped) to move it out of the
+ *   unprocessed queue.
+ *
+ * See .indusk/planning/agent-roles/adr.md for the three-tier role model
+ * and the highlights-queue interface.
+ */
+export declare function registerHighlightTools(server: McpServer, projectRoot: string): void;

package/dist/tools/highlight-tools.js

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { markProcessed, readUnprocessedHighlights, writeHighlight, } from "../lib/highlights/highlights.js";
+/**
+ * Register the three highlight MCP tools:
+ *
+ * - `highlight` — the working agent writes a highlight at trigger points
+ *   (brief accepted, ADR accepted, correction confirmed, retro lesson,
+ *   manual /highlight). The highlight is append-only to
+ *   .indusk/highlights.jsonl.
+ * - `highlights_unprocessed` — the eval agent reads unprocessed
+ *   highlights to decide what to turn into Graphiti episodes.
+ * - `highlight_mark_processed` — the eval agent marks a highlight as
+ *   processed (either wrote-episode or skipped) to move it out of the
+ *   unprocessed queue.
+ *
+ * See .indusk/planning/agent-roles/adr.md for the three-tier role model
+ * and the highlights-queue interface.
+ */
+export function registerHighlightTools(server, projectRoot) {
+    server.registerTool("highlight", {
+        description: "Write a highlight to the queue. Called by the working agent at trigger points — brief/ADR acceptance, corrections, retro lessons, or explicit user flags. The eval agent processes these later into structured Graphiti episodes.",
+        inputSchema: {
+            tag: z
+                .string()
+                .describe("Short tag for the highlight type: brief-accepted, adr-accepted, correction, retro-lesson, observation, or a custom tag."),
+            note: z.string().describe("The highlight content — a single line describing what matters."),
+            level: z
+                .enum(["critical", "important", "note"])
+                .describe("Weight level: critical = architectural decision, important = correction/lesson, note = observation."),
+        },
+    }, async ({ tag, note, level }) => {
+        const entry = writeHighlight(projectRoot, { tag, note, level });
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(entry, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("highlights_unprocessed", {
+        description: "Return all highlights that haven't yet been marked as processed. Called by the eval agent to find highlights needing structured episodes.",
+    }, async () => {
+        const unprocessed = readUnprocessedHighlights(projectRoot);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(unprocessed, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerTool("highlight_mark_processed", {
+        description: "Mark a highlight as processed. Called by the eval agent after handling a highlight — either writing a structured Graphiti episode (wrote-episode) or deciding not to (skipped).",
+        inputSchema: {
+            id: z.string().describe("The highlight ID to mark (format: h-YYYYMMDD-NNN)."),
+            action: z
+                .enum(["wrote-episode", "skipped"])
+                .describe("What was done: wrote-episode = structured episode created; skipped = no episode."),
+            detail: z
+                .string()
+                .optional()
+                .describe("Optional detail — for wrote-episode, the episode name; for skipped, the reason."),
+        },
+    }, async ({ id, action, detail }) => {
+        const mark = markProcessed(projectRoot, id, action, detail);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(mark, null, 2),
+                },
+            ],
+        };
+    });
+}

package/hooks/check-catchup.js

@@ -12,8 +12,8 @@
  */
 
 import { execSync } from "node:child_process";
-import { createConnection } from "node:net";
 import { existsSync, readFileSync } from "node:fs";
+import { createConnection } from "node:net";
 import { join, resolve } from "node:path";
 
 const input = JSON.parse(readFileSync("/dev/stdin", "utf-8"));
@@ -38,9 +38,15 @@ function checkTcp(host, port, timeoutMs = 3000) {
 	return new Promise((resolve) => {
 		const sock = createConnection({ host, port });
 		sock.setTimeout(timeoutMs);
-		sock.on("connect", () => { sock.end(); resolve(true); });
+		sock.on("connect", () => {
+			sock.end();
+			resolve(true);
+		});
 		sock.on("error", () => resolve(false));
-		sock.on("timeout", () => { sock.destroy(); resolve(false); });
+		sock.on("timeout", () => {
+			sock.destroy();
+			resolve(false);
+		});
 	});
 }
 
@@ -61,7 +67,9 @@ if (filePath.endsWith("handoff.md")) {
 		// Check FalkorDB (indusk-infra container) on localhost:6379
 		const falkorUp = await checkTcp("localhost", 6379);
 		if (!falkorUp) {
-			errors.push("FalkorDB not reachable on localhost:6379 — is indusk-infra running? Try: docker start indusk-infra");
+			errors.push(
+				"FalkorDB not reachable on localhost:6379 — is indusk-infra running? Try: docker start indusk-infra",
+			);
 		}
 
 		// Check Graphiti on localhost:8100
@@ -75,14 +83,17 @@ if (filePath.endsWith("handoff.md")) {
 				errors.push("Graphiti responded but not healthy on localhost:8100");
 			}
 		} catch {
-			errors.push("Graphiti MCP server not reachable on localhost:8100 — may still be starting (~90s after container restart)");
+			errors.push(
+				"Graphiti MCP server not reachable on localhost:8100 — may still be starting (~90s after container restart)",
+			);
 		}
 
 		if (errors.length > 0) {
 			process.stderr.write(
 				`Cannot check off mcp-ready — infrastructure verification failed:\n` +
-				errors.map((e) => `  - ${e}`).join("\n") + "\n" +
-				`Fix the issues above before proceeding with catchup.`,
+					errors.map((e) => `  - ${e}`).join("\n") +
+					"\n" +
+					`Fix the issues above before proceeding with catchup.`,
 			);
 			process.exit(2);
 		}

package/hooks/eval-trigger.js

@@ -1,11 +1,17 @@
 #!/usr/bin/env node
 
 /**
- * PostToolUse hook: triggers the eval judge after `jj describe`.
+ * Dual-mode eval trigger.
  *
- * Fires on Bash tool calls containing "jj describe". Spawns the judge runner
- * as a detached background process and exits immediately — never blocks the
- * working session.
+ * 1) PostToolUse hook mode (default): fires on Bash tool calls containing
+ *    `jj describe`. Reads the hook event JSON from stdin. Spawns the judge
+ *    runner as a detached background process.
+ *
+ * 2) CLI mode (`--source <tag>`): invoked manually by skills (e.g., handoff)
+ *    at session end. No stdin read, no `jj describe` filter. Uses the current
+ *    @ change and passes the source tag to the judge via INDUSK_EVAL_SOURCE.
+ *    The judge may skip diff-based scoring when source != "commit" but still
+ *    processes the highlights queue.
  *
  * Exit 0 always — this is advisory, not blocking.
  */
@@ -26,25 +32,46 @@ function syslog(projectRoot, msg) {
 	}
 }
 
-// Read hook input from stdin
-let input = "";
-for await (const chunk of process.stdin) {
-	input += chunk;
+// Parse --source <tag> from argv. Returns null if not in CLI mode.
+function parseSourceArg(argv) {
+	const idx = argv.indexOf("--source");
+	if (idx === -1 || idx === argv.length - 1) return null;
+	const value = argv[idx + 1];
+	if (!value || value.startsWith("--")) return null;
+	return value;
 }
 
-const event = JSON.parse(input);
-const toolInput = event.tool_input ?? {};
-const command = toolInput.command ?? "";
-const cwd = event.cwd ?? process.cwd();
+const cliSource = parseSourceArg(process.argv);
+let cwd;
+let command = "";
 
-syslog(cwd, `hook fired — tool: ${event.tool_name}, command: ${command.slice(0, 100)}`);
+if (cliSource !== null) {
+	// CLI mode — no stdin, no jj describe filter
+	cwd = process.cwd();
+	syslog(cwd, `cli invocation — source: ${cliSource}`);
+} else {
+	// Hook mode — read event from stdin
+	let input = "";
+	for await (const chunk of process.stdin) {
+		input += chunk;
+	}
 
-// Fast path: not a jj describe command
-if (!command.includes("jj describe")) {
-	syslog(cwd, "skip — no jj describe in command");
-	process.exit(0);
+	const event = JSON.parse(input);
+	const toolInput = event.tool_input ?? {};
+	command = toolInput.command ?? "";
+	cwd = event.cwd ?? process.cwd();
+
+	syslog(cwd, `hook fired — tool: ${event.tool_name}, command: ${command.slice(0, 100)}`);
+
+	// Fast path: not a jj describe command
+	if (!command.includes("jj describe")) {
+		syslog(cwd, "skip — no jj describe in command");
+		process.exit(0);
+	}
 }
 
+const source = cliSource ?? "commit";
+
 /**
  * Find the project root by walking up looking for .indusk/ or .claude/.
  */
@@ -157,7 +184,7 @@ if (!judgeRunnerPath) {
 		message:
 			"Could not find @infinitedusky/indusk-mcp package — eval judge not available. Run: npm i -g @infinitedusky/indusk-mcp",
 	});
-	appendFileSync(logPath, entry + "\n", "utf8");
+	appendFileSync(logPath, `${entry}\n`, "utf8");
 	process.exit(0);
 }
 
@@ -238,21 +265,30 @@ const child = spawn("node", ["--input-type=module", "-e", judgeScript], {
 	cwd: projectRoot,
 	stdio: "ignore",
 	detached: true,
-	env: { ...process.env },
+	env: { ...process.env, INDUSK_EVAL_SOURCE: source },
 });
 
 child.unref();
 
-// Output advisory message
-const output = JSON.stringify({
-	hookSpecificOutput: {
-		hookEventName: "PostToolUse",
-		message: `Eval judge spawned for change ${changeId.slice(0, 8)}`,
-	},
-});
-process.stdout.write(output);
-process.stderr.write(
-	`📊 Eval judge spawned in background for ${changeId.slice(0, 8)}. Results will appear in .indusk/eval/results.log\n`,
-);
+syslog(projectRoot, `judge spawned — source: ${source}, pid: ${child.pid}`);
+
+if (cliSource !== null) {
+	// CLI mode — write a brief notice to stderr and exit
+	process.stderr.write(
+		`📊 Eval judge spawned (source=${source}) for ${changeId.slice(0, 8)}. Results will appear in .indusk/eval/results.log\n`,
+	);
+} else {
+	// Hook mode — output structured hook response
+	const output = JSON.stringify({
+		hookSpecificOutput: {
+			hookEventName: "PostToolUse",
+			message: `Eval judge spawned for change ${changeId.slice(0, 8)}`,
+		},
+	});
+	process.stdout.write(output);
+	process.stderr.write(
+		`📊 Eval judge spawned in background for ${changeId.slice(0, 8)}. Results will appear in .indusk/eval/results.log\n`,
+	);
+}
 
 process.exit(0);

package/hooks/gate-reminder.js

@@ -93,13 +93,11 @@ for (const phase of phases) {
 		const nextHasUnchecked = nextPhase.items.some((i) => !i.checked);
 		if (nextHasUnchecked) {
 			// This phase is complete and next phase hasn't started
-			const result = {
+			const _result = {
 				hookSpecificOutput: {
 					hookEventName: "PostToolUse",
 				},
 			};
-			// Output reminder as JSON to stdout
-			console.log(JSON.stringify(result));
 			console.error(
 				`Phase ${phase.number} (${phase.name}) is fully complete. Call advance_plan to validate gates before starting Phase ${nextPhase.number}.`,
 			);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.16.1",
+	"version": "1.17.0",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/handoff.md

@@ -52,6 +52,20 @@ Create or overwrite `.claude/handoff.md` with:
 - When you're about to run out of context
 - `/handoff` explicitly
 
+## Fire the Eval Trigger
+
+After writing the handoff file, fire the eval trigger with `--source handoff` so the eval agent processes any unprocessed highlights before the session ends. This matters because highlights written after the last `jj describe` would otherwise sit in the queue until the next session's first commit.
+
+Run this from the project root:
+
+```bash
+node .claude/hooks/eval-trigger.js --source handoff
+```
+
+The trigger spawns the judge in the background and returns immediately — it never blocks handoff. The judge processes the highlights queue and, because `INDUSK_EVAL_SOURCE=handoff` is set in the environment, may skip diff-based rubric scoring (there's no new commit). Highlights still get materialized into Graphiti episodes.
+
+If the hook isn't installed or Node isn't on PATH, the handoff still succeeds — the highlights remain queued for the next `jj describe` in a future session.
+
 ## Rules
 
 - **Be specific.** "Working on Phase 3" is useless. "Phase 3, item 4: refactored check_health to use extensions. extensions_status MCP tool created. Next: refactor init to remove hardcoded FalkorDB/CGC." is useful.

package/skills/highlight.md

@@ -0,0 +1,50 @@
+---
+name: highlight
+description: Flag a moment in the session as worth remembering. Writes a highlight to the queue so the eval agent can materialize it into a structured Graphiti episode.
+---
+
+You are flagging something the user wants captured — an observation, a decision, a surprise, a lesson that isn't an official retrospective yet. Write a highlight to the queue. The eval agent will process it into a structured Graphiti episode on the next `jj describe` or at session end.
+
+## Invocation
+
+The user runs `/highlight {free-form text} [level: critical|important|note]`.
+
+- If no level is specified, **default to `important`**.
+- If the user's phrasing clearly signals weight (`critical`, `important`, `note`, or synonyms like `major`, `minor`), use that.
+- If the user passes `level=critical` / `level=note` explicitly, honor it.
+
+## Process
+
+1. **Parse the input.** Extract the note text. If the user wrote `/highlight level=critical decide X over Y`, strip the `level=` prefix out of the note.
+
+2. **Choose a tag.** Tags categorize the highlight for the eval agent. Pick one of:
+   - `observation` — general flag (default)
+   - `decision` — an informal decision the user wants recorded
+   - `surprise` — something unexpected
+   - `correction` — a mid-session correction (but the work skill already does this on `context learn`; prefer that path)
+   - A user-supplied tag if the message contains one (`tag=architecture` etc.)
+
+3. **Write the highlight** via the InDusk MCP:
+
+   ```
+   mcp__indusk__highlight({
+     tag: "{chosen tag}",
+     note: "{the user's text, cleaned of any level= or tag= prefixes}",
+     level: "{critical|important|note}"
+   })
+   ```
+
+4. **Confirm to the user** with the generated ID and a one-line summary:
+
+   > "Highlighted as `h-20260417-007` (level: critical, tag: decision). The eval agent will pick this up on the next `jj describe` or at session end."
+
+## Rules
+
+- **Default level is `important`.** Only bump to `critical` if the user explicitly says so or the content is clearly an architectural / decision-level moment.
+- **Do not write the Graphiti episode yourself.** The whole point of highlights is that the working agent flags and moves on; the eval agent handles materialization.
+- **If `mcp__indusk__highlight` is unavailable**, degrade gracefully: tell the user "highlights queue unavailable — InDusk MCP may be down" and do not fail.
+- **One highlight per invocation.** If the user flags multiple things at once, ask them to split or pick the most important one to flag.
+
+## Cross-reference
+
+See [`apps/indusk-docs/src/reference/tools/highlights.md`](../../indusk-docs/src/reference/tools/highlights.md) for the full highlights system — file format, level → Graphiti edge weight mapping, eval agent processing, and trigger points across other skills.

package/skills/planner.md

@@ -74,31 +74,27 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
 4. **If research is done**, write the brief. This is where a direction emerges from the research. The brief proposes what we're building and why, informed by what the research uncovered. **Consider creating a visual sketch** of the proposed architecture with Excalidraw (if the extension is enabled) — a hand-drawn diagram makes the proposal concrete and easier to discuss. **Present the brief and have a conversation about it.** Don't just ask "does this look good?" — walk the user through it: "Here's what I'm proposing we build. Does this match what you had in mind? Is there anything missing, or anything here you don't want?" Iterate until the user is genuinely happy with the direction, then mark it as `accepted`.
 
-   **When the brief moves from `draft` to `accepted`**, capture the decision in Graphiti:
+   **When the brief moves from `draft` to `accepted`**, write a highlight so the eval agent can turn it into a structured Graphiti episode:
    ```
-   mcp__graphiti__add_memory({
-     name: "brief-accepted-{plan-name}",
-     episode_body: "{Problem}\n\n{Proposed Direction}\n\n{Scope summary if helpful}",
-     group_id: "{project-group}",
-     source: "text",
-     source_description: "brief acceptance"
+   mcp__indusk__highlight({
+     tag: "brief-accepted",
+     note: "{plan-name}: {one-line summary of Proposed Direction}",
+     level: "critical"
    })
    ```
-   The `group_id` is the project group (use `getProjectGroupId(projectRoot)` from `apps/indusk-mcp/src/lib/config.ts` — defaults to project directory basename, override via `.indusk/config.json` `graphiti.groupId`). Skip silently if `mcp__graphiti__add_memory` is unavailable (Graphiti may be down — degrade gracefully, do not fail the brief acceptance). Prefer `mcp__indusk__graph_capture` over raw `mcp__graphiti__add_memory` — it dual-writes to both Graphiti and the semantic graph event log.
+   The working agent does not write Graphiti episodes directly. The eval agent reads unprocessed highlights (via `highlights_unprocessed`), extracts the full Problem + Proposed Direction + Scope context from the transcript, writes a structured episode into the project group, and marks the highlight processed. Skip silently if `mcp__indusk__highlight` is unavailable — highlights are best-effort and must not fail brief acceptance. See [`apps/indusk-docs/src/reference/tools/highlights.md`](../../indusk-docs/src/reference/tools/highlights.md) for the full flow.
 
 5. **If brief is accepted** and the workflow includes an ADR (feature only), write the ADR. The ADR formalizes the decisions that were discussed during research and led to the brief. It records what was chosen, what was rejected, and why. **After the ADR is accepted**, add a one-liner to CLAUDE.md's Key Decisions section per the context skill: `- {decision summary} — see .indusk/planning/{plan}/adr.md`
 
-   **When the ADR moves from `proposed` to `accepted`**, capture the Y-statement in Graphiti:
+   **When the ADR moves from `proposed` to `accepted`**, write a highlight so the eval agent can turn it into a structured Y-statement episode:
    ```
-   mcp__graphiti__add_memory({
-     name: "adr-{plan-name}",
-     episode_body: "In context facing: {use case AND constraint}. We decided for: {chosen option}. And against: {rejected alternatives}. To achieve: {desired outcome}. Accepting: {tradeoff}. Because: {rationale}.",
-     group_id: "{project-group}",
-     source: "text",
-     source_description: "ADR acceptance"
+   mcp__indusk__highlight({
+     tag: "adr-accepted",
+     note: "{plan-name}: {chosen option} — rejected {primary alternative}",
+     level: "critical"
    })
    ```
-   The Y-statement is rich enough that Graphiti will extract entities for the chosen option, rejected alternatives, constraint, and rationale — and will detect contradictions if a later ADR overrides this one. Skip silently on Graphiti unavailability. Prefer `mcp__indusk__graph_capture` over raw `mcp__graphiti__add_memory` — it dual-writes to both Graphiti and the semantic graph event log.
+   The eval agent reads the highlight, pulls the full Y-statement from the ADR file, writes a structured episode into the project group, and marks it processed. Graphiti's entity extraction will pick up the chosen option, rejected alternatives, constraint, and rationale, and will detect contradictions if a later ADR overrides this one. The working agent does not write the episode directly. Skip silently on highlight unavailability — degrade gracefully.
 
 6. **If ADR is accepted** (or brief is accepted for bugfix/refactor), write the impl. Break into phased checklists with concrete tasks. For refactor workflows, include a `## Boundary Map` section. For multi-phase impls of any type, consider adding a boundary map.
 

package/skills/retrospective.md

@@ -113,7 +113,17 @@ For each finding, act on it:
 - **Deferred rows classified as `downstream-plan`** — verify the referenced plan exists and is either `accepted` or `in-progress`. If it's `draft` or missing, either accept the referenced plan now or pick a different mitigation.
 - **Deferred rows classified as `telemetry-alert`** — verify the named metric actually exists in the codebase (grep for it). If the metric hasn't been wired up, the mitigation is aspirational — either wire it up now or change the mitigation.
 
-Capture findings as a `retrospective-audit-{plan-slug}` episode in Graphiti (use `mcp__indusk__graph_capture` to dual-write to the semantic log). Include the classification, the warning (if any), and what was done. This is the signal the eval agent uses to detect mitigation drift over time.
+Flag findings as a highlight — the eval agent reads it, writes the `retrospective-audit-{plan-slug}` Graphiti episode, and marks it processed:
+
+```
+mcp__indusk__highlight({
+  tag: "retro-audit",
+  note: "{plan-name}: {finding classification}; {what was done}; {warning if any}",
+  level: "important"
+})
+```
+
+Include the classification, the warning (if any), and what was done. This is the signal the eval agent uses to detect mitigation drift over time.
 
 ### Step 5: Quality Audit
 
@@ -140,35 +150,31 @@ If yes, call `add_lesson` for each one. These become personal lessons in `.claud
 
 If no lessons emerged, that's fine — not every plan produces new knowledge. Move on.
 
-**Also capture each retrospective insight in Graphiti** so it becomes part of the temporal knowledge graph and can surface in future searches and contradictions.
+**Also flag each retrospective insight as a highlight** so the eval agent can turn it into a structured Graphiti episode and surface it in future searches and contradiction detection.
 
 For each item in the retrospective's **What We Learned** section:
 ```
-mcp__graphiti__add_memory({
-  name: "retro-{plan-name}-{n}",
-  episode_body: "{the full insight, including context — not just a one-line summary}",
-  group_id: "{project-group}",
-  source: "text",
-  source_description: "retrospective lesson"
+mcp__indusk__highlight({
+  tag: "retro-lesson",
+  note: "{plan-name}: {the insight, with enough context for the eval agent to write a full episode}",
+  level: "important"
 })
 ```
 
 For each item in the retrospective's **What We'd Do Differently** section:
 ```
-mcp__graphiti__add_memory({
-  name: "retro-{plan-name}-wdid-{n}",
-  episode_body: "{the hindsight item, with reasoning}",
-  group_id: "{project-group}",
-  source: "text",
-  source_description: "retrospective hindsight"
+mcp__indusk__highlight({
+  tag: "retro-hindsight",
+  note: "{plan-name}: {the hindsight item, with reasoning}",
+  level: "important"
 })
 ```
 
-Use the project group (from `getProjectGroupId(projectRoot)`) — most retrospective insights are project-specific. Promote to `shared` only if the insight is clearly cross-project (those should also become a personal lesson via `add_lesson`).
+The eval agent reads each highlight, writes the full Graphiti episode (project group by default; `shared` if the insight is clearly cross-project), and marks it processed. The working agent does not write the episode directly.
 
-**Contradictions:** If the retrospective surfaces a moment where "we thought X but found Y", capture both as separate episodes. Graphiti's contradiction detection will invalidate the older fact when it sees the conflicting one. This is one of Graphiti's most useful features — it remembers that a previous assumption was overturned, so the agent doesn't accidentally re-introduce it later.
+**Contradictions:** If the retrospective surfaces a moment where "we thought X but found Y", write two highlights (one per fact). Graphiti's contradiction detection will invalidate the older fact when it sees the conflicting one once the eval agent materializes the episodes. This is one of Graphiti's most useful features — it remembers that a previous assumption was overturned, so the agent doesn't accidentally re-introduce it later.
 
-Skip silently if `mcp__graphiti__add_memory` is unavailable — Graphiti capture is best-effort, and lesson recording via `add_lesson` is the canonical path. Graphiti capture is supplementary. Prefer `mcp__indusk__graph_capture` over raw `mcp__graphiti__add_memory` — it dual-writes to both Graphiti and the semantic graph event log.
+Skip silently if `mcp__indusk__highlight` is unavailable — highlights are best-effort, and lesson recording via `add_lesson` remains the canonical local path. Highlight-driven Graphiti capture is supplementary.
 
 ### Step 7: Context Audit
 

package/skills/work.md

@@ -259,26 +259,20 @@ When you are corrected mid-work — the user says "no, not that way" or "don't d
 
 Don't wait to be told. Corrections are the most valuable source of project knowledge.
 
-**When the user confirms `context learn`, ALSO capture the correction in Graphiti:**
+**When the user confirms `context learn`, ALSO write a highlight so the eval agent can capture it in Graphiti:**
 ```
-mcp__graphiti__add_memory({
-  name: "correction-{slug}",
-  episode_body: "{lesson text}",
-  group_id: "{shared OR project-group}",
-  source: "text",
-  source_description: "user correction"
+mcp__indusk__highlight({
+  tag: "correction",
+  note: "{short slug + lesson text}",
+  level: "important"
 })
 ```
 
-Where `{slug}` is a short kebab-case label for the topic (e.g. `correction-pnpm-ce`, `correction-graphiti-error-handling`).
+The working agent does not write the Graphiti episode directly. The eval agent reads the highlight, decides whether it's a cross-project convention (→ `shared` group) or a project-specific fact (→ project group), phrases the episode, and writes it. The working agent just flags the moment and keeps working.
 
-**Choosing `shared` vs project group:**
-- **`shared`**: tools, conventions, patterns that apply across projects. Examples: "always use pnpm ce", "never mock the database in integration tests", "use jj describe-then-do for commits". The lesson is generally true and a different project would benefit from it.
-- **`{project-group}`**: facts specific to this project's code, data, or domain. Examples: "the impl-parser handles four gate types per phase", "graph_ensure auto-repairs the indusk-infra container". The lesson only makes sense in the context of this project.
+**What to include in the `note`:** enough for the eval agent to reconstruct the lesson and classify its scope. Example: `pnpm-ce: always use pnpm ce, not npx — skill doc specifies pnpm and mixing causes cache drift`. The eval agent has the full transcript, so concision over completeness is fine.
 
-When in doubt, ask: "Would this correction make sense to a different project?" Yes → `shared`. No → project group.
-
-Use `getProjectGroupId(projectRoot)` from `apps/indusk-mcp/src/lib/config.ts` to get the project group consistently. Skip silently if `mcp__graphiti__add_memory` is unavailable — Graphiti capture is best-effort, do not fail the work item. Prefer `mcp__indusk__graph_capture` over raw `mcp__graphiti__add_memory` — it dual-writes to both Graphiti and the semantic graph event log.
+Skip silently if `mcp__indusk__highlight` is unavailable — highlights are best-effort and must not fail the work item or the `context learn` recording (which is the canonical, local copy of the lesson).
 
 ## Commits (jj)
 

package/templates/FullscreenDiagram.vue

@@ -63,7 +63,7 @@ const cloneDiagram = () => {
 	diagramHTML.value = diagramRef.value.innerHTML;
 };
 
-const toggleExpand = () => {
+const _toggleExpand = () => {
 	if (!isExpanded.value) {
 		cloneDiagram();
 	}
@@ -97,7 +97,7 @@ const toggleExpand = () => {
 	}
 };
 
-const zoomIn = () => {
+const _zoomIn = () => {
 	if (panzoomInstance.value) {
 		const currentZoom = panzoomInstance.value.getTransform().scale;
 		if (currentZoom < 10) {
@@ -106,7 +106,7 @@ const zoomIn = () => {
 	}
 };
 
-const zoomOut = () => {
+const _zoomOut = () => {
 	if (panzoomInstance.value) {
 		const currentZoom = panzoomInstance.value.getTransform().scale;
 		if (currentZoom > 0.05) {

package/templates/filtering-exporter.ts

@@ -14,20 +14,10 @@
  * If OTEL_ENABLED_CATEGORIES is not set, all categories are exported.
  */
 
-import type {
-	ExportResult,
-	ExportResultCode,
-} from "@opentelemetry/core";
+import type { ExportResult, ExportResultCode } from "@opentelemetry/core";
 import type { ReadableSpan, SpanExporter } from "@opentelemetry/sdk-trace-base";
 
-export const ALL_CATEGORIES = [
-	"http",
-	"db",
-	"business",
-	"inference",
-	"state",
-	"system",
-] as const;
+export const ALL_CATEGORIES = ["http", "db", "business", "inference", "state", "system"] as const;
 
 export type OtelCategory = (typeof ALL_CATEGORIES)[number];
 
@@ -49,10 +39,7 @@ export class FilteringExporter implements SpanExporter {
 		this.enabledCategories = getEnabledCategories();
 	}
 
-	export(
-		spans: ReadableSpan[],
-		resultCallback: (result: ExportResult) => void,
-	): void {
+	export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void {
 		const filtered = spans.filter((span) => {
 			const category = span.attributes["otel.category"] as string | undefined;
 			// Spans without a category are always exported

package/templates/instrumentation.ts

@@ -15,15 +15,15 @@
  *   OTEL_ENABLED_CATEGORIES     — comma-separated categories to export (default: all)
  */
 
-import { NodeSDK } from "@opentelemetry/sdk-node";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { NodeSDK } from "@opentelemetry/sdk-node";
 import {
-	ConsoleSpanExporter,
 	BatchSpanProcessor,
+	ConsoleSpanExporter,
 	SimpleSpanProcessor,
 } from "@opentelemetry/sdk-trace-base";
-import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { FilteringExporter } from "./filtering-exporter";
 
@@ -41,8 +41,7 @@ function createSpanProcessor() {
 
 const sdk = new NodeSDK({
 	resource: resourceFromAttributes({
-		[ATTR_SERVICE_NAME]:
-			process.env.OTEL_SERVICE_NAME ?? "unknown-service",
+		[ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME ?? "unknown-service",
 	}),
 	spanProcessors: [createSpanProcessor()],
 	instrumentations: [

package/templates/instrumentation.web.ts

@@ -18,30 +18,34 @@
  *   pnpm add @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions
  */
 
-import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
-import { BatchSpanProcessor, SimpleSpanProcessor, ConsoleSpanExporter } from "@opentelemetry/sdk-trace-base";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { resourceFromAttributes } from "@opentelemetry/resources";
-import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
-import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
 import { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
+import { FetchInstrumentation } from "@opentelemetry/instrumentation-fetch";
 import { UserInteractionInstrumentation } from "@opentelemetry/instrumentation-user-interaction";
-import { registerInstrumentations } from "@opentelemetry/instrumentation";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import {
+	BatchSpanProcessor,
+	ConsoleSpanExporter,
+	SimpleSpanProcessor,
+} from "@opentelemetry/sdk-trace-base";
+import { WebTracerProvider } from "@opentelemetry/sdk-trace-web";
+import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 
 const endpoint =
-	import.meta.env?.VITE_OTEL_EXPORTER_OTLP_ENDPOINT
-	?? process.env.NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT
-	?? "";
+	import.meta.env?.VITE_OTEL_EXPORTER_OTLP_ENDPOINT ??
+	process.env.NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT ??
+	"";
 
 const headers =
-	import.meta.env?.VITE_OTEL_EXPORTER_OTLP_HEADERS
-	?? process.env.NEXT_PUBLIC_OTEL_EXPORTER_OTLP_HEADERS
-	?? "";
+	import.meta.env?.VITE_OTEL_EXPORTER_OTLP_HEADERS ??
+	process.env.NEXT_PUBLIC_OTEL_EXPORTER_OTLP_HEADERS ??
+	"";
 
 const serviceName =
-	import.meta.env?.VITE_OTEL_SERVICE_NAME
-	?? process.env.NEXT_PUBLIC_OTEL_SERVICE_NAME
-	?? "unknown-service";
+	import.meta.env?.VITE_OTEL_SERVICE_NAME ??
+	process.env.NEXT_PUBLIC_OTEL_SERVICE_NAME ??
+	"unknown-service";
 
 // Parse headers string: "Key1=Value1,Key2=Value2" → { Key1: "Value1", Key2: "Value2" }
 function parseHeaders(headerStr: string): Record<string, string> {

package/templates/logger.ts

@@ -17,8 +17,8 @@
  *   DEBUG — development details, disable in production
  */
 
-import pino from "pino";
 import type { TransportTargetOptions } from "pino";
+import pino from "pino";
 
 const targets: TransportTargetOptions[] = [
 	// Always log to stdout