@infinitedusky/indusk-mcp 1.5.14 → 1.6.0

package/dist/bin/commands/extensions.js

@@ -597,9 +597,16 @@ function printMcpInstructions(name, manifest) {
                 ];
                 const cmd = `claude ${args.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}`;
                 console.info(`\n  ${name}: adding MCP server with credentials from .env...`);
+                // Remove existing entry first so we always write fresh credentials
+                try {
+                    execSync(`claude mcp remove -s project ${name}`, { cwd: process.cwd(), timeout: 10000, stdio: ["ignore", "pipe", "pipe"] });
+                }
+                catch {
+                    // Ignore — may not exist
+                }
                 try {
                     execSync(cmd, { cwd: process.cwd(), timeout: 15000, stdio: ["ignore", "pipe", "pipe"] });
-                    console.info(`  ${name}: MCP server added (restart Claude Code to load)`);
+                    console.info(`  ${name}: MCP server configured (restart Claude Code to load)`);
                     return;
                 }
                 catch (e) {
@@ -607,6 +614,7 @@ function printMcpInstructions(name, manifest) {
                     const stderr = err.stderr ? String(err.stderr).trim() : "";
                     console.info(`  ${name}: auto-add failed. ${stderr || err.message || ""}`);
                     console.info(`  command was: ${cmd}`);
+                    return;
                 }
             }
         }

package/dist/bin/commands/init.js

@@ -190,6 +190,9 @@ export async function init(projectRoot, options = {}) {
             existsSync(join(projectRoot, "next.config.mjs"));
         const isPython = existsSync(join(projectRoot, "requirements.txt")) ||
             existsSync(join(projectRoot, "pyproject.toml"));
+        const isReactSPA = !isNextJs &&
+            (existsSync(join(projectRoot, "vite.config.ts")) ||
+                existsSync(join(projectRoot, "vite.config.js")));
         if (isPython) {
             const pyTemplate = "instrumentation.py";
             const targetFile = join(projectRoot, pyTemplate);
@@ -203,9 +206,64 @@ export async function init(projectRoot, options = {}) {
                 console.info("  run: opentelemetry-instrument python your_app.py");
             }
         }
+        else if (isNextJs) {
+            // Next.js — use @vercel/otel
+            const instrTarget = join(projectRoot, "instrumentation.ts");
+            if (existsSync(instrTarget) && !force) {
+                console.info("  skip: instrumentation.ts (already exists)");
+            }
+            else {
+                cpSync(join(packageRoot, "templates/instrumentation.next.ts"), instrTarget);
+                const content = readFileSync(instrTarget, "utf-8");
+                writeFileSync(instrTarget, content.replace('"unknown-service"', `"${projectName}"`));
+                console.info("  create: instrumentation.ts (Next.js — @vercel/otel)");
+            }
+            // Logger
+            const loggerTarget = join(projectRoot, "src/logger.ts");
+            if (existsSync(loggerTarget) && !force) {
+                console.info("  skip: src/logger.ts (already exists)");
+            }
+            else {
+                const loggerDir = join(projectRoot, "src");
+                mkdirSync(loggerDir, { recursive: true });
+                cpSync(join(packageRoot, "templates/logger.ts"), loggerTarget);
+                console.info("  create: src/logger.ts");
+            }
+            // Client-side browser instrumentation
+            const webInstrTarget = join(projectRoot, "src/instrumentation.web.ts");
+            if (existsSync(webInstrTarget) && !force) {
+                console.info("  skip: src/instrumentation.web.ts (already exists)");
+            }
+            else {
+                const srcDir = join(projectRoot, "src");
+                mkdirSync(srcDir, { recursive: true });
+                cpSync(join(packageRoot, "templates/instrumentation.web.ts"), webInstrTarget);
+                const content = readFileSync(webInstrTarget, "utf-8");
+                writeFileSync(webInstrTarget, content.replace('"unknown-service"', `"${projectName}"`));
+                console.info("  create: src/instrumentation.web.ts (browser — OTel Web SDK)");
+            }
+            console.info("  install: pnpm add @vercel/otel pino pino-opentelemetry-transport @opentelemetry/sdk-trace-web @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/instrumentation @opentelemetry/instrumentation-fetch @opentelemetry/instrumentation-document-load @opentelemetry/instrumentation-user-interaction");
+            console.info("  wire (server): Next.js loads instrumentation.ts automatically");
+            console.info("  wire (client): import './instrumentation.web' in your root client component or layout");
+        }
+        else if (isReactSPA) {
+            // React SPA (Vite) — browser instrumentation via Dash0 Web SDK
+            const srcDir = existsSync(join(projectRoot, "src")) ? join(projectRoot, "src") : projectRoot;
+            const instrTarget = join(srcDir, "instrumentation.ts");
+            if (existsSync(instrTarget) && !force) {
+                console.info("  skip: instrumentation.ts (already exists)");
+            }
+            else {
+                cpSync(join(packageRoot, "templates/instrumentation.web.ts"), instrTarget);
+                const content = readFileSync(instrTarget, "utf-8");
+                writeFileSync(instrTarget, content.replace('"unknown-service"', `"${projectName}"`));
+                console.info("  create: src/instrumentation.ts (React SPA — @dash0/sdk-web)");
+            }
+            console.info("  install: pnpm add @opentelemetry/sdk-trace-web @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/instrumentation @opentelemetry/instrumentation-fetch @opentelemetry/instrumentation-document-load @opentelemetry/instrumentation-user-interaction");
+            console.info("  wire: import './instrumentation' at the top of your main.tsx or App.tsx");
+        }
         else {
-            // Node.js or Next.js — copy TypeScript templates
-            const targetDir = isNextJs ? projectRoot : join(projectRoot, "src");
+            // Node.js — full SDK with auto-instrumentation
             const srcDir = existsSync(join(projectRoot, "src")) ? join(projectRoot, "src") : projectRoot;
             for (const template of otelTemplates) {
                 const targetFile = join(srcDir, template);
@@ -222,7 +280,6 @@ export async function init(projectRoot, options = {}) {
                 const content = readFileSync(instrPath, "utf-8");
                 writeFileSync(instrPath, content.replace('"unknown-service"', `"${projectName}"`));
             }
-            // Print instructions
             const packages = [
                 "@opentelemetry/sdk-node",
                 "@opentelemetry/auto-instrumentations-node",
@@ -235,12 +292,7 @@ export async function init(projectRoot, options = {}) {
                 "pino-opentelemetry-transport",
             ];
             console.info(`  install: pnpm add ${packages.join(" ")}`);
-            if (isNextJs) {
-                console.info("  wire: Next.js instrumentation hook (instrumentation.ts in app root)");
-            }
-            else {
-                console.info("  wire: node -r ./src/instrumentation.ts src/index.ts");
-            }
+            console.info("  wire: node --import ./src/instrumentation.ts src/index.ts");
         }
     } // end isInduskMcp else
     // 8. Install gate enforcement hooks

package/extensions/otel/skill.md

@@ -1,13 +1,24 @@
+---
+name: otel
+description: OpenTelemetry instrumentation patterns — span naming, categories, structured logging, error propagation, sensitive data, and validation
+---
+
 # OpenTelemetry
 
-Every service is instrumented from day one. `init` creates the instrumentation files. This skill teaches you how to use them.
+Every service is instrumented from day one. `init` creates the instrumentation files. This skill teaches you how to produce high-quality telemetry.
 
 ## What's Already Set Up
 
-After `init`, your project has:
-- `instrumentation.ts` — auto-instruments HTTP, database, and framework calls
-- `filtering-exporter.ts` — controls which span categories get exported
-- `logger.ts` — Pino structured logger with stdout + OTLP dual output
+After `init`, your project has instrumentation files for your runtime. See the OTel reference docs in the indusk-docs site for the full list per runtime.
+
+## Core Principle: Signal Density Over Volume
+
+Every telemetry item should serve one of three purposes:
+- **Detect** — help identify that something is wrong
+- **Localize** — help pinpoint where the problem is
+- **Explain** — help understand why it happened
+
+If it doesn't serve one of these purposes, don't emit it.
 
 ## When to Add Manual Spans
 
@@ -22,20 +33,61 @@ If it's a meaningful action that you'd want to see in a trace, add a span.
 
 ## Span Naming
 
-Use `{domain}.{entity}.{action}`:
+Span names MUST be low-cardinality. The number of unique span names should be bounded and small.
 
-```typescript
-const tracer = trace.getTracer('my-service');
+### General pattern: `{domain}.{entity}.{action}`
 
-// Good
+```typescript
+// Good — low cardinality
 tracer.startSpan('poker.hand.deal');
 tracer.startSpan('auth.session.create');
 tracer.startSpan('settlement.receipt.sign');
 
-// Bad
-tracer.startSpan('processRequest');
-tracer.startSpan('handle');
-tracer.startSpan('doThing');
+// Bad — high cardinality (contains variable data)
+tracer.startSpan(`process_payment_for_${userId}`);  // user ID in name!
+tracer.startSpan(`GET /api/users/${id}`);            // path param in name!
+```
+
+Variable data (user IDs, order numbers, room codes) goes in **attributes**, never in the span name.
+
+### Per-signal naming
+
+| Signal | Format | Example |
+|--------|--------|---------|
+| HTTP server | `{method} {route}` | `GET /api/users/:id` |
+| HTTP client | `{method} {template}` | `POST /checkout` |
+| Database | `{operation} {collection}` | `SELECT orders` |
+| Messaging | `{operation} {destination}` | `publish shop.orders` |
+| Business logic | `{domain}.{entity}.{action}` | `poker.hand.deal` |
+
+## Span Kind
+
+Each span has exactly one kind. Choose based on the communication pattern:
+
+| Kind | Use When | Examples |
+|------|----------|---------|
+| `SERVER` | Handling an inbound sync request | HTTP handler, gRPC handler |
+| `CLIENT` | Making an outbound sync request | HTTP call, database query, outbound RPC |
+| `PRODUCER` | Initiating an async operation | Publishing to a queue |
+| `CONSUMER` | Processing an async operation | Processing a queued message |
+| `INTERNAL` | Internal operation, no remote peer | In-memory computation, business logic |
+
+Common mistakes:
+- Using `INTERNAL` for everything — database calls are `CLIENT`, HTTP handlers are `SERVER`
+- Using `CLIENT` for message publishing — that's `PRODUCER` (async, no response expected)
+
+## Span Status
+
+Only set error status explicitly. Success is the default.
+
+```typescript
+import { SpanStatusCode } from '@opentelemetry/api';
+
+// Only set on error
+span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+
+// Don't set OK explicitly — it's the default
+// span.setStatus({ code: SpanStatusCode.OK }); // unnecessary
 ```
 
 ## Custom Attributes
@@ -43,38 +95,43 @@ tracer.startSpan('doThing');
 Always add domain-specific data to spans:
 
 ```typescript
-const span = tracer.startSpan('poker.hand.deal');
-span.setAttribute('otel.category', 'business');
-span.setAttribute('room.code', roomCode);
-span.setAttribute('hand.number', handNumber);
-span.setAttribute('player.count', players.length);
-// ... do work ...
-span.end();
+const span = tracer.startSpan('poker.hand.deal', {
+  attributes: {
+    'otel.category': 'business',
+    'room.code': roomCode,
+    'hand.number': handNumber,
+    'player.count': players.length,
+  },
+});
 ```
 
+### Attribute hygiene
+
+- Use snake_case with dots for namespacing: `room.code`, `player.count`
+- Keep values low-cardinality where possible
+- Never put variable-length user input in attributes without truncation
+
 ## Categories
 
-Every manual span should get an `otel.category` attribute. This controls whether it gets exported:
+Every manual span should get an `otel.category` attribute:
 
 | Category | What it covers | Examples |
 |----------|---------------|----------|
-| `http` | HTTP server/client requests | Auto-instrumented |
+| `http` | HTTP requests | Auto-instrumented |
 | `db` | Database queries | Auto-instrumented |
 | `business` | Domain events | hand dealt, user registered, payment processed |
 | `inference` | LLM/AI calls | Gemini generate, embedding create |
-| `state` | State transitions | game started, order status changed |
-| `system` | Infrastructure | health checks, cron jobs, queue processing |
+| `state` | State transitions | game started, order shipped |
+| `system` | Infrastructure | health checks, cron, queue processing |
 
-Control which categories are exported via `OTEL_ENABLED_CATEGORIES`:
+Control export via `OTEL_ENABLED_CATEGORIES`:
 
 ```bash
-# Export only HTTP and business spans
-OTEL_ENABLED_CATEGORIES=http,business node -r ./instrumentation.ts src/index.ts
-
-# Export everything (default)
-node -r ./instrumentation.ts src/index.ts
+OTEL_ENABLED_CATEGORIES=http,business  # only these categories exported
 ```
 
+Unset = all categories exported. Spans without a category are always exported.
+
 ## Structured Logging with Pino
 
 Use the project logger, not `console.log`:
@@ -84,70 +141,155 @@ import { logger } from './logger';
 
 // Good — structured, with context
 logger.info({ roomCode, players: players.length }, 'hand started');
-logger.error({ err, traceId: span.spanContext().traceId }, 'settlement failed');
-logger.warn({ queueDepth: 150, threshold: 100 }, 'queue depth approaching limit');
+logger.error({ err, orderId }, 'payment failed');
 
 // Bad — unstructured string
 console.log('Hand started for room ' + roomCode);
-console.log('Error: ' + err.message);
 ```
 
-### Log Levels
+### Log levels
 
 | Level | Meaning | When to use |
 |-------|---------|------------|
-| `error` | Something is broken | Unhandled errors, failed operations that should succeed |
-| `warn` | Degraded but functional | Approaching limits, fallback behavior triggered |
-| `info` | Business events | State transitions, user actions, completed operations |
-| `debug` | Development details | Variable values, flow tracing — disable in production |
+| `error` | Something is broken | Unhandled errors, failed operations |
+| `warn` | Degraded but functional | Approaching limits, fallback behavior |
+| `info` | Business events | State transitions, completed operations |
+| `debug` | Development details | Disable in production |
+
+### Structured logging safeguards
+
+Never spread entire objects — explicitly pick safe fields:
+
+```typescript
+// BAD: spreads entire request body — may contain passwords, tokens, PII
+logger.info({ ...req.body }, 'user signup');
+
+// GOOD: explicitly select safe fields
+logger.info({ userId: req.body.userId, plan: req.body.plan }, 'user signup');
+```
+
+## Trace Correlation in Logs
+
+Every log inside an active span should carry trace context:
+
+```typescript
+import { trace, context } from '@opentelemetry/api';
+
+function getTraceContext() {
+  const span = trace.getSpan(context.active());
+  if (!span) return {};
+  const ctx = span.spanContext();
+  return { traceId: ctx.traceId, spanId: ctx.spanId };
+}
+
+logger.info({ ...getTraceContext(), orderId }, 'order placed');
+```
+
+Wrap this in a helper so every log call includes trace context automatically. Without it, logs are isolated events that can't be connected to the request that produced them.
 
 ## Error Propagation
 
-Errors must always include trace context:
+Errors must always include trace context. Never swallow silently:
 
 ```typescript
 try {
   await processSettlement(hand);
 } catch (err) {
+  // 1. Record on span
   span.recordException(err);
   span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
-  logger.error({ err, traceId: span.spanContext().traceId }, 'settlement failed');
-  throw err; // re-throw with context preserved
+  
+  // 2. Log with correlation
+  logger.error({ err, ...getTraceContext() }, 'settlement failed');
+  
+  // 3. Re-throw — don't swallow
+  throw err;
 }
 ```
 
-Never swallow errors silently. Every catch block should either:
-1. Re-throw with context
+Every catch block should either:
+1. Re-throw with context preserved
 2. Log with trace correlation and handle completely
 
+## Sensitive Data
+
+Never attach these to spans, logs, or metrics:
+
+| Category | Examples |
+|----------|----------|
+| Auth credentials | Passwords, API keys, bearer tokens, session cookies |
+| Financial instruments | Credit card numbers, bank accounts, CVVs |
+| Government IDs | SSN, passport numbers, tax IDs |
+| Full auth headers | `Authorization`, `Cookie` header values |
+
+For URLs, strip query parameters that carry tokens or user input:
+
+```typescript
+// BAD
+span.setAttribute('http.url', 'https://example.com/callback?token=eyJhbG...');
+
+// GOOD
+span.setAttribute('http.url', sanitizeUrl(req.url));
+```
+
+For database queries, never include literal parameter values — use parameterized queries.
+
+## Validation Checklist
+
+After instrumenting a service, verify:
+
+1. **Service appears in backend** — search for your `OTEL_SERVICE_NAME` in Dash0
+2. **Resource attributes present** — `service.name`, `service.version`, `deployment.environment`
+3. **Expected span names appear** — list your endpoints and business operations, verify each produces a span
+4. **Attributes are populated** — check that domain attributes (`room.code`, `player.count`) are present
+5. **Errors are tracked** — trigger an error, verify it appears with exception details and trace context
+6. **Logs correlate with traces** — verify `traceId` and `spanId` appear in log records
+
 ## Framework-Specific Notes
 
+### Node.js (ESM)
+- Load instrumentation with `--import`: `node --import ./src/instrumentation.ts src/index.ts`
+- ESM requires `--import`, not `--require`
+
 ### Next.js
-The `instrumentation.ts` file in the app root is loaded via the Next.js instrumentation hook (13.4+). No `-r` flag needed.
+- Server: `instrumentation.ts` at app root, loaded automatically by Next.js (13.4+)
+- Client: `src/instrumentation.web.ts`, import in your root client component
+- Both server and client need separate instrumentation — they run in different environments
+
+### React SPA (Vite)
+- `import './instrumentation'` at the top of `main.tsx`
+- Browser env vars use `VITE_` prefix: `VITE_OTEL_EXPORTER_OTLP_ENDPOINT`
 
 ### Python
-Use the `opentelemetry-instrument` CLI wrapper:
-```bash
-opentelemetry-instrument python your_app.py
-```
-Or import the instrumentation module before your app code.
+- Use `opentelemetry-instrument` CLI: `opentelemetry-instrument python your_app.py`
+- Or import `instrumentation.py` before app code
 
 ## Environment Variables
 
+### Server
+
 | Variable | Purpose | Default |
 |----------|---------|---------|
-| `OTEL_SERVICE_NAME` | Service name in traces | Project name (set by init) |
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Backend URL | Not set (uses console exporter) |
-| `OTEL_EXPORTER_OTLP_HEADERS` | Auth headers for backend | Not set |
-| `OTEL_ENABLED_CATEGORIES` | Comma-separated active categories | All enabled |
+| `OTEL_SERVICE_NAME` | Service name | Set by init |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Backend URL | Not set (console) |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Auth headers | Not set |
+| `OTEL_ENABLED_CATEGORIES` | Active categories | All |
 | `LOG_LEVEL` | Pino log level | `info` |
 
-When no `OTEL_EXPORTER_OTLP_ENDPOINT` is set, traces go to the console exporter (stdout). Enable a backend (like Dash0) to send traces remotely.
+### Browser
+
+| Variable | Purpose |
+|----------|---------|
+| `VITE_OTEL_EXPORTER_OTLP_ENDPOINT` / `NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT` | Backend URL |
+| `VITE_OTEL_EXPORTER_OTLP_HEADERS` / `NEXT_PUBLIC_OTEL_EXPORTER_OTLP_HEADERS` | Auth headers |
 
-## Verification
+## During `/work`
 
-During `/work`, check:
-- Are new endpoints/business logic instrumented?
-- Do manual spans have meaningful names and category attributes?
-- Are errors recorded with trace context?
-- Is structured logging used (not console.log)?
+When implementing or reviewing code, check:
+- Are new endpoints and business logic instrumented with manual spans?
+- Do spans have meaningful names (low-cardinality, `{domain}.{entity}.{action}`)?
+- Do spans have the right kind (SERVER, CLIENT, INTERNAL)?
+- Do spans have `otel.category` and domain-specific attributes?
+- Are errors recorded with `recordException` + `setStatus(ERROR)` + trace-correlated log?
+- Is structured logging used (not `console.log`)?
+- Is sensitive data excluded from attributes and logs?

package/hooks/check-gates.js

@@ -117,8 +117,8 @@ function detectWorkflow(content) {
 
 // Which gate types are required per workflow
 const WORKFLOW_GATES = {
-	feature: ["verification", "context", "document"],
-	refactor: ["verification", "context", "document"],
+	feature: ["verification", "otel", "context", "document"],
+	refactor: ["verification", "otel", "context", "document"],
 	bugfix: ["verification", "document"],
 	spike: [],
 };
@@ -147,7 +147,7 @@ function parsePhases(content) {
 			continue;
 		}
 
-		const gateMatch = line.match(/^####\s+Phase\s+\d+\s+(Verification|Context|Document)\b/);
+		const gateMatch = line.match(/^####\s+Phase\s+\d+\s+(Verification|OTel|Context|Document)\b/);
 		if (gateMatch) {
 			currentGateType = gateMatch[1].toLowerCase();
 			continue;

package/hooks/validate-impl-structure.js

@@ -2,7 +2,7 @@
 /**
  * PreToolUse hook: validates that impl phases have all four gate sections.
  *
- * Every phase must have: implementation items, Verification, Context, Document.
+ * Every phase must have: implementation items, Verification, OTel, Context, Document.
  * Sections can opt out with (none needed), (not applicable), or skip-reason: {why}.
  *
  * Exit 0 = allow the edit
@@ -102,10 +102,10 @@ const workflow = workflowMatch ? workflowMatch[1] : "feature";
 
 // Different workflows have different requirements
 const requirements = {
-	feature: { verification: true, context: true, document: true },
-	refactor: { verification: true, context: true, document: true },
-	bugfix: { verification: true, context: false, document: true },
-	spike: { verification: false, context: false, document: false },
+	feature: { verification: true, otel: true, context: true, document: true },
+	refactor: { verification: true, otel: true, context: true, document: true },
+	bugfix: { verification: true, otel: false, context: false, document: true },
+	spike: { verification: false, otel: false, context: false, document: false },
 }[workflow];
 const lines = body.split("\n");
 
@@ -122,9 +122,11 @@ for (const line of lines) {
 			name: phaseMatch[2].trim(),
 			hasImplementation: false,
 			hasVerification: false,
+			hasOtel: false,
 			hasContext: false,
 			hasDocument: false,
 			verificationIsOptOut: false,
+			otelIsOptOut: false,
 			contextIsOptOut: false,
 			documentIsOptOut: false,
 		};
@@ -142,6 +144,13 @@ for (const line of lines) {
 		continue;
 	}
 
+	const otelMatch = line.match(/^####\s+Phase\s+\d+\s+OTel\b/);
+	if (otelMatch) {
+		currentPhase.hasOtel = true;
+		currentSection = "otel";
+		continue;
+	}
+
 	const ctxMatch = line.match(/^####\s+Phase\s+\d+\s+Context\b/);
 	if (ctxMatch) {
 		currentPhase.hasContext = true;
@@ -168,6 +177,7 @@ for (const line of lines) {
 		line.includes("skip-reason:");
 	if (currentPhase && isOptOutLine) {
 		if (currentSection === "verification") currentPhase.verificationIsOptOut = true;
+		if (currentSection === "otel") currentPhase.otelIsOptOut = true;
 		if (currentSection === "context") currentPhase.contextIsOptOut = true;
 		if (currentSection === "document") currentPhase.documentIsOptOut = true;
 	}
@@ -186,6 +196,7 @@ for (const phase of phases) {
 
 	const missing = [];
 	if (requirements.verification && !phase.hasVerification) missing.push("Verification");
+	if (requirements.otel && !phase.hasOtel) missing.push("OTel");
 	if (requirements.context && !phase.hasContext) missing.push("Context");
 	if (requirements.document && !phase.hasDocument) missing.push("Document");
 
@@ -200,6 +211,8 @@ for (const phase of phases) {
 		const optOuts = [];
 		if (requirements.verification && phase.hasVerification && phase.verificationIsOptOut)
 			optOuts.push("Verification");
+		if (requirements.otel && phase.hasOtel && phase.otelIsOptOut)
+			optOuts.push("OTel");
 		if (requirements.context && phase.hasContext && phase.contextIsOptOut) optOuts.push("Context");
 		if (requirements.document && phase.hasDocument && phase.documentIsOptOut)
 			optOuts.push("Document");

package/package.json

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

package/skills/plan.md

@@ -256,8 +256,11 @@ For multi-phase impls, include a boundary map showing what each phase produces a
   function withdrawFor(wallet: address, player: address, amount: uint256, historyHash: bytes32)
   ```
 
+#### Phase 1 OTel
+- [ ] {Instrumentation check — are new code paths observable? See the OTel skill for patterns. Example items: "New endpoints have manual spans with `otel.category` and domain attributes", "Errors recorded with `recordException` + `setStatus(ERROR)` + trace-correlated log". Ask: "did this phase add endpoints, business logic, state transitions, or error paths?" If not, this section can be opted out per gate policy.}
+
 #### Phase 1 Verification
-- [ ] {Verification step — prove this phase works. Must be a specific runnable command with expected output, not "verify it works." See the verify skill for guidance on what checks a phase needs based on what changed.}
+- [ ] {Verification step — prove this phase works. Must be a specific runnable command with expected output, not "verify it works." See the verify skill for guidance on what checks a phase needs based on what changed. Can include trace verification if OTel was added.}
 
 #### Phase 1 Context
 - [ ] {Concrete CLAUDE.md edit this phase produces — e.g., "Add to Architecture: ...", "Add to Conventions: ...", "Update Current State: ...". Ask: "what does this phase change about how the project works?" If nothing, omit this section.}

package/skills/toolbelt.md

@@ -48,6 +48,77 @@ When a new session begins:
 3. Call `list_plans` — understand what plans exist, their stages, and what's in progress.
 4. Call `get_context` — read the project's CLAUDE.md to understand architecture, conventions, and current state.
 
+## Creating a New App
+
+When starting a new service or app in the monorepo, follow this sequence:
+
+### 1. Create the app
+
+| Runtime | Command |
+|---------|---------|
+| **Next.js** | `npx create-next-app apps/my-app` |
+| **React SPA** (Vite) | `pnpm create vite apps/my-app --template react-ts` |
+| **Node.js** (Express/Fastify) | Create `apps/my-app/` with `package.json`, `src/index.ts` |
+| **Python** | Create `apps/my-app/` with `pyproject.toml` or `requirements.txt` |
+
+### 2. Initialize indusk-mcp
+
+```bash
+cd apps/my-app
+npx @infinitedusky/indusk-mcp init
+```
+
+This detects the runtime and scaffolds:
+- Skills, hooks, lessons, CLAUDE.md
+- **Next.js**: `instrumentation.ts` (app root) using `@vercel/otel`, `src/logger.ts` using Pino
+- **Node.js**: `src/instrumentation.ts` (full OTel SDK + FilteringExporter), `src/filtering-exporter.ts`, `src/logger.ts`
+- **Python**: `instrumentation.py` (OTel SDK with auto-instrumentation)
+- Biome config, VS Code settings, `.cgcignore`
+
+### 3. Install the printed packages
+
+`init` prints the install command — run it:
+- **Next.js**: `pnpm add @vercel/otel pino pino-opentelemetry-transport`
+- **Node.js**: `pnpm add @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node ...` (full list printed by init)
+- **Python**: `pip install opentelemetry-distro opentelemetry-instrumentation opentelemetry-exporter-otlp`
+
+### 4. Wire instrumentation into the entry point
+
+- **Next.js**: automatic — Next.js loads `instrumentation.ts` from the app root
+- **Node.js**: `node --import ./src/instrumentation.ts src/index.ts`
+- **Python**: `opentelemetry-instrument python your_app.py`
+
+### 5. Create a composable.env contract (if using composable.env)
+
+Create `env/contracts/my-app.contract.json`:
+```json
+{
+  "name": "my-app",
+  "location": "apps/my-app",
+  "vars": {
+    "OTEL_SERVICE_NAME": "my-app",
+    "OTEL_EXPORTER_OTLP_ENDPOINT": "${dash0.HTTP_ENDPOINT}",
+    "OTEL_EXPORTER_OTLP_HEADERS": "${dash0.OTLP_HEADERS}"
+  }
+}
+```
+
+Then `pnpm ce env:build` generates the `.env` files.
+
+### 6. Enable extensions
+
+```bash
+npx @infinitedusky/indusk-mcp extensions enable dash0
+```
+
+If `.indusk/extensions/dash0/.env` has credentials, this auto-configures the MCP server. Otherwise it tells you what to create.
+
+### 7. Verify
+
+- Start the app, hit an endpoint
+- Check Dash0 for traces: `mcp__dash0__getSpans` with `service.name = my-app`
+- Check health: `mcp__indusk__check_health` should show OTel extension healthy
+
 ## Before Modifying Code
 
 Before touching any file:

package/skills/work.md

@@ -52,14 +52,15 @@ Implementation plans live in `planning/{plan-name}/impl.md` as checklists. Your
    - Add it as a new item in the appropriate phase
    - Then do it and check it off
 
-10. **Per-phase completion order.** Each phase has up to four types of items. Complete them in this order:
+10. **Per-phase completion order.** Each phase has up to five types of items. Complete them in this order:
 
    **Implementation items** → build the thing
-   **Verification items** → prove it works (tests, type checks, commands)
+   **OTel items** → instrument it (spans, categories, error recording — see OTel skill)
+   **Verification items** → prove it works (tests, type checks, commands — can include trace verification)
    **Context items** → capture what changed (concrete CLAUDE.md edits)
    **Document items** → write or update docs pages (see document skill)
 
-   A phase is not complete until all four are done. **Enforced by hooks:** if you try to check off a Phase N+1 implementation item while Phase N has unchecked gates, the edit will be blocked with a message listing what's missing. Complete the gates first.
+   A phase is not complete until all five are done. **Enforced by hooks:** if you try to check off a Phase N+1 implementation item while Phase N has unchecked gates, the edit will be blocked with a message listing what's missing. Complete the gates first.
 
 ## Gate Override Policy
 
@@ -171,7 +172,7 @@ Then **stop and wait** for the user to say "continue" before moving to the next
 
 ### At gate transitions:
 
-When moving between gates (implement → verify → context → document → next phase), explain the transition: what gate you're entering, why it exists, and what it catches. Example: "Code is written. Now we verify — type check, lint, tests. This catches errors before they compound into the next phase."
+When moving between gates (implement → otel → verify → context → document → next phase), explain the transition: what gate you're entering, why it exists, and what it catches. Example: "Code is written. Now OTel — instrument the new code paths. Then verify — type check, lint, tests, trace verification. Then context and docs."
 
 ### Between checklist items:
 

package/templates/instrumentation.next.ts

@@ -0,0 +1,21 @@
+/**
+ * OpenTelemetry Instrumentation for Next.js
+ *
+ * This file is automatically loaded by Next.js via the instrumentation hook (13.4+).
+ * Place it in the app root (next to next.config.ts).
+ *
+ * Configuration via environment variables:
+ *   OTEL_SERVICE_NAME            — service name (defaults to "unknown-service")
+ *   OTEL_EXPORTER_OTLP_ENDPOINT — OTLP backend URL
+ *   OTEL_EXPORTER_OTLP_HEADERS  — auth headers for the backend
+ *
+ * Install: pnpm add @vercel/otel
+ */
+
+import { registerOTel } from "@vercel/otel";
+
+export function register() {
+	registerOTel({
+		serviceName: process.env.OTEL_SERVICE_NAME ?? "unknown-service",
+	});
+}

package/templates/instrumentation.web.ts

@@ -0,0 +1,83 @@
+/**
+ * OpenTelemetry Browser Instrumentation
+ *
+ * Captures page loads, HTTP requests (fetch/XHR), and user interactions
+ * from the browser and sends them to any OTLP-compatible backend.
+ *
+ * Import this as early as possible in your app (main.tsx or App.tsx):
+ *   import './instrumentation';
+ *
+ * Configuration via environment variables (use VITE_ or NEXT_PUBLIC_ prefix):
+ *   VITE_OTEL_SERVICE_NAME            — service name
+ *   VITE_OTEL_EXPORTER_OTLP_ENDPOINT — OTLP backend URL
+ *   VITE_OTEL_EXPORTER_OTLP_HEADERS  — auth headers (e.g., "Authorization=Bearer xxx")
+ *
+ * Install:
+ *   pnpm add @opentelemetry/sdk-trace-web @opentelemetry/instrumentation-fetch
+ *   pnpm add @opentelemetry/instrumentation-document-load @opentelemetry/instrumentation-user-interaction
+ *   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 { DocumentLoadInstrumentation } from "@opentelemetry/instrumentation-document-load";
+import { UserInteractionInstrumentation } from "@opentelemetry/instrumentation-user-interaction";
+import { registerInstrumentations } from "@opentelemetry/instrumentation";
+
+const 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
+	?? "";
+
+const serviceName =
+	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> {
+	if (!headerStr) return {};
+	const result: Record<string, string> = {};
+	for (const pair of headerStr.split(",")) {
+		const eqIdx = pair.indexOf("=");
+		if (eqIdx > 0) {
+			result[pair.slice(0, eqIdx).trim()] = pair.slice(eqIdx + 1).trim();
+		}
+	}
+	return result;
+}
+
+const provider = new WebTracerProvider({
+	resource: resourceFromAttributes({
+		[ATTR_SERVICE_NAME]: serviceName,
+	}),
+});
+
+if (endpoint) {
+	const exporter = new OTLPTraceExporter({
+		url: `${endpoint}/v1/traces`,
+		headers: parseHeaders(headers),
+	});
+	provider.addSpanProcessor(new BatchSpanProcessor(exporter));
+} else {
+	provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
+}
+
+provider.register();
+
+registerInstrumentations({
+	instrumentations: [
+		new FetchInstrumentation(),
+		new DocumentLoadInstrumentation(),
+		new UserInteractionInstrumentation(),
+	],
+});