@feelingmindful/thinking-graph 1.10.1 → 1.12.0

package/dist/tools/execute-skills.d.ts

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import type { ThinkingGraph } from '../engine/graph.js';
+import type { VaultBridge } from '../vault/bridge.js';
+export declare const executeSkillsSchema: z.ZodObject<{
+    executionId: z.ZodOptional<z.ZodString>;
+    planId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    stepNumber: z.ZodNumber;
+    invocation: z.ZodString;
+    plugin: z.ZodString;
+    skill: z.ZodString;
+    purpose: z.ZodOptional<z.ZodString>;
+    status: z.ZodDefault<z.ZodEnum<["completed", "failed"]>>;
+    resultSummary: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    decisions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        metadata?: Record<string, unknown> | undefined;
+    }, {
+        content: string;
+        metadata?: Record<string, unknown> | undefined;
+    }>, "many">>;
+    techDebt: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        severity: z.ZodOptional<z.ZodEnum<["critical", "high", "medium", "low"]>>;
+        effort: z.ZodOptional<z.ZodString>;
+        impact: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        metadata?: Record<string, unknown> | undefined;
+        severity?: "critical" | "high" | "medium" | "low" | undefined;
+        effort?: string | undefined;
+        impact?: string | undefined;
+    }, {
+        content: string;
+        metadata?: Record<string, unknown> | undefined;
+        severity?: "critical" | "high" | "medium" | "low" | undefined;
+        effort?: string | undefined;
+        impact?: string | undefined;
+    }>, "many">>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    projectId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    invocation: string;
+    status: "completed" | "failed";
+    skill: string;
+    stepNumber: number;
+    plugin: string;
+    resultSummary: string;
+    sessionId?: string | undefined;
+    projectId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    purpose?: string | undefined;
+    planId?: string | undefined;
+    runId?: string | undefined;
+    executionId?: string | undefined;
+    decisions?: {
+        content: string;
+        metadata?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    techDebt?: {
+        content: string;
+        metadata?: Record<string, unknown> | undefined;
+        severity?: "critical" | "high" | "medium" | "low" | undefined;
+        effort?: string | undefined;
+        impact?: string | undefined;
+    }[] | undefined;
+}, {
+    invocation: string;
+    skill: string;
+    stepNumber: number;
+    plugin: string;
+    resultSummary: string;
+    sessionId?: string | undefined;
+    projectId?: string | undefined;
+    metadata?: Record<string, unknown> | undefined;
+    status?: "completed" | "failed" | undefined;
+    purpose?: string | undefined;
+    planId?: string | undefined;
+    runId?: string | undefined;
+    executionId?: string | undefined;
+    decisions?: {
+        content: string;
+        metadata?: Record<string, unknown> | undefined;
+    }[] | undefined;
+    techDebt?: {
+        content: string;
+        metadata?: Record<string, unknown> | undefined;
+        severity?: "critical" | "high" | "medium" | "low" | undefined;
+        effort?: string | undefined;
+        impact?: string | undefined;
+    }[] | undefined;
+}>;
+export type ExecuteSkillsInput = z.infer<typeof executeSkillsSchema>;
+export declare function executeSkillsHandler(graph: ThinkingGraph, input: ExecuteSkillsInput, vault?: VaultBridge, projectSlug?: string): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/execute-skills.js

@@ -0,0 +1,274 @@
+import { z } from 'zod';
+import { learnHandler } from './learn.js';
+import { findExecutionInstances, findStoredPlan, parseExecutionId, resolveExecutionInstance, resolveExecutionProgress, } from './execute-plan.js';
+const metadataSchema = z.record(z.unknown());
+const decisionOutputSchema = z.object({
+    content: z.string(),
+    metadata: metadataSchema.optional(),
+});
+const techDebtOutputSchema = z.object({
+    content: z.string(),
+    severity: z.enum(['critical', 'high', 'medium', 'low']).optional(),
+    effort: z.string().optional(),
+    impact: z.string().optional(),
+    metadata: metadataSchema.optional(),
+});
+export const executeSkillsSchema = z.object({
+    executionId: z.string().optional().describe('Execution ID returned by execute-plan for a specific run. Prefer passing this exact value forward once a run has started.'),
+    planId: z.string().optional().describe('Plan ID returned by plan-skills'),
+    runId: z.string().optional().describe('Execution instance ID for this plan within the project. Required to disambiguate when execute-plan returned availableRunIds.'),
+    stepNumber: z.coerce.number().int().min(1),
+    invocation: z.string(),
+    plugin: z.string(),
+    skill: z.string(),
+    purpose: z.string().optional(),
+    status: z.enum(['completed', 'failed']).default('completed'),
+    resultSummary: z.string().describe('Human-readable summary of what the step produced or why it failed'),
+    metadata: metadataSchema.optional(),
+    decisions: z.array(decisionOutputSchema).optional(),
+    techDebt: z.array(techDebtOutputSchema).optional(),
+    sessionId: z.string().optional(),
+    projectId: z.string().optional(),
+});
+function asRecord(value) {
+    return value && typeof value === 'object' ? value : {};
+}
+async function resolveSession(graph, sessionId, projectId) {
+    if (!sessionId)
+        return graph.getCurrentSession();
+    return (await graph.storage.getSession(sessionId)) ?? graph.createSession({ id: sessionId, projectId });
+}
+function parseLearnResponse(result) {
+    return JSON.parse(result.content[0].text);
+}
+async function getPriorSkillResults(graph, _sessionId, projectId, executionId) {
+    const result = await graph.findNodes({ type: 'skill_result', projectId, limit: 1000 });
+    return result.items.filter(node => asRecord(node.metadata).executionId === executionId);
+}
+export async function executeSkillsHandler(graph, input, vault, projectSlug) {
+    const session = await resolveSession(graph, input.sessionId, input.projectId);
+    const parsedExecution = input.executionId ? parseExecutionId(input.executionId) : null;
+    const planId = input.planId ?? parsedExecution?.planId;
+    const status = input.status ?? 'completed';
+    if (input.executionId && !parsedExecution) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: 'Invalid executionId format.' }) }] };
+    }
+    if (input.planId && parsedExecution && input.planId !== parsedExecution.planId) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: 'planId does not match executionId.' }) }] };
+    }
+    if (input.runId && parsedExecution && input.runId !== parsedExecution.runId) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: 'runId does not match executionId.' }) }] };
+    }
+    if (!planId) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: 'executionId or planId is required. When multiple runs exist, pass runId from execute-plan.availableRunIds.' }) }] };
+    }
+    const storedPlan = await findStoredPlan(graph, session.id, input.projectId, planId);
+    if (!storedPlan) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: `No stored plan found for ${planId}. Run execute-plan first.` }) }] };
+    }
+    let executionId = input.executionId;
+    let runId = input.runId ?? parsedExecution?.runId;
+    if (executionId) {
+        const knownInstances = await findExecutionInstances(graph, input.projectId, planId);
+        const matchingInstance = knownInstances.find(instance => instance.executionId === executionId);
+        if (!matchingInstance) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            status: 'error',
+                            planId,
+                            error: `Execution ${executionId} is unknown. Run execute-plan first for this run and reuse its executionId/runId pair.`,
+                            availableRunIds: knownInstances.map(instance => instance.runId).sort(),
+                        }),
+                    }],
+            };
+        }
+        runId = matchingInstance.runId;
+    }
+    else {
+        const executionInstance = await resolveExecutionInstance(graph, session, input.projectId, storedPlan, input.runId);
+        if (!executionInstance.instance) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            status: 'error',
+                            planId,
+                            error: executionInstance.error,
+                            availableRunIds: executionInstance.availableRunIds ?? [],
+                        }),
+                    }],
+            };
+        }
+        executionId = executionInstance.instance.executionId;
+        runId = executionInstance.instance.runId;
+    }
+    if (!runId) {
+        runId = parseExecutionId(executionId)?.runId;
+    }
+    const progress = await resolveExecutionProgress(graph, session.id, input.projectId, storedPlan, executionId);
+    if (!progress.nextStep) {
+        return { content: [{ type: 'text', text: JSON.stringify({ status: 'error', error: `Execution ${executionId} is already complete.` }) }] };
+    }
+    if (progress.blockingGate) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'awaiting_approval',
+                        executionId,
+                        planId,
+                        runId,
+                        blockedByGate: progress.blockingGate,
+                        nextStep: progress.nextStep,
+                        error: `Approval gate ${progress.blockingGate.id} must be approved before step ${progress.nextStep.stepNumber}. Rerun execute-plan with runId ${runId}.`,
+                    }),
+                }],
+        };
+    }
+    if (progress.nextStep.stepNumber !== input.stepNumber) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'error',
+                        executionId,
+                        planId,
+                        runId,
+                        error: `Step ${input.stepNumber} is out of order. Record step ${progress.nextStep.stepNumber} next.`,
+                        nextStep: progress.nextStep,
+                        completedSteps: progress.completedSteps,
+                    }),
+                }],
+        };
+    }
+    if (input.invocation !== progress.nextStep.invocation
+        || input.plugin !== progress.nextStep.plugin
+        || input.skill !== progress.nextStep.skill) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        status: 'error',
+                        executionId,
+                        planId,
+                        runId,
+                        error: `Step ${input.stepNumber} does not match the stored plan entry.`,
+                        expectedStep: progress.nextStep,
+                    }),
+                }],
+        };
+    }
+    const priorResults = await getPriorSkillResults(graph, session.id, input.projectId, executionId);
+    const attempt = priorResults.filter(node => asRecord(node.metadata).stepNumber === input.stepNumber).length + 1;
+    const priorStepNode = priorResults
+        .filter(node => asRecord(node.metadata).stepNumber === input.stepNumber - 1)
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0];
+    const skillResult = await learnHandler(graph, {
+        content: `Step ${input.stepNumber} (${input.invocation}) attempt ${attempt}: ${input.resultSummary}`,
+        type: 'skill_result',
+        projectId: input.projectId,
+        sessionId: session.id,
+        metadata: {
+            kind: 'skill_execution',
+            executionId,
+            planId,
+            runId,
+            stepNumber: input.stepNumber,
+            invocation: input.invocation,
+            plugin: input.plugin,
+            skill: input.skill,
+            purpose: input.purpose,
+            status,
+            attempt,
+            ...(input.metadata ?? {}),
+        },
+    }, vault, projectSlug);
+    const skillResultData = parseLearnResponse(skillResult);
+    if (priorStepNode) {
+        await graph.addEdge({
+            sourceId: skillResultData.nodeId,
+            targetId: priorStepNode.id,
+            type: 'depends_on',
+            reasoning: 'Execution order dependency between consecutive steps.',
+        });
+    }
+    const decisionNodeIds = [];
+    for (const decision of input.decisions ?? []) {
+        const recorded = await learnHandler(graph, {
+            content: decision.content,
+            type: 'decision',
+            projectId: input.projectId,
+            sessionId: session.id,
+            metadata: {
+                kind: 'skill_output_decision',
+                executionId,
+                planId,
+                runId,
+                stepNumber: input.stepNumber,
+                invocation: input.invocation,
+                sourceSkillResultId: skillResultData.nodeId,
+                ...(decision.metadata ?? {}),
+            },
+        }, vault, projectSlug);
+        const recordedData = parseLearnResponse(recorded);
+        decisionNodeIds.push(recordedData.nodeId);
+        await graph.addEdge({
+            sourceId: recordedData.nodeId,
+            targetId: skillResultData.nodeId,
+            type: 'invoked_by',
+            reasoning: 'Decision captured from skill execution output.',
+        });
+    }
+    const techDebtNodeIds = [];
+    for (const debt of input.techDebt ?? []) {
+        const recorded = await learnHandler(graph, {
+            content: debt.content,
+            type: 'tech_debt',
+            projectId: input.projectId,
+            sessionId: session.id,
+            severity: debt.severity,
+            effort: debt.effort,
+            impact: debt.impact,
+            metadata: {
+                kind: 'skill_output_tech_debt',
+                executionId,
+                planId,
+                runId,
+                stepNumber: input.stepNumber,
+                invocation: input.invocation,
+                sourceSkillResultId: skillResultData.nodeId,
+                ...(debt.metadata ?? {}),
+            },
+        }, vault, projectSlug);
+        const recordedData = parseLearnResponse(recorded);
+        techDebtNodeIds.push(recordedData.nodeId);
+        await graph.addEdge({
+            sourceId: recordedData.nodeId,
+            targetId: skillResultData.nodeId,
+            type: 'invoked_by',
+            reasoning: 'Tech debt captured from skill execution output.',
+        });
+    }
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    status,
+                    executionId,
+                    planId,
+                    runId,
+                    skillResultNodeId: skillResultData.nodeId,
+                    stepNumber: input.stepNumber,
+                    attempt,
+                    decisionNodeIds,
+                    techDebtNodeIds,
+                    recordedCount: 1 + decisionNodeIds.length + techDebtNodeIds.length,
+                    nextAction: status === 'failed'
+                        ? `Fix or rerun ${input.invocation}, then record a successful retry before continuing.`
+                        : `Rerun execute-plan for ${executionId} to continue with the next step.`,
+                }),
+            }],
+    };
+}

package/dist/tools/learn.d.ts

@@ -5,6 +5,7 @@ export declare const learnSchema: z.ZodObject<{
     content: z.ZodString;
     type: z.ZodEnum<["thought", "decision", "insight", "code_fact", "assumption", "detection", "tech_debt", "principle", "pattern", "skill_result", "research"]>;
     projectId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
     filePath: z.ZodOptional<z.ZodString>;
     lineRange: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
     severity: z.ZodOptional<z.ZodEnum<["critical", "high", "medium", "low"]>>;
@@ -28,6 +29,7 @@ export declare const learnSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: "thought" | "decision" | "insight" | "code_fact" | "assumption" | "detection" | "tech_debt" | "principle" | "pattern" | "skill_result" | "research";
     content: string;
+    sessionId?: string | undefined;
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
@@ -44,6 +46,7 @@ export declare const learnSchema: z.ZodObject<{
 }, {
     type: "thought" | "decision" | "insight" | "code_fact" | "assumption" | "detection" | "tech_debt" | "principle" | "pattern" | "skill_result" | "research";
     content: string;
+    sessionId?: string | undefined;
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;

package/dist/tools/learn.js

@@ -5,6 +5,7 @@ export const learnSchema = z.object({
     content: z.string().describe('What was learned'),
     type: z.enum(NODE_TYPES).describe('Node type'),
     projectId: z.string().optional(),
+    sessionId: z.string().optional(),
     filePath: z.string().optional().describe('For code_facts'),
     lineRange: z.tuple([z.coerce.number(), z.coerce.number()]).optional().describe('Line range [start, end]'),
     severity: z.enum(['critical', 'high', 'medium', 'low']).optional().describe('For tech_debt'),
@@ -46,7 +47,9 @@ export async function learnHandler(graph, input, vault, projectSlug) {
         metadata.effort = input.effort;
     if (input.impact)
         metadata.impact = input.impact;
-    const session = await graph.getCurrentSession();
+    const session = input.sessionId
+        ? ((await graph.storage.getSession(input.sessionId)) ?? await graph.createSession({ id: input.sessionId, projectId: input.projectId }))
+        : await graph.getCurrentSession();
     const node = await graph.addNode({
         type: input.type,
         content: input.content,

package/dist/tools/plan-skills.d.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import type { ThinkingGraph } from '../engine/graph.js';
+export declare const planSkillsSchema: z.ZodObject<{
+    request: z.ZodString;
+    platform: z.ZodOptional<z.ZodEnum<["ios", "android", "web", "all"]>>;
+    goalVerb: z.ZodOptional<z.ZodString>;
+    areas: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    currentState: z.ZodOptional<z.ZodEnum<["new", "existing", "unknown"]>>;
+    detectedNeeds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    selectedInvocation: z.ZodOptional<z.ZodString>;
+    requireApproval: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
+    maxCandidates: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    request: string;
+    areas?: string[] | undefined;
+    platform?: "all" | "web" | "ios" | "android" | undefined;
+    currentState?: "unknown" | "new" | "existing" | undefined;
+    goalVerb?: string | undefined;
+    detectedNeeds?: string[] | undefined;
+    maxCandidates?: number | undefined;
+    selectedInvocation?: string | undefined;
+    requireApproval?: boolean | undefined;
+}, {
+    request: string;
+    areas?: string[] | undefined;
+    platform?: "all" | "web" | "ios" | "android" | undefined;
+    currentState?: "unknown" | "new" | "existing" | undefined;
+    goalVerb?: string | undefined;
+    detectedNeeds?: string[] | undefined;
+    maxCandidates?: number | undefined;
+    selectedInvocation?: string | undefined;
+    requireApproval?: unknown;
+}>;
+export type PlanSkillsInput = z.infer<typeof planSkillsSchema>;
+export declare function planSkillsHandler(graph: ThinkingGraph, input: PlanSkillsInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/plan-skills.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { buildPlanId, buildSkillPlan } from './skill-routing.js';
+const coerceBool = z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean());
+export const planSkillsSchema = z.object({
+    request: z.string().describe('Task or problem to convert into an ordered skill execution plan'),
+    platform: z.enum(['ios', 'android', 'web', 'all']).optional().describe('Preferred platform filter'),
+    goalVerb: z.string().optional().describe('Desired outcome verb such as audit, create, refactor, configure, research, or full'),
+    areas: z.array(z.string()).optional().describe('Explicit areas to weight such as accessibility, auth, observability, or copy'),
+    currentState: z.enum(['new', 'existing', 'unknown']).optional().describe('Whether the target is greenfield or an existing project'),
+    detectedNeeds: z.array(z.string()).optional().describe('Known states such as missing, needs-work, or good'),
+    selectedInvocation: z.string().optional().describe('Force a specific routed invocation when you want the plan built from a chosen candidate'),
+    requireApproval: coerceBool.optional().describe('Whether to insert approval gates before execution (default true)'),
+    maxCandidates: z.coerce.number().int().min(1).max(10).optional().describe('Maximum ranked candidates to consider during routing'),
+});
+export async function planSkillsHandler(graph, input) {
+    const planned = await buildSkillPlan(graph, input);
+    const planId = planned.plan.length > 0
+        ? buildPlanId({ request: input.request, plan: planned.plan, approvalGates: planned.approvalGates })
+        : null;
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    planId,
+                    request: input.request,
+                    desiredVerb: planned.desiredVerb,
+                    inferredAreas: planned.inferredAreas,
+                    heuristicNotes: planned.heuristicNotes,
+                    route: planned.route,
+                    plan: planned.plan,
+                    approvalGates: planned.approvalGates,
+                    fallbacks: planned.fallbacks,
+                    executionReady: planned.approvalGates.length === 0,
+                    nextAction: planned.approvalGates.length > 0
+                        ? `Request approval for ${planned.approvalGates[0].id} before executing step ${planned.approvalGates[0].beforeStepNumber}.`
+                        : 'Execution may proceed.',
+                }),
+            }],
+    };
+}

package/dist/tools/recommend-skills.js

@@ -60,8 +60,8 @@ export async function recommendSkillsHandler(graph, input) {
     // Build suggestions for the agent
     const suggestions = skills.slice(0, 3).map(s => ({
         tool: 'skill',
-        when: `Invoke ${s.plugin}:${s.skill} to ${s.verb ?? 'run'} ${s.areas.length > 0 ? `(covers: ${s.areas.join(', ')})` : ''}`,
-        example: { skill: `${s.plugin}:${s.skill}` },
+        when: `Run \`${s.invocation}\`${s.areas.length > 0 ? ` (covers: ${s.areas.join(', ')})` : ''}`,
+        example: { skill: `${s.plugin}:${s.skill}`, invocation: s.invocation },
     }));
     // If skills produce node types, suggest piping results back via learn
     if (skills.some(s => s.produces.length > 0)) {

package/dist/tools/research.d.ts

@@ -3,7 +3,7 @@ import type { ThinkingGraph } from '../engine/graph.js';
 import { type VaultBridge } from '../vault/bridge.js';
 export declare const researchSchema: z.ZodObject<{
     query: z.ZodString;
-    intent: z.ZodDefault<z.ZodEnum<["fact_check", "explore", "compare", "how_to", "current_state"]>>;
+    intent: z.ZodDefault<z.ZodEnum<["fact_check", "explore", "compare", "how_to", "current_state", "grounded_qa"]>>;
     context: z.ZodOptional<z.ZodString>;
     researchId: z.ZodOptional<z.ZodString>;
     findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -23,9 +23,11 @@ export declare const researchSchema: z.ZodObject<{
     scrapeUrls: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     recencyFilter: z.ZodOptional<z.ZodEnum<["hour", "day", "week", "month", "year"]>>;
     domainFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    notebookId: z.ZodOptional<z.ZodString>;
+    skipGrounded: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
 }, "strip", z.ZodTypeAny, {
     query: string;
-    intent: "fact_check" | "explore" | "compare" | "how_to" | "current_state";
+    intent: "fact_check" | "explore" | "compare" | "how_to" | "current_state" | "grounded_qa";
     projectId?: string | undefined;
     context?: string | undefined;
     researchId?: string | undefined;
@@ -37,10 +39,12 @@ export declare const researchSchema: z.ZodObject<{
     scrapeUrls?: string[] | undefined;
     recencyFilter?: "hour" | "day" | "week" | "month" | "year" | undefined;
     domainFilter?: string[] | undefined;
+    notebookId?: string | undefined;
+    skipGrounded?: boolean | undefined;
 }, {
     query: string;
     projectId?: string | undefined;
-    intent?: "fact_check" | "explore" | "compare" | "how_to" | "current_state" | undefined;
+    intent?: "fact_check" | "explore" | "compare" | "how_to" | "current_state" | "grounded_qa" | undefined;
     context?: string | undefined;
     researchId?: string | undefined;
     findings?: {
@@ -51,6 +55,8 @@ export declare const researchSchema: z.ZodObject<{
     scrapeUrls?: string[] | undefined;
     recencyFilter?: "hour" | "day" | "week" | "month" | "year" | undefined;
     domainFilter?: string[] | undefined;
+    notebookId?: string | undefined;
+    skipGrounded?: unknown;
 }>;
 export type ResearchInput = z.infer<typeof researchSchema>;
 export declare function researchHandler(graph: ThinkingGraph, input: ResearchInput, vault?: VaultBridge, projectSlug?: string): Promise<{

package/dist/tools/research.js

@@ -7,7 +7,11 @@ const RESEARCH_INTENTS = [
     'compare', // Compare options, libraries, approaches
     'how_to', // Find implementation guidance
     'current_state', // Get current state of something (version, status, etc.)
+    'grounded_qa', // Query a curated knowledge base (NotebookLM notebook) — zero hallucinations
 ];
+// Intents that should preferentially route through a NotebookLM notebook when available.
+// These are the cases where a curated, citation-backed source is most valuable.
+const GROUNDED_PREFERRED_INTENTS = new Set(['how_to', 'fact_check', 'current_state', 'grounded_qa']);
 const findingSchema = z.object({
     content: z.string().describe('What was found'),
     source: z.string().optional().describe('URL or citation'),
@@ -26,10 +30,51 @@ export const researchSchema = z.object({
     scrapeUrls: z.array(z.string()).optional().describe('Specific URLs to scrape with Firecrawl'),
     recencyFilter: z.enum(['hour', 'day', 'week', 'month', 'year']).optional().describe('How recent results should be'),
     domainFilter: z.array(z.string()).optional().describe('Restrict to these domains'),
+    notebookId: z.string().optional().describe('Specific NotebookLM notebook ID to query. If omitted, action plan will list notebooks first so the caller can pick the best match.'),
+    skipGrounded: coerceBool.optional().describe('Skip NotebookLM step even when it would normally auto-prepend'),
 });
+function buildGroundedSteps(input) {
+    const steps = [];
+    const query = input.query;
+    // If caller specified a notebookId, select it then ask directly.
+    if (input.notebookId) {
+        steps.push({
+            tool: 'mcp__notebooklm__select_notebook',
+            description: 'Select the specified NotebookLM notebook',
+            args: { id: input.notebookId },
+        });
+        steps.push({
+            tool: 'mcp__notebooklm__ask_question',
+            description: 'Ask NotebookLM (grounded, citation-backed)',
+            args: { question: query },
+        });
+        return steps;
+    }
+    // Otherwise: search the library for the best match, then the agent picks one and asks.
+    steps.push({
+        tool: 'mcp__notebooklm__search_notebooks',
+        description: 'Find a NotebookLM notebook matching this query. Skip remaining NotebookLM steps if no match.',
+        args: { query },
+    });
+    steps.push({
+        tool: 'mcp__notebooklm__ask_question',
+        description: 'Ask the selected NotebookLM notebook. Only run after search_notebooks returns a match; fall back to the web-grounded steps below if the library has no relevant notebook.',
+        args: { question: query },
+    });
+    return steps;
+}
 function buildActionPlan(input) {
     const steps = [];
     const query = input.query;
+    // Grounded NotebookLM path (preferred for how_to / fact_check / current_state / grounded_qa).
+    const shouldPrependGrounded = !input.skipGrounded && GROUNDED_PREFERRED_INTENTS.has(input.intent ?? 'explore');
+    if (shouldPrependGrounded) {
+        steps.push(...buildGroundedSteps(input));
+    }
+    // grounded_qa is NotebookLM-only — no web fallback steps.
+    if (input.intent === 'grounded_qa') {
+        return steps;
+    }
     // Choose Perplexity tool based on intent
     switch (input.intent) {
         case 'fact_check':

package/dist/tools/route-skills.d.ts

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import type { ThinkingGraph } from '../engine/graph.js';
+export declare const routeSkillsSchema: z.ZodObject<{
+    request: z.ZodString;
+    platform: z.ZodOptional<z.ZodEnum<["ios", "android", "web", "all"]>>;
+    goalVerb: z.ZodOptional<z.ZodString>;
+    areas: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    currentState: z.ZodOptional<z.ZodEnum<["new", "existing", "unknown"]>>;
+    detectedNeeds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    maxCandidates: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    request: string;
+    areas?: string[] | undefined;
+    platform?: "all" | "web" | "ios" | "android" | undefined;
+    currentState?: "unknown" | "new" | "existing" | undefined;
+    goalVerb?: string | undefined;
+    detectedNeeds?: string[] | undefined;
+    maxCandidates?: number | undefined;
+}, {
+    request: string;
+    areas?: string[] | undefined;
+    platform?: "all" | "web" | "ios" | "android" | undefined;
+    currentState?: "unknown" | "new" | "existing" | undefined;
+    goalVerb?: string | undefined;
+    detectedNeeds?: string[] | undefined;
+    maxCandidates?: number | undefined;
+}>;
+export type RouteSkillsInput = z.infer<typeof routeSkillsSchema>;
+export declare function routeSkillsHandler(graph: ThinkingGraph, input: RouteSkillsInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;