@askthew/mcp-plugin 0.4.0 → 0.4.3

package/dist/index.js

@@ -3,10 +3,20 @@ import { z } from "zod";
 import { resolvePluginScope } from "./scope.js";
 import { resolveMcpMode } from "./lib/free-tier-policy.js";
 import { LocalStore } from "./lib/local-store.js";
-import { analyzeLocalPatterns } from "./lib/tip-engine.js";
 import { buildTelemetryPayload, flushTelemetryOutbox } from "./lib/telemetry.js";
+import { ensureLocalIdentity } from "./lib/local-identity.js";
+import { buildLocalTimeline, buildTimelineInsights as buildLocalTimelineInsights, renderTimelineMarkdown as renderLocalTimelineMarkdown } from "./lib/timeline-insights.js";
 import { paidDescription, paidFeatureNudge, toolJson } from "./lib/upgrade-nudge.js";
+import { configPath, readJsonFile } from "./lib/paths.js";
 const evidenceRoleSchema = z.enum(["user", "assistant", "system"]);
+const evidenceEntrySchema = z.object({
+    role: evidenceRoleSchema,
+    excerpt: z.string().min(1).max(2000),
+    kind: z.enum(["excerpt", "diff", "prompt_diff"]).optional(),
+    diff: z.string().max(12000).optional(),
+    before: z.string().max(6000).optional(),
+    after: z.string().max(6000).optional(),
+});
 const sessionSignalKindSchema = z.enum([
     "setup_complete",
     "session_checkpoint",
@@ -21,10 +31,7 @@ export const codingSessionSignalSchema = z.object({
     kind: sessionSignalKindSchema,
     summary: z.string().min(1).max(2000),
     evidence: z
-        .array(z.object({
-        role: evidenceRoleSchema,
-        excerpt: z.string().min(1).max(500),
-    }))
+        .array(evidenceEntrySchema)
         .default([]),
     filesTouched: z.array(z.string().min(1).max(500)).default([]),
     commandsRun: z.array(z.string().min(1).max(500)).default([]),
@@ -53,7 +60,9 @@ const REDACTION_PATTERNS = [
     { name: "twilio_key", pattern: /\bSK[0-9a-fA-F]{32}\b/g },
     { name: "slack_token", pattern: /\bxox[baprs]-[0-9A-Za-z\-]{10,}\b/g },
     { name: "slack_webhook", pattern: /https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+/g },
-    { name: "openai_key", pattern: /\bsk-[A-Za-z0-9]{20,}\b/g },
+    { name: "openai_env_assignment", pattern: /\bOPENAI_API_KEY\s*[=:]\s*["']?sk-[A-Za-z0-9_-]{20,}["']?/g },
+    { name: "openai_key", pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/g },
+    { name: "bearer_token", pattern: /\bBearer\s+[A-Za-z0-9._-]+\b/g },
     { name: "anthropic_key", pattern: /\bsk-ant-[A-Za-z0-9\-_]{32,}\b/g },
     { name: "github_pat_classic", pattern: /\bghp_[A-Za-z0-9]{36}\b/g },
     { name: "github_pat_fine", pattern: /\bgithub_pat_[A-Za-z0-9_]{82}\b/g },
@@ -135,6 +144,12 @@ const SENSITIVE_PATH_SEGMENTS = new Set([
 ]);
 const ENTROPY_THRESHOLD = 4.5;
 const ENTROPY_TOKEN_PATTERN = /[A-Za-z0-9+/=_\-]{20,}/g;
+export function loadAskTheWConfig(env = process.env) {
+    return readJsonFile(configPath(env)) ?? {};
+}
+function isRedactionEnabled() {
+    return loadAskTheWConfig().redaction?.enabled !== false;
+}
 function sanitizeUrl(raw) {
     try {
         const url = new URL(raw);
@@ -235,6 +250,9 @@ function redactMetadata(value, key) {
 }
 export function redactProvenanceSignal(input) {
     const parsed = provenanceSignalSchema.parse(input);
+    if (!isRedactionEnabled()) {
+        return parsed;
+    }
     return {
         ...parsed,
         decision: redactRawSignalText(parsed.decision),
@@ -252,12 +270,18 @@ export function redactProvenanceSignal(input) {
 }
 export function redactCodingSessionSignal(input) {
     const parsed = codingSessionSignalSchema.parse(input);
+    if (!isRedactionEnabled()) {
+        return parsed;
+    }
     return {
         ...parsed,
         summary: redactRawSignalText(parsed.summary),
         evidence: parsed.evidence.map((entry) => ({
             ...entry,
             excerpt: redactOperationalContext(entry.excerpt),
+            diff: typeof entry.diff === "string" ? redactOperationalContext(entry.diff) : undefined,
+            before: typeof entry.before === "string" ? redactOperationalContext(entry.before) : undefined,
+            after: typeof entry.after === "string" ? redactOperationalContext(entry.after) : undefined,
         })),
         filesTouched: parsed.filesTouched.map((filePath) => sanitizeFilePath(filePath)),
         commandsRun: parsed.commandsRun.map((command) => redactOperationalContext(command)),
@@ -278,6 +302,32 @@ function normalizeClientId(value) {
 export function normalizeInstallTokenInput(token) {
     return String(token ?? "").trim().replace(/^['"]/, "").replace(/['"]$/, "");
 }
+const echoSchema = z.enum(["summary", "full"]).optional();
+const cursorSchema = z.string().optional();
+const idempotencyKeySchema = z.string().min(1).max(200).optional();
+const maxCharsSchema = z.number().int().positive().max(100000).optional();
+function traceId() {
+    return `trace_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function structuredError(input) {
+    return {
+        ok: false,
+        code: input.code,
+        message: input.message,
+        retryable: Boolean(input.retryable),
+        hint: input.hint ?? "",
+        traceId: input.traceId ?? traceId(),
+        ...(typeof input.status === "number" ? { status: input.status } : {}),
+        ...(input.extra ?? {}),
+    };
+}
+function withResponseShape(route, responseShape = "v2") {
+    const [path, query = ""] = route.split("?");
+    const searchParams = new URLSearchParams(query);
+    searchParams.set("response_shape", responseShape);
+    const nextQuery = searchParams.toString();
+    return nextQuery ? `${path}?${nextQuery}` : path;
+}
 function routeWithQuery(route, params) {
     const searchParams = new URLSearchParams();
     for (const [key, value] of Object.entries(params)) {
@@ -334,6 +384,7 @@ async function postToServer(route, payload, options, request) {
         method,
         headers: {
             ...(method === "GET" ? {} : { "Content-Type": "application/json" }),
+            ...(request?.idempotencyKey ? { "Idempotency-Key": request.idempotencyKey } : {}),
             ...(installToken
                 ? { Authorization: `Bearer ${installToken}` }
                 : apiKey
@@ -343,18 +394,44 @@ async function postToServer(route, payload, options, request) {
         ...(method === "GET" ? {} : { body: JSON.stringify(bodyPayload) }),
     }).catch(() => null);
     if (!response) {
-        return {
-            ok: false,
-            error: "Ask The W server could not be reached.",
-        };
+        return structuredError({
+            code: "network_error",
+            message: "Ask The W server could not be reached.",
+            retryable: true,
+            hint: "Check your network connection or retry the same idempotency key.",
+        });
     }
     const body = await response.json().catch(() => null);
     if (!response.ok) {
-        return {
-            ok: false,
+        if (body && typeof body === "object") {
+            const record = body;
+            return {
+                ...structuredError({
+                    code: typeof record.code === "string" ? record.code : "http_error",
+                    message: typeof record.message === "string"
+                        ? record.message
+                        : typeof record.error === "string"
+                            ? record.error
+                            : `Ask The W request failed with HTTP ${response.status}.`,
+                    retryable: response.status === 429 || response.status >= 500,
+                    hint: typeof record.hint === "string"
+                        ? record.hint
+                        : response.status >= 500
+                            ? "Retry with the same Idempotency-Key if this was a write."
+                            : "Check the tool input and retry.",
+                    traceId: typeof record.traceId === "string" ? record.traceId : undefined,
+                    status: response.status,
+                }),
+                ...record,
+            };
+        }
+        return structuredError({
+            code: "http_error",
+            message: `Ask The W request failed with HTTP ${response.status}.`,
+            retryable: response.status === 429 || response.status >= 500,
+            hint: response.status >= 500 ? "Retry with the same Idempotency-Key if this was a write." : "Check the tool input and retry.",
             status: response.status,
-            ...(body && typeof body === "object" ? body : { error: "Ask The W request failed." }),
-        };
+        });
     }
     return body;
 }
@@ -367,6 +444,7 @@ function runtimeMetadata(options) {
     return {
         repository: scope.repoName,
         repo_name: scope.repoName,
+        scope_key: localScopeKey(),
         ...(scope.repoRoot ? { repo_root: sanitizeFilePath(scope.repoRoot) } : {}),
         ...(scope.appPath ? { app_path: sanitizeFilePath(scope.appPath) } : {}),
         ...(scope.serviceName ? { service_name: scope.serviceName } : {}),
@@ -376,6 +454,14 @@ function runtimeMetadata(options) {
         ...extraMetadata,
     };
 }
+function localScopeKey(cwd = process.cwd()) {
+    const scope = resolvePluginScope(cwd);
+    return [scope.repoRoot || scope.repoName || cwd, scope.appPath ?? "", scope.serviceName ?? ""]
+        .filter(Boolean)
+        .join("::")
+        .replace(/\s+/g, " ")
+        .slice(0, 500);
+}
 function startupSessionId(options) {
     const scope = resolvePluginScope(process.cwd());
     const { clientId } = credentials(options?.credentials);
@@ -387,6 +473,20 @@ function startupSessionId(options) {
         .replace(/[^a-zA-Z0-9:_-]+/g, "_")
         .slice(0, 240);
 }
+function loginCommandHint() {
+    for (const value of [
+        process.env.ASKTHEW_EMAIL,
+        process.env.GIT_AUTHOR_EMAIL,
+        process.env.GIT_COMMITTER_EMAIL,
+        process.env.EMAIL,
+    ]) {
+        const email = String(value ?? "").trim();
+        if (/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) {
+            return `npx @askthew/mcp-plugin identify --email ${email}`;
+        }
+    }
+    return "npx @askthew/mcp-plugin identify --email <your-email>";
+}
 async function sendStartupHeartbeat(options) {
     if (!hasServerIdentity(options?.credentials)) {
         return;
@@ -421,7 +521,7 @@ async function sendStartupSetupSignal(options) {
         sessionId: startupSessionId(options),
         sequence: 0,
         kind: "setup_complete",
-        summary: "Ask The W MCP server started for this coding-agent session.",
+        summary: "Ask The W plugin server started for this coding-agent session.",
         evidence: [],
         filesTouched: [],
         commandsRun: [],
@@ -441,20 +541,24 @@ async function sendStartupSignals(options) {
     await sendStartupSetupSignal(options).catch(() => null);
 }
 export function createAskTheWMcpServer(options = {}) {
+    const initialMode = resolveMcpMode();
+    if (initialMode.mode === "free_pending_auth") {
+        ensureLocalIdentity({
+            emailClaim: process.env.ASKTHEW_EMAIL,
+            apiUrl: options.apiBaseUrl,
+            telemetryOptOut: process.env.ASKTHEW_TELEMETRY === "off",
+        });
+    }
     const resolvedMode = resolveMcpMode();
     const optionInstallToken = normalizeInstallTokenInput(options.credentials?.installToken);
     const mode = optionInstallToken
         ? { mode: "paid", installToken: optionInstallToken, reason: "options_install_token" }
         : resolvedMode;
     const localStore = mode.mode === "paid" ? null : LocalStore.open();
-    if (localStore) {
+    if (localStore && mode.mode === "free" && mode.cliCredentials) {
         void flushTelemetryOutbox({
             store: localStore,
-            credentials: mode.cliCredentials ?? {
-                userId: "unauthenticated",
-                cliToken: "",
-                cliTokenId: "none",
-            },
+            credentials: mode.cliCredentials,
             apiUrl: options.apiBaseUrl,
             fetchImpl: options.fetchImpl,
         }).catch(() => null);
@@ -463,11 +567,11 @@ export function createAskTheWMcpServer(options = {}) {
         name: "Ask The W Coding Agent Connector",
         version: "0.4.0",
     });
-    if (options.sendStartupHeartbeat !== false) {
+    if (options.sendStartupHeartbeat !== false && mode.mode === "paid") {
         void sendStartupSignals(options);
     }
-    const apiToolResponse = async (route, payload = {}, method = "GET") => {
-        const upstream = await postToServer(route, payload, options, { method });
+    const apiToolResponse = async (route, payload = {}, method = "GET", request) => {
+        const upstream = await postToServer(route, payload, options, { method, idempotencyKey: request?.idempotencyKey });
         return {
             content: [
                 {
@@ -478,13 +582,71 @@ export function createAskTheWMcpServer(options = {}) {
         };
     };
     const localResponse = (value) => toolJson(value);
+    const localToolError = (input) => localResponse(structuredError(input));
+    const budgetedLocalResponse = (value, maxChars) => {
+        if (!maxChars || JSON.stringify(value, null, 2).length <= maxChars) {
+            return localResponse(value);
+        }
+        const next = { ...value, truncated: true, maxChars };
+        for (const key of ["signals", "decisions", "decisionCandidates", "matches"]) {
+            const list = next[key];
+            if (Array.isArray(list)) {
+                while (list.length > 0 && JSON.stringify(next, null, 2).length > maxChars) {
+                    list.pop();
+                }
+                next[key] = list;
+            }
+        }
+        if (typeof next.rendered === "string" && JSON.stringify(next, null, 2).length > maxChars) {
+            const overhead = JSON.stringify({ ...next, rendered: "" }, null, 2).length + 80;
+            next.rendered = `${next.rendered.slice(0, Math.max(0, maxChars - overhead)).trimEnd()}\n\n[truncated to max_chars=${maxChars}]`;
+        }
+        return localResponse(next);
+    };
+    const currentScopeKey = () => localScopeKey();
+    const compactWriteResponse = (input) => localResponse({
+        ok: input.ok !== false,
+        id: input.id ?? null,
+        ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+        ...(typeof input.sequence === "number" ? { sequence: input.sequence } : {}),
+        ...(typeof input.signalCount === "number" ? { signalCount: input.signalCount } : {}),
+        ...(input.warnings && input.warnings.length > 0 ? { warnings: input.warnings } : {}),
+    });
+    const upstreamId = (upstream) => {
+        if (!upstream || typeof upstream !== "object")
+            return null;
+        const record = upstream;
+        return (record.id ??
+            record.signalId ??
+            record.entry?.id ??
+            record.decision?.id ??
+            record.data?.id ??
+            record.data?.outcome?.id ??
+            record.data?.decision?.id ??
+            null);
+    };
+    const upstreamSequence = (upstream) => {
+        if (!upstream || typeof upstream !== "object")
+            return null;
+        const record = upstream;
+        const sequence = record.sequence ?? record.entry?.sequence ?? record.data?.sequence ?? null;
+        return typeof sequence === "number" ? sequence : null;
+    };
+    const upstreamFailure = (upstream) => upstream && typeof upstream === "object" && upstream.ok === false
+        ? upstream
+        : null;
     const requireFreeIdentity = () => {
-        if (mode.mode === "unauthenticated") {
-            return localResponse({
-                ok: false,
+        if (mode.mode === "unauthenticated" || mode.mode === "free_pending_auth") {
+            const loginCommand = loginCommandHint();
+            return localToolError({
                 code: "free_tier_login_required",
-                message: "Run `npx @askthew/mcp-plugin auth login --email you@example.com` to unlock local capture.",
-                supportEmail: "support@askthew.com",
+                message: "Free local mode needs a local install identity before capture.",
+                retryable: false,
+                hint: `Run \`${loginCommand}\` or reinstall with \`--free --email <your-email>\`, then restart or reload the MCP host.`,
+                extra: {
+                    loginCommand,
+                    supportEmail: "support@askthew.com",
+                },
             });
         }
         return null;
@@ -495,14 +657,13 @@ export function createAskTheWMcpServer(options = {}) {
         kind: sessionSignalKindSchema,
         summary: z.string().min(1).max(2000),
         evidence: z
-            .array(z.object({
-            role: evidenceRoleSchema,
-            excerpt: z.string().min(1).max(500),
-        }))
+            .array(evidenceEntrySchema)
             .default([]),
         filesTouched: z.array(z.string().min(1).max(500)).default([]),
         commandsRun: z.array(z.string().min(1).max(500)).default([]),
         metadata: z.record(z.string(), z.unknown()).default({}),
+        idempotencyKey: idempotencyKeySchema,
+        echo: echoSchema,
     }, async (payload) => {
         const sessionSignal = redactCodingSessionSignal({
             ...payload,
@@ -511,6 +672,7 @@ export function createAskTheWMcpServer(options = {}) {
                 ...(payload.metadata ?? {}),
             },
         });
+        const scopeKey = currentScopeKey();
         if (mode.mode !== "paid" && localStore) {
             const loginRequired = requireFreeIdentity();
             if (loginRequired) {
@@ -525,7 +687,13 @@ export function createAskTheWMcpServer(options = {}) {
                 filesTouched: sessionSignal.filesTouched,
                 commandsRun: sessionSignal.commandsRun,
                 metadata: sessionSignal.metadata,
+                scopeKey,
             });
+            const sessionSignalCount = localStore.listSignals({
+                sessionId: signal.sessionId,
+                scopeKey,
+                limit: 100000,
+            }).length;
             if (sessionSignal.kind === "final_summary" && mode.cliCredentials) {
                 localStore.enqueueTelemetry(buildTelemetryPayload({
                     store: localStore,
@@ -539,6 +707,25 @@ export function createAskTheWMcpServer(options = {}) {
                     fetchImpl: options.fetchImpl,
                 }).catch(() => null);
             }
+            if (!payload.echo) {
+                return compactWriteResponse({
+                    id: signal.id,
+                    sessionId: signal.sessionId,
+                    sequence: signal.sequence,
+                    signalCount: sessionSignalCount,
+                });
+            }
+            if (payload.echo === "summary") {
+                return localResponse({
+                    ok: true,
+                    id: signal.id,
+                    sessionId: signal.sessionId,
+                    sequence: signal.sequence,
+                    signalCount: sessionSignalCount,
+                    summary: signal.summary,
+                    kind: signal.kind,
+                });
+            }
             return localResponse({
                 ok: true,
                 tier: "free",
@@ -548,9 +735,35 @@ export function createAskTheWMcpServer(options = {}) {
                     : "Captured locally in SQLite. Aggregate telemetry only may flush on final_summary unless opted out.",
             });
         }
-        const upstream = await postToServer("/api/ingest/mcp", {
+        const upstream = await postToServer(payload.echo === "full" ? "/api/ingest/mcp" : withResponseShape("/api/ingest/mcp"), {
             sessionSignal,
-        }, options);
+        }, options, { idempotencyKey: payload.idempotencyKey });
+        const failure = upstreamFailure(upstream);
+        if (failure)
+            return localResponse(failure);
+        if (!payload.echo) {
+            return compactWriteResponse({
+                id: upstreamId(upstream),
+                sessionId: sessionSignal.sessionId,
+                sequence: sessionSignal.sequence,
+                signalCount: upstream && typeof upstream === "object" && typeof upstream.signalCount === "number"
+                    ? upstream.signalCount
+                    : 1,
+            });
+        }
+        if (payload.echo === "summary") {
+            return localResponse({
+                ok: true,
+                id: upstreamId(upstream),
+                sessionId: sessionSignal.sessionId,
+                sequence: sessionSignal.sequence,
+                signalCount: upstream && typeof upstream === "object" && typeof upstream.signalCount === "number"
+                    ? upstream.signalCount
+                    : 1,
+                summary: sessionSignal.summary,
+                kind: sessionSignal.kind,
+            });
+        }
         return {
             content: [
                 {
@@ -568,20 +781,46 @@ export function createAskTheWMcpServer(options = {}) {
     server.tool("list_decisions", {
         limit: z.number().int().positive().max(300).optional(),
         cursor: z.string().optional(),
+        sessionId: z.string().optional(),
+        status: z.enum(["proposed", "committed", "shipped", "abandoned"]).optional(),
+        since: z.string().optional(),
+        compact: z.boolean().optional(),
+        max_chars: maxCharsSchema,
     }, async (payload) => {
         if (mode.mode !== "paid" && localStore) {
             const loginRequired = requireFreeIdentity();
             if (loginRequired)
                 return loginRequired;
-            return localResponse({
+            const decisions = localStore.listDecisions({
+                limit: payload.limit ?? 5,
+                cursor: payload.cursor,
+                sessionId: payload.sessionId,
+                status: payload.status,
+                since: payload.since,
+                scopeKey: currentScopeKey(),
+            });
+            return budgetedLocalResponse({
                 ok: true,
                 tier: "free",
-                decisions: localStore.listDecisions({ limit: payload.limit ?? 50 }),
-            });
+                decisions: payload.compact !== false
+                    ? decisions.map((decision) => ({
+                        id: decision.id,
+                        headline: decision.headline,
+                        status: decision.status,
+                        signalIds: decision.sourceSignalIds,
+                    }))
+                    : decisions.map((decision) => decisionWithSignals(localStore, decision)),
+                nextCursor: decisions.length >= (payload.limit ?? 5) ? decisions.at(-1)?.createdAt ?? null : null,
+            }, payload.max_chars ?? 8000);
         }
         return apiToolResponse(routeWithQuery("/api/decisions", {
-            limit: payload.limit,
+            limit: payload.limit ?? 5,
             cursor: payload.cursor,
+            sessionId: payload.sessionId,
+            status: payload.status,
+            since: payload.since,
+            compact: payload.compact ?? true,
+            max_chars: payload.max_chars ?? 8000,
         }));
     });
     server.tool("get_decision", {
@@ -592,29 +831,79 @@ export function createAskTheWMcpServer(options = {}) {
             if (loginRequired)
                 return loginRequired;
             const decision = localStore.getDecision(payload.id);
-            return localResponse(decision ? { ok: true, tier: "free", decision } : { ok: false, code: "not_found" });
+            return decision
+                ? localResponse({ ok: true, tier: "free", decision: decisionWithSignals(localStore, decision) })
+                : localToolError({
+                    code: "not_found",
+                    message: "Decision not found in the local Ask The W store.",
+                    retryable: false,
+                    hint: "Check the decision id or search/list local decisions first.",
+                });
         }
         return apiToolResponse(`/api/decisions/${encodeURIComponent(payload.id)}`);
     });
     server.tool("create_decision", {
         content: z.string().min(1),
+        idempotencyKey: idempotencyKeySchema,
+        echo: echoSchema,
     }, async (payload) => {
         if (mode.mode !== "paid" && localStore) {
             const loginRequired = requireFreeIdentity();
             if (loginRequired)
                 return loginRequired;
+            const scopeKey = currentScopeKey();
+            if (payload.idempotencyKey) {
+                const existingId = localStore.getMeta(`idempotency:create_decision:${scopeKey}:${payload.idempotencyKey}`);
+                if (existingId) {
+                    const existing = localStore.getDecision(existingId);
+                    if (existing) {
+                        return payload.echo === "full"
+                            ? localResponse({ ok: true, tier: "free", decision: decisionWithSignals(localStore, existing), idempotent: true })
+                            : compactWriteResponse({ id: existing.id, sequence: localStore.stats().decisions });
+                    }
+                }
+            }
+            const decision = localStore.createDecision({
+                rawContent: payload.content,
+                sessionId: localStore.mostRecentSessionId({ scopeKey }),
+                scopeKey,
+            });
+            if (payload.idempotencyKey) {
+                localStore.setMeta(`idempotency:create_decision:${scopeKey}:${payload.idempotencyKey}`, decision.id);
+            }
+            const warnings = detectDecisionConflicts({
+                decision,
+                decisions: localStore.listDecisions({ limit: 100000, scopeKey }),
+            });
+            if (!payload.echo) {
+                return compactWriteResponse({
+                    id: decision.id,
+                    sequence: localStore.stats().decisions,
+                    warnings,
+                });
+            }
             return localResponse({
                 ok: true,
-                tier: "free",
-                decision: localStore.createDecision({
-                    rawContent: payload.content,
-                    sessionId: localStore.mostRecentSessionId(),
-                }),
+                ...(payload.echo === "summary"
+                    ? { id: decision.id, sequence: localStore.stats().decisions, headline: decision.headline, warnings }
+                    : { tier: "free", decision: decisionWithSignals(localStore, decision), warnings }),
             });
         }
-        return apiToolResponse("/api/decisions", {
+        const upstream = await postToServer(payload.echo === "full" ? "/api/decisions" : withResponseShape("/api/decisions"), {
             content: payload.content,
-        }, "POST");
+        }, options, { method: "POST", idempotencyKey: payload.idempotencyKey });
+        const failure = upstreamFailure(upstream);
+        if (failure)
+            return localResponse(failure);
+        if (!payload.echo) {
+            return compactWriteResponse({
+                id: upstreamId(upstream),
+                sequence: upstreamSequence(upstream) ?? 1,
+            });
+        }
+        return localResponse(payload.echo === "summary"
+            ? { ok: true, id: upstreamId(upstream), sequence: upstreamSequence(upstream) ?? 1 }
+            : upstream);
     });
     server.tool("update_decision", {
         id: z.string().min(1),
@@ -623,6 +912,8 @@ export function createAskTheWMcpServer(options = {}) {
         status: z.enum(["proposed", "committed", "shipped", "abandoned"]).optional(),
         alignment: z.enum(["aligned", "orthogonal", "conflicts", "ambiguous"]).optional(),
         outcomeId: z.string().min(1).optional(),
+        idempotencyKey: idempotencyKeySchema,
+        echo: echoSchema,
     }, async (payload) => {
         if (mode.mode !== "paid" && localStore) {
             const loginRequired = requireFreeIdentity();
@@ -634,40 +925,76 @@ export function createAskTheWMcpServer(options = {}) {
                 ...(payload.status ? { status: payload.status } : {}),
                 ...(payload.alignment !== undefined ? { alignment: payload.alignment } : {}),
             });
-            return localResponse(decision ? { ok: true, tier: "free", decision } : { ok: false, code: "not_found" });
+            if (!decision) {
+                return localToolError({
+                    code: "not_found",
+                    message: "Decision not found in the local Ask The W store.",
+                    retryable: false,
+                    hint: "Check the decision id before updating.",
+                });
+            }
+            const warnings = detectDecisionConflicts({
+                decision,
+                decisions: localStore.listDecisions({ limit: 100000, scopeKey: currentScopeKey() }),
+            });
+            if (!payload.echo) {
+                return compactWriteResponse({ id: decision.id, sequence: localStore.stats().decisions, warnings });
+            }
+            return localResponse(payload.echo === "summary"
+                ? { ok: true, id: decision.id, sequence: localStore.stats().decisions, headline: decision.headline, warnings }
+                : { ok: true, tier: "free", decision: decisionWithSignals(localStore, decision), warnings });
         }
-        return apiToolResponse(`/api/decisions/${encodeURIComponent(payload.id)}`, {
+        const upstream = await postToServer(payload.echo === "full"
+            ? `/api/decisions/${encodeURIComponent(payload.id)}`
+            : withResponseShape(`/api/decisions/${encodeURIComponent(payload.id)}`), {
             headline: payload.headline,
             why: payload.why,
             status: payload.status,
             alignment: payload.alignment,
             outcomeId: payload.outcomeId,
-        }, "PATCH");
+        }, options, { method: "PATCH", idempotencyKey: payload.idempotencyKey });
+        const failure = upstreamFailure(upstream);
+        if (failure)
+            return localResponse(failure);
+        if (!payload.echo) {
+            return compactWriteResponse({ id: upstreamId(upstream) ?? payload.id, sequence: upstreamSequence(upstream) ?? 1 });
+        }
+        return localResponse(payload.echo === "summary"
+            ? { ok: true, id: upstreamId(upstream) ?? payload.id, sequence: upstreamSequence(upstream) ?? 1 }
+            : upstream);
     });
     server.tool("delete_decision", {
         id: z.string().min(1),
         confirmText: z.string().min(1),
+        idempotencyKey: idempotencyKeySchema,
     }, async (payload) => {
         if (mode.mode !== "paid" && localStore) {
             const loginRequired = requireFreeIdentity();
             if (loginRequired)
                 return loginRequired;
             if (payload.confirmText !== payload.id) {
-                return localResponse({ ok: false, code: "confirmation_required", message: "confirmText must match the decision id." });
+                return localToolError({
+                    code: "confirmation_required",
+                    message: "confirmText must match the decision id.",
+                    retryable: false,
+                    hint: "Pass the exact decision id as confirmText.",
+                });
             }
             return localResponse({ ok: localStore.deleteDecision(payload.id), tier: "free" });
         }
         return apiToolResponse(`/api/decisions/${encodeURIComponent(payload.id)}`, {
             confirmText: payload.confirmText,
-        }, "DELETE");
+        }, "DELETE", { idempotencyKey: payload.idempotencyKey });
     });
     server.tool("list_outcomes", paidDescription("List outcomes from your workspace.", mode.mode), {
         limit: z.number().int().positive().max(300).optional(),
+        cursor: cursorSchema,
     }, async (payload) => {
         if (mode.mode === "free")
             return localResponse(paidFeatureNudge("list_outcomes"));
         return apiToolResponse(routeWithQuery("/api/outcomes", {
             limit: payload.limit,
+            cursor: payload.cursor,
         }));
     });
     server.tool("get_outcome", paidDescription("Get outcome detail from your workspace.", mode.mode), {
@@ -677,14 +1004,20 @@ export function createAskTheWMcpServer(options = {}) {
         : apiToolResponse(`/api/outcomes/${encodeURIComponent(payload.id)}`));
     server.tool("list_outcome_signals", paidDescription("List signals linked to an outcome.", mode.mode), {
         id: z.string().min(1),
+        limit: z.number().int().positive().max(300).optional(),
+        cursor: cursorSchema,
     }, async (payload) => mode.mode === "free"
         ? localResponse(paidFeatureNudge("list_outcome_signals"))
-        : apiToolResponse(`/api/outcomes/${encodeURIComponent(payload.id)}/signals`));
+        : apiToolResponse(routeWithQuery(`/api/outcomes/${encodeURIComponent(payload.id)}/signals`, {
+            limit: payload.limit,
+            cursor: payload.cursor,
+        })));
     server.tool("create_outcome", paidDescription("Create a new outcome.", mode.mode), {
         name: z.string().min(1),
         summary: z.string().optional(),
         causalHypothesis: z.string().optional(),
         suggestedAction: z.string().optional(),
+        idempotencyKey: idempotencyKeySchema,
     }, async (payload) => {
         if (mode.mode === "free")
             return localResponse(paidFeatureNudge("create_outcome"));
@@ -693,7 +1026,7 @@ export function createAskTheWMcpServer(options = {}) {
             summary: payload.summary,
             causalHypothesis: payload.causalHypothesis,
             suggestedAction: payload.suggestedAction,
-        }, "POST");
+        }, "POST", { idempotencyKey: payload.idempotencyKey });
     });
     server.tool("update_outcome", paidDescription("Update an outcome.", mode.mode), {
         id: z.string().min(1),
@@ -702,26 +1035,40 @@ export function createAskTheWMcpServer(options = {}) {
         causalHypothesis: z.string().optional(),
         suggestedAction: z.string().optional(),
         status: z.enum(["active", "achieved", "abandoned", "archived"]).optional(),
+        idempotencyKey: idempotencyKeySchema,
+        echo: echoSchema,
     }, async (payload) => {
         if (mode.mode === "free")
             return localResponse(paidFeatureNudge("update_outcome"));
-        return apiToolResponse(`/api/outcomes/${encodeURIComponent(payload.id)}`, {
+        const upstream = await postToServer(payload.echo === "full"
+            ? `/api/outcomes/${encodeURIComponent(payload.id)}`
+            : withResponseShape(`/api/outcomes/${encodeURIComponent(payload.id)}`), {
             name: payload.name,
             summary: payload.summary,
             causalHypothesis: payload.causalHypothesis,
             suggestedAction: payload.suggestedAction,
             status: payload.status,
-        }, "PATCH");
+        }, options, { method: "PATCH", idempotencyKey: payload.idempotencyKey });
+        const failure = upstreamFailure(upstream);
+        if (failure)
+            return localResponse(failure);
+        if (!payload.echo) {
+            return compactWriteResponse({ id: upstreamId(upstream) ?? payload.id, sequence: upstreamSequence(upstream) ?? 1 });
+        }
+        return localResponse(payload.echo === "summary"
+            ? { ok: true, id: upstreamId(upstream) ?? payload.id, sequence: upstreamSequence(upstream) ?? 1 }
+            : upstream);
     });
     server.tool("delete_outcome", paidDescription("Delete an outcome.", mode.mode), {
         id: z.string().min(1),
         confirmText: z.string().min(1),
+        idempotencyKey: idempotencyKeySchema,
     }, async (payload) => {
         if (mode.mode === "free")
             return localResponse(paidFeatureNudge("delete_outcome"));
         return apiToolResponse(`/api/outcomes/${encodeURIComponent(payload.id)}`, {
             confirmText: payload.confirmText,
-        }, "DELETE");
+        }, "DELETE", { idempotencyKey: payload.idempotencyKey });
     });
     server.tool("get_north_star", paidDescription("Read the workspace north-star metric.", mode.mode), {}, async () => mode.mode === "free"
         ? localResponse(paidFeatureNudge("get_north_star"))
@@ -731,6 +1078,7 @@ export function createAskTheWMcpServer(options = {}) {
         current: z.string().min(1),
         target: z.string().min(1),
         reason: z.string().min(1),
+        idempotencyKey: idempotencyKeySchema,
     }, async (payload) => {
         if (mode.mode === "free")
             return localResponse(paidFeatureNudge("update_north_star"));
@@ -739,25 +1087,85 @@ export function createAskTheWMcpServer(options = {}) {
             current: payload.current,
             target: payload.target,
             reason: payload.reason,
-        }, "POST");
+        }, "POST", { idempotencyKey: payload.idempotencyKey });
     });
     server.tool("list_signals", {
         limit: z.number().int().positive().max(300).optional(),
         cursor: z.string().optional(),
+        sessionId: z.string().optional(),
+        since: z.string().optional(),
+        compact: z.boolean().optional(),
+        max_chars: maxCharsSchema,
     }, async (payload) => {
         if (mode.mode !== "paid" && localStore) {
             const loginRequired = requireFreeIdentity();
             if (loginRequired)
                 return loginRequired;
-            return localResponse({
+            const signals = localStore.listSignals({
+                limit: payload.limit ?? 10,
+                cursor: payload.cursor,
+                sessionId: payload.sessionId,
+                since: payload.since,
+                scopeKey: currentScopeKey(),
+            });
+            return budgetedLocalResponse({
                 ok: true,
                 tier: "free",
-                signals: localStore.listSignals({ limit: payload.limit ?? 300 }),
-            });
+                signals: payload.compact !== false
+                    ? signals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id)))
+                    : signals.map((signal) => signalWithDecision(localStore, signal)),
+                nextCursor: signals.length >= (payload.limit ?? 10) ? signals.at(-1)?.capturedAt ?? null : null,
+            }, payload.max_chars ?? 8000);
         }
         return apiToolResponse(routeWithQuery("/api/signals", {
-            limit: payload.limit,
+            limit: payload.limit ?? 10,
             cursor: payload.cursor,
+            sessionId: payload.sessionId,
+            since: payload.since,
+            compact: payload.compact ?? true,
+            max_chars: payload.max_chars ?? 8000,
+        }));
+    });
+    server.tool("find_signal_by_summary", "Find recent signals by summary text without needing an opaque signal id first.", {
+        query: z.string().min(1),
+        sessionId: z.string().optional(),
+        limit: z.number().int().positive().max(50).default(5),
+        compact: z.boolean().optional(),
+        max_chars: maxCharsSchema,
+    }, async (payload) => {
+        if (mode.mode !== "paid" && localStore) {
+            const loginRequired = requireFreeIdentity();
+            if (loginRequired)
+                return loginRequired;
+            const normalizedQuery = payload.query.toLowerCase();
+            const signals = localStore
+                .listSignals({
+                limit: 100000,
+                sessionId: payload.sessionId,
+                scopeKey: currentScopeKey(),
+            })
+                .filter((signal) => [
+                signal.summary,
+                signal.kind,
+                ...signal.filesTouched,
+                ...signal.commandsRun,
+            ].join("\n").toLowerCase().includes(normalizedQuery))
+                .slice(0, payload.limit);
+            return budgetedLocalResponse({
+                ok: true,
+                tier: "free",
+                query: payload.query,
+                signals: payload.compact === false
+                    ? signals.map((signal) => signalWithDecision(localStore, signal))
+                    : signals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id))),
+            }, payload.max_chars ?? 8000);
+        }
+        return apiToolResponse(routeWithQuery("/api/signals", {
+            query: payload.query,
+            sessionId: payload.sessionId,
+            limit: payload.limit,
+            compact: payload.compact ?? true,
+            max_chars: payload.max_chars ?? 8000,
         }));
     });
     server.tool("get_signal", {
@@ -768,25 +1176,46 @@ export function createAskTheWMcpServer(options = {}) {
             if (loginRequired)
                 return loginRequired;
             const signal = localStore.getSignal(Number(payload.id));
-            return localResponse(signal ? { ok: true, tier: "free", signal } : { ok: false, code: "not_found" });
+            return signal
+                ? localResponse({ ok: true, tier: "free", signal: signalWithDecision(localStore, signal) })
+                : localToolError({
+                    code: "not_found",
+                    message: "Signal not found in the local Ask The W store.",
+                    retryable: false,
+                    hint: "Check the signal id or list local signals first.",
+                });
         }
         return apiToolResponse(`/api/signals/${encodeURIComponent(payload.id)}`);
     });
-    server.tool("review_decisions", {
+    server.tool("review_decisions", "Review captured decisions. Use for natural prompts like: What did I decide yesterday?", {
         since: z.string().optional(),
         status: z.enum(["proposed", "committed", "shipped", "abandoned"]).optional(),
         format: z.enum(["markdown", "json"]).default("markdown"),
         limit: z.number().int().positive().max(300).default(50),
+        cursor: cursorSchema,
+        sessionId: z.string().optional(),
+        compact: z.boolean().optional(),
+        max_chars: maxCharsSchema,
     }, async (payload) => {
         if (mode.mode === "paid") {
             return apiToolResponse(routeWithQuery("/api/decisions", {
                 since: payload.since,
                 status: payload.status,
                 limit: payload.limit,
+                cursor: payload.cursor,
+                sessionId: payload.sessionId,
+                compact: payload.compact,
+                max_chars: payload.max_chars,
             }));
         }
-        if (!localStore)
-            return localResponse({ ok: false, code: "local_store_unavailable" });
+        if (!localStore) {
+            return localToolError({
+                code: "local_store_unavailable",
+                message: "The local Ask The W store is unavailable.",
+                retryable: true,
+                hint: "Retry after restarting the plugin host.",
+            });
+        }
         const loginRequired = requireFreeIdentity();
         if (loginRequired)
             return loginRequired;
@@ -794,86 +1223,380 @@ export function createAskTheWMcpServer(options = {}) {
             since: payload.since,
             status: payload.status,
             limit: payload.limit,
+            cursor: payload.cursor,
+            sessionId: payload.sessionId,
+            scopeKey: currentScopeKey(),
         });
-        return localResponse({
+        return budgetedLocalResponse({
             ok: true,
             tier: "free",
             format: payload.format,
             rendered: renderDecisionDigest(decisions),
-            decisions,
+            decisions: payload.compact
+                ? decisions.map((decision) => ({
+                    id: decision.id,
+                    headline: decision.headline,
+                    status: decision.status,
+                    signalIds: decision.sourceSignalIds,
+                }))
+                : decisions.map((decision) => decisionWithSignals(localStore, decision)),
             count: decisions.length,
+            nextCursor: decisions.length >= payload.limit ? decisions.at(-1)?.createdAt ?? null : null,
             copyHint: "Copy this output to back up your decisions - `export_decisions` is a paid feature.",
-        });
+        }, payload.max_chars);
     });
-    server.tool("review_session", {
+    server.tool("review_session", "Review the current session trail. Use for natural prompts like: Show me my session trail.", {
         sessionId: z.string().optional(),
         format: z.enum(["markdown", "json"]).default("markdown"),
+        cursor: cursorSchema,
+        limit: z.number().int().positive().max(50).default(50),
+        compact: z.boolean().optional(),
+        max_chars: maxCharsSchema,
     }, async (payload) => {
         if (!localStore || mode.mode === "paid") {
-            return apiToolResponse(routeWithQuery("/api/signals", { sessionId: payload.sessionId }));
+            return apiToolResponse(routeWithQuery("/api/signals", {
+                sessionId: payload.sessionId,
+                cursor: payload.cursor,
+                limit: payload.limit,
+                compact: payload.compact,
+                max_chars: payload.max_chars,
+            }));
         }
         const loginRequired = requireFreeIdentity();
         if (loginRequired)
             return loginRequired;
-        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId();
-        const signals = sessionId ? localStore.listSignals({ sessionId, limit: 100000 }) : [];
+        const scopeKey = currentScopeKey();
+        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId({ scopeKey });
+        const allSessionIds = localStore.listSessionIds({ limit: 100000, scopeKey });
+        const allowedSessionIds = new Set(allSessionIds.slice(0, 3));
+        if (sessionId && allSessionIds.length > 3 && !allowedSessionIds.has(sessionId)) {
+            return localToolError({
+                code: "free_tier_limit",
+                message: "The free plugin can review the latest three local sessions.",
+                retryable: false,
+                hint: "Upgrade to review more than three sessions in the workspace dashboard.",
+                extra: {
+                    tool: "review_session",
+                    limit: 3,
+                    upgradeUrl: "https://askthew.com/mcp?utm_source=mcp-plugin&utm_medium=tool-nudge&utm_campaign=mcp-free&tool=review_session",
+                    cta: "Upgrade to review more than three sessions in the workspace dashboard.",
+                },
+            });
+        }
+        const limit = Math.min(50, payload.limit ?? 50);
+        const signals = sessionId
+            ? localStore.listSignals({ sessionId, scopeKey, cursor: payload.cursor, limit })
+            : [];
+        const allSignals = sessionId ? localStore.listSignals({ sessionId, scopeKey, limit: 100000 }) : [];
+        const decisions = sessionId
+            ? localStore.listDecisions({ sessionId, scopeKey, limit: 100000 })
+            : [];
+        const decisionCandidates = listDecisionCandidates({ store: localStore, sessionId, scopeKey, limit: 25 }).candidates;
         const counts = signals.reduce((accumulator, signal) => {
             accumulator[signal.kind] = (accumulator[signal.kind] ?? 0) + 1;
             return accumulator;
         }, {});
-        return localResponse({
+        const allCounts = allSignals.reduce((accumulator, signal) => {
+            accumulator[signal.kind] = (accumulator[signal.kind] ?? 0) + 1;
+            return accumulator;
+        }, {});
+        const nextCursor = signals.length >= limit ? signals.at(-1)?.capturedAt ?? null : null;
+        if (payload.format === "json") {
+            return budgetedLocalResponse({
+                ok: true,
+                tier: "free",
+                sessionId,
+                format: "json",
+                signals: payload.compact
+                    ? signals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id)))
+                    : signals.map((signal) => signalWithDecision(localStore, signal)),
+                decisions: payload.compact
+                    ? decisions.map((decision) => ({ id: decision.id, headline: decision.headline, status: decision.status, signalIds: decision.sourceSignalIds }))
+                    : decisions.map((decision) => decisionWithSignals(localStore, decision)),
+                decisionCandidates,
+                nextCursor,
+                counts: {
+                    totalSignals: allSignals.length,
+                    byKind: allCounts,
+                },
+            }, payload.max_chars);
+        }
+        return budgetedLocalResponse({
             ok: true,
             tier: "free",
             sessionId,
-            format: payload.format,
-            rendered: renderSessionFeed(signals),
-            signals,
+            format: "markdown",
+            rendered: renderSessionMarkdown({ sessionId, signals: allSignals, decisions, decisionCandidates }),
+            ...(payload.compact
+                ? { signals: allSignals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id))) }
+                : {}),
             counts: {
-                totalSignals: signals.length,
-                byKind: counts,
+                totalSignals: allSignals.length,
+                byKind: Object.keys(allCounts).length ? allCounts : counts,
             },
-        });
+        }, payload.max_chars);
     });
-    server.tool("analyze_session", {
+    server.tool("recap", "Summarize the latest local coding-agent session as a digest, standup, or share-ready recap.", {
+        format: z.enum(["digest", "standup", "share"]).default("digest"),
         sessionId: z.string().optional(),
-        window: z.enum(["session", "day", "week"]).default("session"),
+        compact: z.boolean().optional(),
+        max_chars: maxCharsSchema,
     }, async (payload) => {
-        if (!localStore || mode.mode === "paid") {
-            return localResponse(paidFeatureNudge("analyze_session"));
+        if (!localStore || mode.mode === "paid")
+            return localResponse(paidFeatureNudge("recap"));
+        const loginRequired = requireFreeIdentity();
+        if (loginRequired)
+            return loginRequired;
+        const scopeKey = currentScopeKey();
+        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId({ scopeKey });
+        const signals = sessionId ? localStore.listSignals({ sessionId, scopeKey, limit: 100000 }) : [];
+        const decisions = sessionId ? localStore.listDecisions({ sessionId, scopeKey, limit: 100000 }) : [];
+        return budgetedLocalResponse({
+            ok: true,
+            tier: "free",
+            sessionId,
+            format: payload.format,
+            rendered: renderRecap({ format: payload.format, signals, decisions }),
+            ...(payload.compact
+                ? { signals: signals.map((signal) => compactSignal(signal, localStore.getDecisionForSignal(signal.id))) }
+                : {}),
+        }, payload.max_chars);
+    });
+    server.tool("coach", "Coach the local coding-agent session. Use for natural prompts like: Coach me on this session.", {
+        scope: z.enum(["session", "week", "patterns"]).default("session"),
+        sessionId: z.string().optional(),
+        max_chars: maxCharsSchema,
+    }, async (payload) => {
+        if (payload.scope === "week" || payload.scope === "patterns") {
+            return localResponse(paidFeatureNudge("coach"));
         }
+        if (!localStore || mode.mode === "paid")
+            return localResponse(paidFeatureNudge("coach"));
         const loginRequired = requireFreeIdentity();
         if (loginRequired)
             return loginRequired;
-        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId();
-        const signals = sessionId ? localStore.listSignals({ sessionId, limit: 100000 }) : [];
-        const decisions = localStore.listDecisions({ limit: 100000 });
-        const tips = signals.length < 5 ? [] : analyzeLocalPatterns({ signals, decisions });
-        const verification = signals.filter((signal) => signal.kind === "verification_result");
-        const verificationPass = verification.filter((signal) => /pass|green|ok|success/i.test(signal.summary)).length;
+        const scopeKey = currentScopeKey();
+        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId({ scopeKey });
+        const signals = sessionId ? localStore.listSignals({ sessionId, scopeKey, limit: 100000 }) : [];
+        const decisions = sessionId ? localStore.listDecisions({ sessionId, scopeKey, limit: 100000 }) : [];
+        const coaching = buildSessionCoach({ signals, decisions });
+        return budgetedLocalResponse({
+            ok: true,
+            tier: "free",
+            scope: "session",
+            sessionId,
+            qualityScore: coaching.qualityScore,
+            biggestGap: coaching.biggestGap,
+            failureMode: coaching.failureMode,
+            rendered: `Decision quality score: ${coaching.qualityScore}/100\nBiggest gap: ${coaching.biggestGap}`,
+        }, payload.max_chars);
+    });
+    server.tool("promote_signal_to_decision", "Copy a captured signal summary into a linked local decision.", {
+        signalId: z.union([z.string(), z.number()]),
+        status: z.enum(["proposed", "committed", "shipped", "abandoned"]).default("proposed"),
+        why: z.string().optional(),
+        idempotencyKey: idempotencyKeySchema,
+    }, async (payload) => {
+        if (!localStore || mode.mode === "paid")
+            return localResponse(paidFeatureNudge("promote_signal_to_decision"));
+        const loginRequired = requireFreeIdentity();
+        if (loginRequired)
+            return loginRequired;
+        const numericSignalId = typeof payload.signalId === "number" ? payload.signalId : Number(payload.signalId);
+        if (!Number.isFinite(numericSignalId)) {
+            return localToolError({
+                code: "invalid_input",
+                message: "Invalid signalId.",
+                retryable: false,
+                hint: "Use the numeric local signal id.",
+                extra: { field: "signalId" },
+            });
+        }
+        const signal = localStore.getSignal(numericSignalId);
+        if (!signal) {
+            return localToolError({
+                code: "not_found",
+                message: "Signal not found in the local Ask The W store.",
+                retryable: false,
+                hint: "List signals first, then pass the numeric local signal id.",
+                extra: { tool: "promote_signal_to_decision" },
+            });
+        }
+        if (payload.idempotencyKey) {
+            const existingId = localStore.getMeta(`idempotency:promote_signal_to_decision:${payload.idempotencyKey}`);
+            if (existingId) {
+                const existing = localStore.getDecision(existingId);
+                if (existing) {
+                    return localResponse({
+                        ok: true,
+                        id: existing.id,
+                        sequence: localStore.stats().decisions,
+                        decision: decisionWithSignals(localStore, existing),
+                        linkedSignalId: signal.id,
+                        idempotent: true,
+                    });
+                }
+            }
+        }
+        const decision = localStore.createDecision({
+            rawContent: signal.summary,
+            headline: signal.summary,
+            why: payload.why ?? null,
+            status: payload.status,
+            sessionId: signal.sessionId,
+            files: signal.filesTouched,
+            sourceSignalIds: [signal.id],
+            scopeKey: signal.scopeKey ?? currentScopeKey(),
+        });
+        if (payload.idempotencyKey) {
+            localStore.setMeta(`idempotency:promote_signal_to_decision:${payload.idempotencyKey}`, decision.id);
+        }
+        const warnings = detectDecisionConflicts({
+            decision,
+            decisions: localStore.listDecisions({ limit: 100000, scopeKey: decision.scopeKey }),
+        });
         return localResponse({
+            ok: true,
+            id: decision.id,
+            sequence: localStore.stats().decisions,
+            decision: decisionWithSignals(localStore, decision),
+            linkedSignalId: signal.id,
+            warnings,
+        });
+    });
+    server.tool("list_decision_candidates", "List local signals that look like decision moments and can be promoted.", {
+        sessionId: z.string().optional(),
+        limit: z.number().int().positive().max(300).default(50),
+        cursor: cursorSchema,
+        max_chars: maxCharsSchema,
+    }, async (payload) => {
+        if (!localStore || mode.mode === "paid")
+            return localResponse(paidFeatureNudge("list_decision_candidates"));
+        const loginRequired = requireFreeIdentity();
+        if (loginRequired)
+            return loginRequired;
+        const scopeKey = currentScopeKey();
+        const sessionId = payload.sessionId ?? localStore.mostRecentSessionId({ scopeKey });
+        const result = listDecisionCandidates({
+            store: localStore,
+            sessionId,
+            scopeKey,
+            limit: payload.limit,
+            cursor: payload.cursor,
+        });
+        return budgetedLocalResponse({
             ok: true,
             tier: "free",
-            window: payload.window,
-            guidance: tips.length === 0
-                ? "Capture a few signals first - `analyze_session` needs at least 5 signals to surface patterns."
-                : undefined,
-            windowSummary: {
-                signalCount: signals.length,
-                decisionsCreated: decisions.length,
-                verificationPassRate: verification.length ? verificationPass / verification.length : 0,
-                directionChanges: signals.filter((signal) => signal.kind === "direction_change").length,
-                filesTouched: new Set(signals.flatMap((signal) => signal.filesTouched)).size,
-            },
-            tips,
-            paidUpsell: "Zones, health-state, velocity trends, and LLM-synthesized cross-session insights are part of the paid tier. https://askthew.com/pricing",
-            supportEmail: "support@askthew.com",
+            sessionId,
+            decisionCandidates: result.candidates,
+            nextCursor: result.nextCursor,
+        }, payload.max_chars);
+    });
+    server.tool("search_trail", "Search local signals and decisions together.", {
+        query: z.string().min(1),
+        sessionId: z.string().optional(),
+        limit: z.number().int().positive().max(100).default(25),
+        cursor: cursorSchema,
+        compact: z.boolean().optional(),
+        max_chars: maxCharsSchema,
+    }, async (payload) => {
+        if (!localStore || mode.mode === "paid")
+            return localResponse(paidFeatureNudge("search_trail"));
+        const loginRequired = requireFreeIdentity();
+        if (loginRequired)
+            return loginRequired;
+        const result = searchTrail({
+            store: localStore,
+            query: payload.query,
+            scopeKey: currentScopeKey(),
+            sessionId: payload.sessionId,
+            limit: payload.limit,
+            cursor: payload.cursor,
+            compact: payload.compact,
         });
+        return budgetedLocalResponse({
+            ok: true,
+            tier: "free",
+            query: payload.query,
+            matches: result.matches,
+            nextCursor: result.nextCursor,
+        }, payload.max_chars);
     });
     server.tool("export_decisions", paidDescription("Export decisions from your workspace.", mode.mode), {
         format: z.enum(["json", "markdown", "jsonl"]).default("json"),
-    }, async () => mode.mode === "free"
+        cursor: cursorSchema,
+        limit: z.number().int().positive().max(300).optional(),
+        max_chars: maxCharsSchema,
+    }, async (payload) => mode.mode === "free"
         ? localResponse(paidFeatureNudge("export_decisions"))
-        : apiToolResponse("/api/export/timeline"));
+        : apiToolResponse(routeWithQuery("/api/export/timeline", {
+            format: payload.format,
+            cursor: payload.cursor,
+            limit: payload.limit ?? 50,
+            max_chars: payload.max_chars ?? 8000,
+        })));
+    server.tool("view_timeline", "View signals and decisions counts bucketed by session, day, or month.", {
+        scope: z.enum(["day", "month", "session"]).default("day"),
+        range: z.enum(["7D", "30D", "90D", "12M", "CUSTOM"]).default("30D"),
+        start: z.string().optional(),
+        end: z.string().optional(),
+        limit: z.number().int().positive().max(300).optional(),
+        outcomeId: z.string().optional(),
+        decisionStatus: z.enum(["proposed", "committed", "shipped", "abandoned"]).optional(),
+        signalSource: z.string().optional(),
+        max_chars: maxCharsSchema,
+    }, async (payload) => {
+        if (mode.mode === "paid") {
+            return apiToolResponse(routeWithQuery("/api/analytics/timeline-counts", {
+                scope: payload.scope,
+                range: payload.range,
+                start: payload.start,
+                end: payload.end,
+                limit: payload.limit,
+                outcomeId: payload.outcomeId,
+                decisionStatus: payload.decisionStatus,
+                signalSource: payload.signalSource,
+            }));
+        }
+        if (!localStore) {
+            return localToolError({
+                code: "local_store_unavailable",
+                message: "The local Ask The W store is unavailable.",
+                retryable: true,
+                hint: "Retry after restarting the plugin host.",
+            });
+        }
+        const loginRequired = requireFreeIdentity();
+        if (loginRequired)
+            return loginRequired;
+        const scopeKey = currentScopeKey();
+        const points = buildLocalTimeline({
+            scope: payload.scope,
+            signals: localStore.listSignals({ scopeKey, limit: 100000 }),
+            decisions: localStore.listDecisions({ scopeKey, limit: 100000 }),
+            limit: payload.limit,
+        });
+        const totals = points.reduce((accumulator, point) => ({
+            signals: accumulator.signals + point.signalCount,
+            decisions: accumulator.decisions + point.decisionCount,
+        }), { signals: 0, decisions: 0 });
+        return budgetedLocalResponse({
+            ok: true,
+            tier: "free",
+            scope: payload.scope,
+            period: {
+                start: points[0]?.startedAt ?? points[0]?.x ?? "",
+                end: points.at(-1)?.endedAt ?? points.at(-1)?.x ?? "",
+                label: "Local timeline",
+                tz: "UTC",
+            },
+            points,
+            totals,
+            insights: buildLocalTimelineInsights(points),
+            narrative: `Local timeline: ${totals.signals} signals, ${totals.decisions} decisions.`,
+            markdownTable: renderLocalTimelineMarkdown(points, payload.scope),
+        }, payload.max_chars);
+    });
     return server;
 }
 function renderDecisionDigest(decisions) {
@@ -886,6 +1609,116 @@ function renderDecisionDigest(decisions) {
         ...decisions.map((decision) => [`## ${decision.headline}`, `- id: ${decision.id}`, `- status: ${decision.status}`, `- created: ${decision.createdAt}`, decision.why ? `- why: ${decision.why}` : "- why: not captured"].join("\n")),
     ].join("\n\n");
 }
+function buildSessionCoach(input) {
+    const verificationCount = input.signals.filter((signal) => signal.kind === "verification_result").length;
+    const implementationCount = input.signals.filter((signal) => signal.kind === "implementation_update").length;
+    const directionCount = input.signals.filter((signal) => signal.kind === "direction_change").length;
+    const finalSummaryCount = input.signals.filter((signal) => signal.kind === "final_summary").length;
+    const decisionCount = input.decisions.length;
+    const hasVerification = verificationCount > 0;
+    const hasDecision = decisionCount > 0;
+    const hasDirection = directionCount > 0;
+    const qualityScore = Math.max(0, Math.min(100, 35 +
+        Math.min(25, decisionCount * 12) +
+        (hasVerification ? 25 : 0) +
+        (hasDirection ? 10 : 0) -
+        Math.max(0, implementationCount - decisionCount) * 3));
+    const failureMode = implementationCount >= 3 && verificationCount === 0
+        ? `You captured ${implementationCount} implementation updates but no verification_result; run one check and capture it before ending.`
+        : input.signals.length >= 6 && finalSummaryCount === 0
+            ? `You captured ${input.signals.length} signals but no final_summary; close the session with the outcome and remaining risk.`
+            : decisionCount === 0 && directionCount > 0
+                ? "Direction changed, but no decision was captured; promote the clearest direction_change signal."
+                : null;
+    const biggestGap = failureMode ?? (!hasDecision
+        ? "Promote the clearest captured signal into a decision before the trail goes stale."
+        : !hasVerification
+            ? "Capture one verification result so the decision trail records whether the work actually held."
+            : implementationCount > decisionCount * 3
+                ? "There are many implementation updates per decision; collapse the important why into one decision."
+                : "The trail is usable. Keep the next decision tied to a verification result.");
+    return { qualityScore, biggestGap, failureMode };
+}
+function renderSessionMarkdown(input) {
+    const counts = input.signals.reduce((accumulator, signal) => {
+        accumulator[signal.kind] = (accumulator[signal.kind] ?? 0) + 1;
+        return accumulator;
+    }, {});
+    const activeDecisions = input.decisions.filter((decision) => decision.status !== "abandoned");
+    const coaching = buildSessionCoach({
+        signals: input.signals.map((signal) => ({ ...signal, filesTouched: [], commandsRun: [] })),
+        decisions: input.decisions,
+    });
+    const lines = [
+        "# Session Review",
+        `Session: ${input.sessionId ?? "none"}`,
+        `Signals: ${input.signals.length}`,
+        `Signal kinds: ${Object.entries(counts).map(([kind, count]) => `${kind} ${count}`).join(", ") || "none"}`,
+        `Active decisions: ${activeDecisions.length}`,
+        `Coaching tip: ${coaching.biggestGap}`,
+        "",
+        "## Signals By Kind",
+        ...Object.entries(counts)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([kind, count]) => `- ${kind}: ${count}`),
+        "",
+        "## Decision Candidates",
+        ...(input.decisionCandidates?.length
+            ? input.decisionCandidates.slice(0, 10).map((candidate) => `- signal ${candidate.signalId}: ${candidate.summary} (${candidate.suggestedStatus})`)
+            : ["- none"]),
+        "",
+        "## Active Decisions",
+        ...(activeDecisions.length
+            ? activeDecisions.map((decision) => `- ${decision.headline} (${decision.status})${decision.why ? ` - ${decision.why}` : ""}`)
+            : ["- none"]),
+    ];
+    return lines.slice(0, 300).join("\n");
+}
+function decisionalWeight(signal) {
+    const kindWeight = signal.kind === "direction_change" ? 4 : signal.kind === "verification_result" ? 3 : signal.kind === "implementation_update" ? 2 : 1;
+    const textWeight = /\b(decid|chose|commit|reject|approve|ship|verify|blocked|risk)\b/i.test(signal.summary) ? 2 : 0;
+    return kindWeight + textWeight;
+}
+function renderRecap(input) {
+    if (input.format === "standup") {
+        const blockers = input.signals.filter((signal) => /\b(block|fail|error|risk|stuck)\b/i.test(signal.summary));
+        return [
+            "# Standup Recap",
+            "## Yesterday",
+            input.decisions.length ? `- Captured ${input.decisions.length} decisions.` : "- No decisions captured.",
+            "## Today",
+            input.signals.length ? `- Review ${input.signals.length} session signals and promote the strongest one.` : "- Capture the first useful signal.",
+            "## Blockers",
+            ...(blockers.length ? blockers.slice(0, 5).map((signal) => `- ${signal.summary}`) : ["- None captured."]),
+        ].join("\n");
+    }
+    if (input.format === "share") {
+        return [
+            "# Ask The W Session Share",
+            "",
+            `Signals captured: ${input.signals.length}`,
+            `Decisions captured: ${input.decisions.length}`,
+            "",
+            "## Highlights",
+            ...input.signals
+                .slice()
+                .sort((left, right) => decisionalWeight(right) - decisionalWeight(left))
+                .slice(0, 8)
+                .map((signal) => `- ${signal.summary}`),
+            "",
+            "_Captured by Ask The W._",
+        ].join("\n");
+    }
+    return [
+        "# Session Digest",
+        "",
+        ...input.signals
+            .slice()
+            .sort((left, right) => decisionalWeight(right) - decisionalWeight(left))
+            .slice(0, 28)
+            .map((signal, index) => `${index + 1}. [${signal.kind}] ${signal.summary}`),
+    ].join("\n").split("\n").slice(0, 30).join("\n");
+}
 function renderSessionFeed(signals) {
     if (signals.length === 0) {
         return "# Session\n\nNo local signals captured yet.";
@@ -902,3 +1735,167 @@ function renderSessionFeed(signals) {
         ].join("\n")),
     ].join("\n\n");
 }
+function compactSignal(signal, decision) {
+    return {
+        id: signal.id,
+        kind: signal.kind,
+        summary: signal.summary,
+        files: signal.filesTouched,
+        decisionId: decision?.id ?? null,
+    };
+}
+function decisionWithSignals(store, decision) {
+    return {
+        ...decision,
+        contributingSignals: store.listSignalsByIds(decision.sourceSignalIds),
+    };
+}
+function signalWithDecision(store, signal) {
+    const decision = store.getDecisionForSignal(signal.id);
+    return {
+        ...signal,
+        decisionId: decision?.id ?? null,
+        decision: decision
+            ? {
+                id: decision.id,
+                headline: decision.headline,
+                status: decision.status,
+                why: decision.why,
+            }
+            : null,
+    };
+}
+function candidateFromSignal(signal, linkedDecision) {
+    if (linkedDecision)
+        return null;
+    const text = [signal.summary, ...signal.evidence.map((entry) => {
+            if (entry && typeof entry === "object") {
+                const record = entry;
+                return [record.excerpt, record.diff, record.before, record.after].filter(Boolean).join(" ");
+            }
+            return String(entry ?? "");
+        })].join(" ");
+    const hasDecisionLanguage = /\b(decid(?:e|ed|ing)?|chose|choose|commit(?:ted)?|approved?|reject(?:ed)?|let'?s go with|go with|we will|we're going to|standardize|adopt|defer|drop|keep|remove|replace)\b/i.test(text);
+    if (!hasDecisionLanguage && signal.kind !== "direction_change") {
+        return null;
+    }
+    const because = /\bbecause\b/i.test(text);
+    return {
+        id: `candidate_${signal.id}`,
+        signalId: signal.id,
+        sessionId: signal.sessionId,
+        summary: signal.summary,
+        suggestedStatus: signal.kind === "verification_result" ? "shipped" : "proposed",
+        why: because ? "The signal includes an explicit because/reason clause." : "The signal uses decision language.",
+        files: signal.filesTouched,
+        capturedAt: signal.capturedAt,
+    };
+}
+function listDecisionCandidates(input) {
+    const signals = input.store.listSignals({
+        sessionId: input.sessionId ?? undefined,
+        scopeKey: input.scopeKey,
+        cursor: input.cursor,
+        limit: Math.max(1, Math.min(300, input.limit ?? 50)),
+    });
+    const candidates = signals
+        .map((signal) => candidateFromSignal(signal, input.store.getDecisionForSignal(signal.id)))
+        .filter((candidate) => Boolean(candidate));
+    return {
+        candidates,
+        nextCursor: signals.length >= (input.limit ?? 50) ? signals.at(-1)?.capturedAt ?? null : null,
+    };
+}
+function normalizedDecisionTerms(text) {
+    const stop = new Set(["the", "and", "for", "with", "this", "that", "from", "into", "keep", "use", "adopt", "remove", "drop", "replace", "defer", "ship", "commit"]);
+    return String(text ?? "")
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/\s+/)
+        .filter((term) => term.length >= 4 && !stop.has(term));
+}
+function decisionPolarity(text) {
+    if (/\b(remove|drop|abandon|defer|reject|disable|stop|sunset|do not|don't|won't|will not)\b/i.test(text))
+        return "negative";
+    if (/\b(keep|use|adopt|enable|add|ship|commit|standardize|choose|approve|go with)\b/i.test(text))
+        return "positive";
+    return "neutral";
+}
+function detectDecisionConflicts(input) {
+    const polarity = decisionPolarity(`${input.decision.headline} ${input.decision.rawContent}`);
+    if (polarity === "neutral")
+        return [];
+    const terms = new Set(normalizedDecisionTerms(`${input.decision.headline} ${input.decision.rawContent}`));
+    if (terms.size === 0)
+        return [];
+    return input.decisions
+        .filter((prior) => prior.id !== input.decision.id)
+        .filter((prior) => !input.decision.scopeKey || prior.scopeKey === input.decision.scopeKey)
+        .map((prior) => {
+        const priorPolarity = decisionPolarity(`${prior.headline} ${prior.rawContent}`);
+        const priorTerms = normalizedDecisionTerms(`${prior.headline} ${prior.rawContent}`);
+        const overlap = priorTerms.filter((term) => terms.has(term));
+        return {
+            prior,
+            priorPolarity,
+            overlap,
+        };
+    })
+        .filter((entry) => entry.priorPolarity !== "neutral" && entry.priorPolarity !== polarity && entry.overlap.length > 0)
+        .slice(0, 3)
+        .map((entry) => ({
+        code: "possible_conflict",
+        message: `This may conflict with "${entry.prior.headline}".`,
+        conflictingDecisionId: entry.prior.id,
+        overlappingTerms: entry.overlap.slice(0, 5),
+    }));
+}
+function searchTrail(input) {
+    const terms = String(input.query ?? "")
+        .toLowerCase()
+        .split(/\s+/)
+        .filter(Boolean);
+    const limit = Math.max(1, Math.min(100, input.limit ?? 25));
+    const haystackMatches = (value) => terms.every((term) => value.toLowerCase().includes(term));
+    const signals = input.store
+        .listSignals({ scopeKey: input.scopeKey, sessionId: input.sessionId ?? undefined, cursor: input.cursor, limit: 100000 })
+        .filter((signal) => haystackMatches([
+        signal.summary,
+        signal.kind,
+        signal.filesTouched.join(" "),
+        signal.commandsRun.join(" "),
+        JSON.stringify(signal.evidence),
+        JSON.stringify(signal.metadata),
+    ].join(" ")))
+        .map((signal) => ({
+        type: "signal",
+        id: String(signal.id),
+        createdAt: signal.capturedAt,
+        score: terms.length,
+        result: input.compact ? compactSignal(signal, input.store.getDecisionForSignal(signal.id)) : signalWithDecision(input.store, signal),
+    }));
+    const decisions = input.store
+        .listDecisions({ scopeKey: input.scopeKey, sessionId: input.sessionId ?? undefined, cursor: input.cursor, limit: 100000 })
+        .filter((decision) => haystackMatches([decision.headline, decision.why ?? "", decision.rawContent, decision.files.join(" "), decision.status].join(" ")))
+        .map((decision) => ({
+        type: "decision",
+        id: decision.id,
+        createdAt: decision.createdAt,
+        score: terms.length,
+        result: input.compact
+            ? {
+                id: decision.id,
+                headline: decision.headline,
+                status: decision.status,
+                signalIds: decision.sourceSignalIds,
+            }
+            : decisionWithSignals(input.store, decision),
+    }));
+    const matches = [...signals, ...decisions]
+        .sort((left, right) => right.createdAt.localeCompare(left.createdAt))
+        .slice(0, limit);
+    return {
+        matches,
+        nextCursor: matches.length >= limit ? matches.at(-1)?.createdAt ?? null : null,
+    };
+}