@feelingmindful/thinking-graph 1.3.0 → 1.5.0

package/dist/compat/sequential.d.ts

@@ -1,20 +1,15 @@
 import { z } from 'zod';
 import type { ThinkingGraph } from '../engine/graph.js';
-/**
- * Backward compatibility shim for the original `sequentialthinking` tool.
- * Maps the old API (thought, thoughtNumber, totalThoughts, nextThoughtNeeded)
- * to the new `think` tool, preserving the original response format.
- */
 export declare const sequentialSchema: z.ZodObject<{
     thought: z.ZodString;
     thoughtNumber: z.ZodNumber;
     totalThoughts: z.ZodNumber;
-    nextThoughtNeeded: z.ZodBoolean;
-    isRevision: z.ZodOptional<z.ZodBoolean>;
+    nextThoughtNeeded: z.ZodEffects<z.ZodBoolean, boolean, unknown>;
+    isRevision: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
     revisesThought: z.ZodOptional<z.ZodNumber>;
     branchFromThought: z.ZodOptional<z.ZodNumber>;
     branchId: z.ZodOptional<z.ZodString>;
-    needsMoreThoughts: z.ZodOptional<z.ZodBoolean>;
+    needsMoreThoughts: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
 }, "strip", z.ZodTypeAny, {
     thought: string;
     thoughtNumber: number;
@@ -29,12 +24,12 @@ export declare const sequentialSchema: z.ZodObject<{
     thought: string;
     thoughtNumber: number;
     totalThoughts: number;
-    nextThoughtNeeded: boolean;
     branchId?: string | undefined;
-    isRevision?: boolean | undefined;
+    isRevision?: unknown;
     revisesThought?: number | undefined;
+    nextThoughtNeeded?: unknown;
     branchFromThought?: number | undefined;
-    needsMoreThoughts?: boolean | undefined;
+    needsMoreThoughts?: unknown;
 }>;
 export type SequentialInput = z.infer<typeof sequentialSchema>;
 export declare function compatHandler(graph: ThinkingGraph, input: SequentialInput): Promise<{

package/dist/compat/sequential.js

@@ -4,16 +4,17 @@ import { z } from 'zod';
  * Maps the old API (thought, thoughtNumber, totalThoughts, nextThoughtNeeded)
  * to the new `think` tool, preserving the original response format.
  */
+const coerceBool = z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean());
 export const sequentialSchema = z.object({
     thought: z.string().describe('The current thinking step'),
-    thoughtNumber: z.number().int().min(1).describe('Current thought number'),
-    totalThoughts: z.number().int().min(1).describe('Estimated total thoughts'),
-    nextThoughtNeeded: z.boolean().describe('Whether another step is needed'),
-    isRevision: z.boolean().optional(),
-    revisesThought: z.number().int().min(1).optional(),
-    branchFromThought: z.number().int().min(1).optional(),
+    thoughtNumber: z.coerce.number().int().min(1).describe('Current thought number'),
+    totalThoughts: z.coerce.number().int().min(1).describe('Estimated total thoughts'),
+    nextThoughtNeeded: coerceBool.describe('Whether another step is needed'),
+    isRevision: coerceBool.optional(),
+    revisesThought: z.coerce.number().int().min(1).optional(),
+    branchFromThought: z.coerce.number().int().min(1).optional(),
     branchId: z.string().optional(),
-    needsMoreThoughts: z.boolean().optional(),
+    needsMoreThoughts: coerceBool.optional(),
 });
 export async function compatHandler(graph, input) {
     const session = await graph.getCurrentSession();

package/dist/index.js

@@ -9,7 +9,8 @@ import { relateSchema, relateHandler } from './tools/relate.js';
 import { recallSchema, recallHandler } from './tools/recall.js';
 import { learnSchema, learnHandler } from './tools/learn.js';
 import { exportSchema, exportHandler } from './tools/export.js';
-import { sequentialSchema, compatHandler } from './compat/sequential.js';
+import { researchSchema, researchHandler } from './tools/research.js';
+// Legacy compat shim removed — use `think` tool directly
 // ─── Storage setup ───────────────────────────────────────
 const memoryOnly = process.env.THINKING_GRAPH_MEMORY_ONLY === 'true';
 const storage = memoryOnly
@@ -30,8 +31,7 @@ server.tool('relate', 'Create a typed, directional relationship between two node
 server.tool('recall', 'Query the thinking graph — search by text, filter by type, traverse relationships, or search across projects.', recallSchema.shape, async (input) => recallHandler(graph, input));
 server.tool('learn', 'Store durable knowledge — code facts, tech debt, insights, principles. Deduplicates similar content.', learnSchema.shape, async (input) => learnHandler(graph, input));
 server.tool('export', 'Export the thinking graph as JSON or a human-readable markdown summary.', exportSchema.shape, async (input) => exportHandler(graph, input));
-// Backward compat: register the original tool name
-server.tool('sequentialthinking', 'Record a sequential thinking step (backward compatible with @modelcontextprotocol/server-sequential-thinking).', sequentialSchema.shape, async (input) => compatHandler(graph, input));
+server.tool('research', 'Research a topic using Perplexity/Firecrawl, then ingest findings into the graph. Two-phase: call once to get an action plan, then again with findings to store them.', researchSchema.shape, async (input) => researchHandler(graph, input));
 // ─── Startup ─────────────────────────────────────────────
 async function main() {
     await storage.initialize();

package/dist/tools/export.d.ts

@@ -5,7 +5,7 @@ export declare const exportSchema: z.ZodObject<{
     sessionId: z.ZodOptional<z.ZodString>;
     projectId: z.ZodOptional<z.ZodString>;
     type: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["thought", "decision", "insight", "code_fact", "assumption", "detection", "tech_debt", "principle", "pattern", "skill_result", "research"]>, z.ZodArray<z.ZodEnum<["thought", "decision", "insight", "code_fact", "assumption", "detection", "tech_debt", "principle", "pattern", "skill_result", "research"]>, "many">]>>;
-    includeEdges: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    includeEdges: z.ZodDefault<z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>>;
     outputPath: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     format: "json" | "summary";
@@ -19,7 +19,7 @@ export declare const exportSchema: z.ZodObject<{
     type?: "thought" | "decision" | "insight" | "code_fact" | "assumption" | "detection" | "tech_debt" | "principle" | "pattern" | "skill_result" | "research" | ("thought" | "decision" | "insight" | "code_fact" | "assumption" | "detection" | "tech_debt" | "principle" | "pattern" | "skill_result" | "research")[] | undefined;
     sessionId?: string | undefined;
     projectId?: string | undefined;
-    includeEdges?: boolean | undefined;
+    includeEdges?: unknown;
     outputPath?: string | undefined;
 }>;
 export type ExportInput = z.infer<typeof exportSchema>;

package/dist/tools/export.js

@@ -6,7 +6,7 @@ export const exportSchema = z.object({
     sessionId: z.string().optional(),
     projectId: z.string().optional(),
     type: z.union([z.enum(NODE_TYPES), z.array(z.enum(NODE_TYPES))]).optional(),
-    includeEdges: z.boolean().optional().default(true),
+    includeEdges: z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean()).optional().default(true),
     outputPath: z.string().optional().describe('Write to file'),
 });
 export async function exportHandler(graph, input) {

package/dist/tools/learn.d.ts

@@ -30,13 +30,13 @@ export declare const learnSchema: z.ZodObject<{
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
+    filePath?: string | undefined;
+    lineRange?: [number, number] | undefined;
     relates?: {
         type: "depends_on" | "contradicts" | "supports" | "refines" | "supersedes" | "similar_to" | "located_in" | "violates" | "addresses" | "detected_by" | "invoked_by";
         targetId: string;
         reasoning?: string | undefined;
     }[] | undefined;
-    filePath?: string | undefined;
-    lineRange?: [number, number] | undefined;
     effort?: string | undefined;
     impact?: string | undefined;
     violatedBy?: string[] | undefined;
@@ -46,13 +46,13 @@ export declare const learnSchema: z.ZodObject<{
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     severity?: "critical" | "high" | "medium" | "low" | undefined;
+    filePath?: string | undefined;
+    lineRange?: [number, number] | undefined;
     relates?: {
         type: "depends_on" | "contradicts" | "supports" | "refines" | "supersedes" | "similar_to" | "located_in" | "violates" | "addresses" | "detected_by" | "invoked_by";
         targetId: string;
         reasoning?: string | undefined;
     }[] | undefined;
-    filePath?: string | undefined;
-    lineRange?: [number, number] | undefined;
     effort?: string | undefined;
     impact?: string | undefined;
     violatedBy?: string[] | undefined;

package/dist/tools/learn.js

@@ -5,7 +5,7 @@ export const learnSchema = z.object({
     type: z.enum(NODE_TYPES).describe('Node type'),
     projectId: z.string().optional(),
     filePath: z.string().optional().describe('For code_facts'),
-    lineRange: z.tuple([z.number(), z.number()]).optional().describe('Line range [start, end]'),
+    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'),
     effort: z.string().optional().describe('Estimated fix effort'),
     impact: z.string().optional().describe('What breaks if unfixed'),

package/dist/tools/recall.d.ts

@@ -5,7 +5,7 @@ export declare const recallSchema: z.ZodObject<{
     type: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["thought", "decision", "insight", "code_fact", "assumption", "detection", "tech_debt", "principle", "pattern", "skill_result", "research"]>, z.ZodArray<z.ZodEnum<["thought", "decision", "insight", "code_fact", "assumption", "detection", "tech_debt", "principle", "pattern", "skill_result", "research"]>, "many">]>>;
     sessionId: z.ZodOptional<z.ZodString>;
     projectId: z.ZodOptional<z.ZodString>;
-    crossProject: z.ZodOptional<z.ZodBoolean>;
+    crossProject: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
     relatedTo: z.ZodOptional<z.ZodString>;
     edgeType: z.ZodOptional<z.ZodUnion<[z.ZodEnum<["depends_on", "contradicts", "supports", "refines", "supersedes", "similar_to", "located_in", "violates", "addresses", "detected_by", "invoked_by"]>, z.ZodArray<z.ZodEnum<["depends_on", "contradicts", "supports", "refines", "supersedes", "similar_to", "located_in", "violates", "addresses", "detected_by", "invoked_by"]>, "many">]>>;
     direction: z.ZodOptional<z.ZodEnum<["outgoing", "incoming", "both"]>>;
@@ -34,7 +34,7 @@ export declare const recallSchema: z.ZodObject<{
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     query?: string | undefined;
-    crossProject?: boolean | undefined;
+    crossProject?: unknown;
     relatedTo?: string | undefined;
     edgeType?: "depends_on" | "contradicts" | "supports" | "refines" | "supersedes" | "similar_to" | "located_in" | "violates" | "addresses" | "detected_by" | "invoked_by" | ("depends_on" | "contradicts" | "supports" | "refines" | "supersedes" | "similar_to" | "located_in" | "violates" | "addresses" | "detected_by" | "invoked_by")[] | undefined;
     direction?: "outgoing" | "incoming" | "both" | undefined;

package/dist/tools/recall.js

@@ -1,19 +1,20 @@
 import { z } from 'zod';
 import { NODE_TYPES, EDGE_TYPES } from '../engine/types.js';
+const coerceBool = z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean());
 export const recallSchema = z.object({
     query: z.string().optional().describe('Full-text search'),
     type: z.union([z.enum(NODE_TYPES), z.array(z.enum(NODE_TYPES))]).optional(),
     sessionId: z.string().optional(),
     projectId: z.string().optional(),
-    crossProject: z.boolean().optional().describe('Search across all projects'),
+    crossProject: coerceBool.optional().describe('Search across all projects'),
     relatedTo: z.string().optional().describe('Find nodes connected to this ID'),
     edgeType: z.union([z.enum(EDGE_TYPES), z.array(z.enum(EDGE_TYPES))]).optional(),
     direction: z.enum(['outgoing', 'incoming', 'both']).optional(),
-    depth: z.number().int().min(1).optional().describe('Traversal depth'),
+    depth: z.coerce.number().int().min(1).optional().describe('Traversal depth'),
     since: z.string().optional().describe('ISO timestamp'),
     metadata: z.record(z.unknown()).optional(),
-    limit: z.number().int().min(1).max(100).optional(),
-    offset: z.number().int().min(0).optional(),
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+    offset: z.coerce.number().int().min(0).optional(),
 });
 export async function recallHandler(graph, input) {
     // If relatedTo is specified, use graph traversal

package/dist/tools/relate.d.ts

@@ -6,7 +6,7 @@ export declare const relateSchema: z.ZodObject<{
     type: z.ZodEnum<["depends_on", "contradicts", "supports", "refines", "supersedes", "similar_to", "located_in", "violates", "addresses", "detected_by", "invoked_by"]>;
     weight: z.ZodOptional<z.ZodNumber>;
     reasoning: z.ZodOptional<z.ZodString>;
-    bidirectional: z.ZodOptional<z.ZodBoolean>;
+    bidirectional: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
 }, "strip", z.ZodTypeAny, {
     type: "depends_on" | "contradicts" | "supports" | "refines" | "supersedes" | "similar_to" | "located_in" | "violates" | "addresses" | "detected_by" | "invoked_by";
     sourceId: string;
@@ -20,7 +20,7 @@ export declare const relateSchema: z.ZodObject<{
     targetId: string;
     weight?: number | undefined;
     reasoning?: string | undefined;
-    bidirectional?: boolean | undefined;
+    bidirectional?: unknown;
 }>;
 export type RelateInput = z.infer<typeof relateSchema>;
 export declare function relateHandler(graph: ThinkingGraph, input: RelateInput): Promise<{

package/dist/tools/relate.js

@@ -1,12 +1,13 @@
 import { z } from 'zod';
 import { EDGE_TYPES } from '../engine/types.js';
+const coerceBool = z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean());
 export const relateSchema = z.object({
     sourceId: z.string().describe('Node ID (prefix with "?" for content search)'),
     targetId: z.string().describe('Node ID, content search, or principle name'),
     type: z.enum(EDGE_TYPES).describe('Relationship type'),
-    weight: z.number().min(0).max(1).optional().describe('Confidence 0-1'),
+    weight: z.coerce.number().min(0).max(1).optional().describe('Confidence 0-1'),
     reasoning: z.string().optional().describe('Why this relationship exists'),
-    bidirectional: z.boolean().optional().describe('Create reverse edge too'),
+    bidirectional: coerceBool.optional().describe('Create reverse edge too'),
 });
 async function resolveId(graph, id) {
     if (id.startsWith('?')) {

package/dist/tools/research.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import type { ThinkingGraph } from '../engine/graph.js';
+export declare const researchSchema: z.ZodObject<{
+    query: z.ZodString;
+    intent: z.ZodDefault<z.ZodEnum<["fact_check", "explore", "compare", "how_to", "current_state"]>>;
+    context: z.ZodOptional<z.ZodString>;
+    researchId: z.ZodOptional<z.ZodString>;
+    findings: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        content: z.ZodString;
+        source: z.ZodOptional<z.ZodString>;
+        confidence: z.ZodOptional<z.ZodEnum<["high", "medium", "low"]>>;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        source?: string | undefined;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }, {
+        content: string;
+        source?: string | undefined;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }>, "many">>;
+    projectId: z.ZodOptional<z.ZodString>;
+    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">>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    intent: "fact_check" | "explore" | "compare" | "how_to" | "current_state";
+    projectId?: string | undefined;
+    context?: string | undefined;
+    researchId?: string | undefined;
+    findings?: {
+        content: string;
+        source?: string | undefined;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }[] | undefined;
+    scrapeUrls?: string[] | undefined;
+    recencyFilter?: "hour" | "day" | "week" | "month" | "year" | undefined;
+    domainFilter?: string[] | undefined;
+}, {
+    query: string;
+    projectId?: string | undefined;
+    intent?: "fact_check" | "explore" | "compare" | "how_to" | "current_state" | undefined;
+    context?: string | undefined;
+    researchId?: string | undefined;
+    findings?: {
+        content: string;
+        source?: string | undefined;
+        confidence?: "high" | "medium" | "low" | undefined;
+    }[] | undefined;
+    scrapeUrls?: string[] | undefined;
+    recencyFilter?: "hour" | "day" | "week" | "month" | "year" | undefined;
+    domainFilter?: string[] | undefined;
+}>;
+export type ResearchInput = z.infer<typeof researchSchema>;
+export declare function researchHandler(graph: ThinkingGraph, input: ResearchInput): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/tools/research.js

@@ -0,0 +1,236 @@
+import { z } from 'zod';
+const coerceBool = z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean());
+const RESEARCH_INTENTS = [
+    'fact_check', // Verify a claim or assumption
+    'explore', // Open-ended exploration of a topic
+    'compare', // Compare options, libraries, approaches
+    'how_to', // Find implementation guidance
+    'current_state', // Get current state of something (version, status, etc.)
+];
+const findingSchema = z.object({
+    content: z.string().describe('What was found'),
+    source: z.string().optional().describe('URL or citation'),
+    confidence: z.enum(['high', 'medium', 'low']).optional(),
+});
+export const researchSchema = z.object({
+    // Phase 1: initiate research
+    query: z.string().describe('What to research'),
+    intent: z.enum(RESEARCH_INTENTS).default('explore').describe('Research intent — guides tool selection'),
+    context: z.string().optional().describe('Why this research matters to the current task'),
+    // Phase 2: ingest findings (provide researchId from phase 1)
+    researchId: z.string().optional().describe('Node ID from phase 1 — triggers ingestion mode'),
+    findings: z.array(findingSchema).optional().describe('Results to store (phase 2)'),
+    // Options
+    projectId: z.string().optional(),
+    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'),
+});
+function buildActionPlan(input) {
+    const steps = [];
+    const query = input.query;
+    // Choose Perplexity tool based on intent
+    switch (input.intent) {
+        case 'fact_check':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_ask',
+                description: 'Quick fact check with citations',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    search_context_size: 'medium',
+                    ...(input.recencyFilter && { search_recency_filter: input.recencyFilter }),
+                    ...(input.domainFilter && { search_domain_filter: input.domainFilter }),
+                },
+            });
+            break;
+        case 'compare':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_reason',
+                description: 'Step-by-step comparison with web grounding',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    search_context_size: 'high',
+                    ...(input.recencyFilter && { search_recency_filter: input.recencyFilter }),
+                    ...(input.domainFilter && { search_domain_filter: input.domainFilter }),
+                },
+            });
+            break;
+        case 'explore':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_research',
+                description: 'Deep multi-source research (30s+)',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    reasoning_effort: 'medium',
+                },
+            });
+            break;
+        case 'how_to':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_ask',
+                description: 'Find implementation guidance',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    search_context_size: 'high',
+                    ...(input.recencyFilter && { search_recency_filter: input.recencyFilter }),
+                    ...(input.domainFilter && { search_domain_filter: input.domainFilter }),
+                },
+            });
+            break;
+        case 'current_state':
+            steps.push({
+                tool: 'mcp__perplexity__perplexity_ask',
+                description: 'Get current state with recency filter',
+                args: {
+                    messages: [{ role: 'user', content: query }],
+                    search_recency_filter: input.recencyFilter ?? 'week',
+                    search_context_size: 'medium',
+                    ...(input.domainFilter && { search_domain_filter: input.domainFilter }),
+                },
+            });
+            break;
+    }
+    // If specific URLs provided, add Firecrawl scrape steps
+    if (input.scrapeUrls?.length) {
+        for (const url of input.scrapeUrls) {
+            steps.push({
+                tool: 'mcp__firecrawl__firecrawl_scrape',
+                description: `Scrape ${url}`,
+                args: {
+                    url,
+                    formats: ['markdown'],
+                    onlyMainContent: true,
+                },
+            });
+        }
+    }
+    // For explore/compare, also suggest a Firecrawl search for additional sources
+    if (input.intent === 'explore' || input.intent === 'compare') {
+        steps.push({
+            tool: 'mcp__firecrawl__firecrawl_search',
+            description: 'Search for additional sources',
+            args: {
+                query,
+                limit: 5,
+                sources: [{ type: 'web' }],
+            },
+        });
+    }
+    return steps;
+}
+export async function researchHandler(graph, input) {
+    // ── Phase 2: ingest findings ──────────────────────────
+    if (input.researchId && input.findings?.length) {
+        const researchNode = await graph.getNode(input.researchId);
+        if (!researchNode) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: `Research node ${input.researchId} not found` }),
+                    }],
+            };
+        }
+        const session = await graph.getCurrentSession();
+        const storedNodes = [];
+        for (const finding of input.findings) {
+            // Check for duplicates
+            const existing = await graph.findSimilar(finding.content, 'research', input.projectId);
+            if (existing) {
+                storedNodes.push(existing.id);
+                continue;
+            }
+            const node = await graph.addNode({
+                type: 'research',
+                content: finding.content,
+                sessionId: session.id,
+                projectId: input.projectId,
+                metadata: {
+                    source: finding.source,
+                    confidence: finding.confidence,
+                    researchQuery: researchNode.content,
+                },
+            });
+            // Relate finding back to the research query node
+            await graph.addEdge({
+                sourceId: node.id,
+                targetId: input.researchId,
+                type: 'supports',
+                reasoning: 'Finding from research query',
+            });
+            storedNodes.push(node.id);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        phase: 'ingest',
+                        researchId: input.researchId,
+                        storedCount: storedNodes.length,
+                        nodeIds: storedNodes,
+                        suggestions: [
+                            {
+                                tool: 'relate',
+                                when: 'Connect these findings to the thoughts/decisions they inform',
+                                example: {
+                                    sourceId: '<thought nodeId>',
+                                    targetId: storedNodes[0] ?? '<finding nodeId>',
+                                    type: 'depends_on',
+                                    reasoning: 'Decision informed by research',
+                                },
+                            },
+                            {
+                                tool: 'learn',
+                                when: 'Promote a key finding to a durable insight that persists cross-project',
+                                example: {
+                                    content: '<key takeaway>',
+                                    type: 'insight',
+                                    relates: [{ type: 'refines', targetId: input.researchId }],
+                                },
+                            },
+                        ],
+                    }),
+                }],
+        };
+    }
+    // ── Phase 1: initiate research ────────────────────────
+    const session = await graph.getCurrentSession();
+    const node = await graph.addNode({
+        type: 'research',
+        content: input.query,
+        sessionId: session.id,
+        projectId: input.projectId,
+        metadata: {
+            intent: input.intent,
+            context: input.context,
+            status: 'pending',
+        },
+    });
+    const actionPlan = buildActionPlan(input);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify({
+                    phase: 'initiate',
+                    researchId: node.id,
+                    query: input.query,
+                    intent: input.intent,
+                    actionPlan,
+                    ingestStep: {
+                        tool: 'research',
+                        description: 'After executing the action plan, pipe findings back here',
+                        args: {
+                            query: input.query,
+                            researchId: node.id,
+                            findings: [
+                                {
+                                    content: '<summarize what you found>',
+                                    source: '<url or citation>',
+                                    confidence: 'high',
+                                },
+                            ],
+                        },
+                    },
+                }),
+            }],
+    };
+}

package/dist/tools/think.d.ts

@@ -5,7 +5,7 @@ export declare const thinkSchema: z.ZodObject<{
     type: z.ZodDefault<z.ZodEnum<["thought", "decision", "insight", "code_fact", "assumption", "detection", "tech_debt", "principle", "pattern", "skill_result", "research"]>>;
     thoughtNumber: z.ZodNumber;
     totalThoughts: z.ZodNumber;
-    nextThoughtNeeded: z.ZodBoolean;
+    nextThoughtNeeded: z.ZodEffects<z.ZodBoolean, boolean, unknown>;
     sessionId: z.ZodOptional<z.ZodString>;
     projectId: z.ZodOptional<z.ZodString>;
     relates: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -22,11 +22,11 @@ export declare const thinkSchema: z.ZodObject<{
         reasoning?: string | undefined;
     }>, "many">>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    isRevision: z.ZodOptional<z.ZodBoolean>;
+    isRevision: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
     revisesThought: z.ZodOptional<z.ZodNumber>;
     branchFromThought: z.ZodOptional<z.ZodNumber>;
     branchId: z.ZodOptional<z.ZodString>;
-    needsMoreThoughts: z.ZodOptional<z.ZodBoolean>;
+    needsMoreThoughts: z.ZodOptional<z.ZodEffects<z.ZodBoolean, boolean, unknown>>;
 }, "strip", z.ZodTypeAny, {
     thought: string;
     type: "thought" | "decision" | "insight" | "code_fact" | "assumption" | "detection" | "tech_debt" | "principle" | "pattern" | "skill_result" | "research";
@@ -50,21 +50,21 @@ export declare const thinkSchema: z.ZodObject<{
     thought: string;
     thoughtNumber: number;
     totalThoughts: number;
-    nextThoughtNeeded: boolean;
     type?: "thought" | "decision" | "insight" | "code_fact" | "assumption" | "detection" | "tech_debt" | "principle" | "pattern" | "skill_result" | "research" | undefined;
     sessionId?: string | undefined;
     projectId?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     branchId?: string | undefined;
-    isRevision?: boolean | undefined;
+    isRevision?: unknown;
     revisesThought?: number | undefined;
+    nextThoughtNeeded?: unknown;
     relates?: {
         type: "depends_on" | "contradicts" | "supports" | "refines" | "supersedes" | "similar_to" | "located_in" | "violates" | "addresses" | "detected_by" | "invoked_by";
         targetId: string;
         reasoning?: string | undefined;
     }[] | undefined;
     branchFromThought?: number | undefined;
-    needsMoreThoughts?: boolean | undefined;
+    needsMoreThoughts?: unknown;
 }>;
 export type ThinkInput = z.infer<typeof thinkSchema>;
 export declare function thinkHandler(graph: ThinkingGraph, input: ThinkInput): Promise<{

package/dist/tools/think.js

@@ -1,11 +1,85 @@
 import { z } from 'zod';
-import { NODE_TYPES, EDGE_TYPES } from '../engine/types.js';
+import { NODE_TYPES, EDGE_TYPES, GLOBAL_NODE_TYPES } from '../engine/types.js';
+const coerceBool = z.preprocess((v) => (v === 'true' ? true : v === 'false' ? false : v), z.boolean());
+function buildSuggestions(type, thoughtNumber, relatedCount, stats) {
+    const suggestions = [];
+    // First thought in session — suggest recall to check prior knowledge
+    if (thoughtNumber === 1 && stats.totalNodes > 1) {
+        suggestions.push({
+            tool: 'recall',
+            when: 'Check what the graph already knows before reasoning from scratch',
+            example: { query: '<topic>', crossProject: true },
+        });
+    }
+    // Decision nodes with no relationships — suggest relate
+    if (type === 'decision' && relatedCount === 0) {
+        suggestions.push({
+            tool: 'relate',
+            when: 'Connect this decision to what it depends on or what it supersedes',
+            example: { sourceId: '<this nodeId>', targetId: '?<search term>', type: 'depends_on' },
+        });
+    }
+    // Assumption nodes — suggest relate and research to verify
+    if (type === 'assumption') {
+        suggestions.push({
+            tool: 'relate',
+            when: 'Link this assumption to the decision or design it supports',
+            example: { sourceId: '<this nodeId>', targetId: '?<decision>', type: 'supports' },
+        });
+        suggestions.push({
+            tool: 'research',
+            when: 'Verify this assumption with external sources before building on it',
+            example: { query: '<the assumption to verify>', intent: 'fact_check' },
+        });
+    }
+    // Detection or tech_debt — suggest relate to violated principle
+    if (type === 'detection' || type === 'tech_debt') {
+        suggestions.push({
+            tool: 'relate',
+            when: 'Link to the principle this violates (pre-seeded: SRP, DRY, YAGNI, etc.)',
+            example: { sourceId: '<this nodeId>', targetId: '?<principle name>', type: 'violates' },
+        });
+    }
+    // Insight, pattern, or principle — suggest learn to persist cross-project
+    if (GLOBAL_NODE_TYPES.includes(type)) {
+        suggestions.push({
+            tool: 'learn',
+            when: 'Persist this so it carries across sessions and projects',
+            example: { content: '<the insight>', type },
+        });
+    }
+    // Code fact — suggest learn with file metadata
+    if (type === 'code_fact') {
+        suggestions.push({
+            tool: 'learn',
+            when: 'Store this code fact with its file location for future recall',
+            example: { content: '<fact>', type: 'code_fact', filePath: '<path>', lineRange: [0, 0] },
+        });
+    }
+    // Research node via think — redirect to the full research tool
+    if (type === 'research') {
+        suggestions.push({
+            tool: 'research',
+            when: 'Use the research tool instead — it generates an action plan with Perplexity/Firecrawl calls and handles ingestion',
+            example: { query: '<what to research>', intent: 'explore' },
+        });
+    }
+    // Generic: if the node has no relationships and there are other nodes, nudge relate
+    if (relatedCount === 0 && stats.totalNodes > 2 && type === 'thought') {
+        suggestions.push({
+            tool: 'relate',
+            when: 'Connect this thought to related nodes (use "?<search>" to find by content)',
+            example: { sourceId: '<this nodeId>', targetId: '?<search term>', type: 'supports' },
+        });
+    }
+    return suggestions;
+}
 export const thinkSchema = z.object({
     thought: z.string().describe('The reasoning content'),
     type: z.enum(NODE_TYPES).default('thought').describe('Node type'),
-    thoughtNumber: z.number().int().min(1).describe('Current thought number'),
-    totalThoughts: z.number().int().min(1).describe('Estimated total thoughts'),
-    nextThoughtNeeded: z.boolean().describe('Whether another step is needed'),
+    thoughtNumber: z.coerce.number().int().min(1).describe('Current thought number'),
+    totalThoughts: z.coerce.number().int().min(1).describe('Estimated total thoughts'),
+    nextThoughtNeeded: coerceBool.describe('Whether another step is needed'),
     sessionId: z.string().optional().describe('Session ID (auto-generated if omitted)'),
     projectId: z.string().optional().describe('Project ID (detected from cwd if omitted)'),
     relates: z.array(z.object({
@@ -15,11 +89,11 @@ export const thinkSchema = z.object({
     })).optional().describe('Inline relationships'),
     metadata: z.record(z.unknown()).optional().describe('Flexible metadata'),
     // Backward compat
-    isRevision: z.boolean().optional(),
-    revisesThought: z.number().int().min(1).optional(),
-    branchFromThought: z.number().int().min(1).optional(),
+    isRevision: coerceBool.optional(),
+    revisesThought: z.coerce.number().int().min(1).optional(),
+    branchFromThought: z.coerce.number().int().min(1).optional(),
     branchId: z.string().optional(),
-    needsMoreThoughts: z.boolean().optional(),
+    needsMoreThoughts: coerceBool.optional(),
 });
 export async function thinkHandler(graph, input) {
     const session = input.sessionId
@@ -52,6 +126,7 @@ export async function thinkHandler(graph, input) {
         }
     }
     const stats = await graph.storage.getStats();
+    const suggestions = buildSuggestions(input.type ?? 'thought', input.thoughtNumber, relatedCount, stats);
     return {
         content: [{
                 type: 'text',
@@ -63,6 +138,7 @@ export async function thinkHandler(graph, input) {
                     branches: [],
                     thoughtHistoryLength: stats.totalNodes,
                     relatedNodes: relatedCount,
+                    ...(suggestions.length > 0 && { suggestions }),
                 }),
             }],
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelingmindful/thinking-graph",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Persistent graph-based MCP thinking server for the feeling-mindful plugin marketplace",
   "type": "module",
   "main": "dist/index.js",

package/seeds/skill-registry.json

@@ -90,74 +90,74 @@
     "produces": [], "invokes": ["premium-android:research", "premium-android:init", "premium-android:configure", "premium-android:refactor", "premium-android:create", "premium-core:growth", "premium-core:humanize", "premium-android:audit"], "platform": "android"
   },
   {
-    "id": "nextjs-research", "pluginName": "premium-nextjs", "skillName": "research", "verb": "research",
-    "invocation": "/premium-nextjs:research", "areas": [], "detects": [],
+    "id": "nextjs-research", "pluginName": "premium-web", "skillName": "nextjs", "verb": "research",
+    "invocation": "/premium-web:nextjs", "areas": [], "detects": [],
     "produces": ["research"], "invokes": ["premium-core:research"], "platform": "nextjs"
   },
   {
-    "id": "nextjs-init", "pluginName": "premium-nextjs", "skillName": "init", "verb": "init",
-    "invocation": "/premium-nextjs:init", "areas": ["infra", "design-tokens", "monetization", "observability"], "detects": ["missing"],
+    "id": "nextjs-init", "pluginName": "premium-web", "skillName": "nextjs", "verb": "init",
+    "invocation": "/premium-web:nextjs", "areas": ["infra", "design-tokens", "monetization", "observability"], "detects": ["missing"],
     "produces": ["code_fact", "decision"], "invokes": [], "platform": "nextjs"
   },
   {
-    "id": "nextjs-configure", "pluginName": "premium-nextjs", "skillName": "configure", "verb": "configure",
-    "invocation": "/premium-nextjs:configure", "areas": ["infra", "security", "observability"], "detects": ["needs-work"],
+    "id": "nextjs-configure", "pluginName": "premium-web", "skillName": "nextjs", "verb": "configure",
+    "invocation": "/premium-web:nextjs", "areas": ["infra", "security", "observability"], "detects": ["needs-work"],
     "produces": ["code_fact"], "invokes": [], "platform": "nextjs"
   },
   {
-    "id": "nextjs-refactor", "pluginName": "premium-nextjs", "skillName": "refactor", "verb": "refactor",
-    "invocation": "/premium-nextjs:refactor", "areas": ["architecture", "design-tokens", "icons", "copy"], "detects": ["needs-work"],
+    "id": "nextjs-refactor", "pluginName": "premium-web", "skillName": "nextjs", "verb": "refactor",
+    "invocation": "/premium-web:nextjs", "areas": ["architecture", "design-tokens", "icons", "copy"], "detects": ["needs-work"],
     "produces": ["tech_debt", "code_fact", "decision"], "invokes": ["premium-core:humanize"], "platform": "nextjs"
   },
   {
-    "id": "nextjs-create", "pluginName": "premium-nextjs", "skillName": "create", "verb": "create",
-    "invocation": "/premium-nextjs:create", "areas": ["design-tokens", "animations", "typography", "icons", "monetization"], "detects": ["missing"],
+    "id": "nextjs-create", "pluginName": "premium-web", "skillName": "nextjs", "verb": "create",
+    "invocation": "/premium-web:nextjs", "areas": ["design-tokens", "animations", "typography", "icons", "monetization"], "detects": ["missing"],
     "produces": ["code_fact", "decision"], "invokes": [], "platform": "nextjs"
   },
   {
-    "id": "nextjs-audit", "pluginName": "premium-nextjs", "skillName": "audit", "verb": "audit",
-    "invocation": "/premium-nextjs:audit", "areas": ["architecture", "design-tokens", "typography", "icons", "copy", "monetization", "security", "observability", "seo"], "detects": ["missing", "needs-work", "good"],
+    "id": "nextjs-audit", "pluginName": "premium-web", "skillName": "nextjs", "verb": "audit",
+    "invocation": "/premium-web:nextjs", "areas": ["architecture", "design-tokens", "typography", "icons", "copy", "monetization", "security", "observability", "seo"], "detects": ["missing", "needs-work", "good"],
     "produces": ["detection", "tech_debt"], "invokes": ["premium-core:audit"], "platform": "nextjs"
   },
   {
-    "id": "nextjs-full", "pluginName": "premium-nextjs", "skillName": "full", "verb": "full",
-    "invocation": "/premium-nextjs:full", "areas": [], "detects": [],
-    "produces": [], "invokes": ["premium-nextjs:research", "premium-nextjs:init", "premium-nextjs:configure", "premium-nextjs:refactor", "premium-nextjs:create", "premium-core:growth", "premium-core:humanize", "premium-nextjs:audit"], "platform": "nextjs"
+    "id": "nextjs-full", "pluginName": "premium-web", "skillName": "nextjs", "verb": "full",
+    "invocation": "/premium-web:nextjs", "areas": [], "detects": [],
+    "produces": [], "invokes": ["premium-web:nextjs", "premium-core:growth", "premium-core:humanize"], "platform": "nextjs"
   },
   {
-    "id": "astro-research", "pluginName": "premium-astro", "skillName": "research", "verb": "research",
-    "invocation": "/premium-astro:research", "areas": [], "detects": [],
+    "id": "astro-research", "pluginName": "premium-web", "skillName": "astro", "verb": "research",
+    "invocation": "/premium-web:astro", "areas": [], "detects": [],
     "produces": ["research"], "invokes": ["premium-core:research"], "platform": "astro"
   },
   {
-    "id": "astro-init", "pluginName": "premium-astro", "skillName": "init", "verb": "init",
-    "invocation": "/premium-astro:init", "areas": ["infra", "design-tokens", "monetization", "observability"], "detects": ["missing"],
+    "id": "astro-init", "pluginName": "premium-web", "skillName": "astro", "verb": "init",
+    "invocation": "/premium-web:astro", "areas": ["infra", "design-tokens", "monetization", "observability"], "detects": ["missing"],
     "produces": ["code_fact", "decision"], "invokes": [], "platform": "astro"
   },
   {
-    "id": "astro-configure", "pluginName": "premium-astro", "skillName": "configure", "verb": "configure",
-    "invocation": "/premium-astro:configure", "areas": ["infra", "security", "observability"], "detects": ["needs-work"],
+    "id": "astro-configure", "pluginName": "premium-web", "skillName": "astro", "verb": "configure",
+    "invocation": "/premium-web:astro", "areas": ["infra", "security", "observability"], "detects": ["needs-work"],
     "produces": ["code_fact"], "invokes": [], "platform": "astro"
   },
   {
-    "id": "astro-refactor", "pluginName": "premium-astro", "skillName": "refactor", "verb": "refactor",
-    "invocation": "/premium-astro:refactor", "areas": ["architecture", "design-tokens", "islands-hydration", "copy"], "detects": ["needs-work"],
+    "id": "astro-refactor", "pluginName": "premium-web", "skillName": "astro", "verb": "refactor",
+    "invocation": "/premium-web:astro", "areas": ["architecture", "design-tokens", "islands-hydration", "copy"], "detects": ["needs-work"],
     "produces": ["tech_debt", "code_fact", "decision"], "invokes": ["premium-core:humanize"], "platform": "astro"
   },
   {
-    "id": "astro-create", "pluginName": "premium-astro", "skillName": "create", "verb": "create",
-    "invocation": "/premium-astro:create", "areas": ["design-tokens", "animations", "typography", "icons", "monetization"], "detects": ["missing"],
+    "id": "astro-create", "pluginName": "premium-web", "skillName": "astro", "verb": "create",
+    "invocation": "/premium-web:astro", "areas": ["design-tokens", "animations", "typography", "icons", "monetization"], "detects": ["missing"],
     "produces": ["code_fact", "decision"], "invokes": [], "platform": "astro"
   },
   {
-    "id": "astro-audit", "pluginName": "premium-astro", "skillName": "audit", "verb": "audit",
-    "invocation": "/premium-astro:audit", "areas": ["architecture", "design-tokens", "islands-hydration", "content-collections", "copy", "monetization", "security", "observability", "seo"], "detects": ["missing", "needs-work", "good"],
+    "id": "astro-audit", "pluginName": "premium-web", "skillName": "astro", "verb": "audit",
+    "invocation": "/premium-web:astro", "areas": ["architecture", "design-tokens", "islands-hydration", "content-collections", "copy", "monetization", "security", "observability", "seo"], "detects": ["missing", "needs-work", "good"],
     "produces": ["detection", "tech_debt"], "invokes": ["premium-core:audit"], "platform": "astro"
   },
   {
-    "id": "astro-full", "pluginName": "premium-astro", "skillName": "full", "verb": "full",
-    "invocation": "/premium-astro:full", "areas": [], "detects": [],
-    "produces": [], "invokes": ["premium-astro:research", "premium-astro:init", "premium-astro:configure", "premium-astro:refactor", "premium-astro:create", "premium-core:growth", "premium-core:humanize", "premium-astro:audit"], "platform": "astro"
+    "id": "astro-full", "pluginName": "premium-web", "skillName": "astro", "verb": "full",
+    "invocation": "/premium-web:astro", "areas": [], "detects": [],
+    "produces": [], "invokes": ["premium-web:astro", "premium-core:growth", "premium-core:humanize"], "platform": "astro"
   },
   {
     "id": "marketing-product-context", "pluginName": "marketing-skills", "skillName": "product-marketing-context", "verb": "context",