@grafema/mcp 0.2.11 → 0.3.0-beta

package/dist/definitions/graphql-tools.js

@@ -0,0 +1,62 @@
+/**
+ * GraphQL Tool — execute GraphQL queries on the code graph
+ */
+export const GRAPHQL_TOOLS = [
+    {
+        name: 'query_graphql',
+        description: `Execute a GraphQL query on the code graph.
+
+GraphQL provides typed, nested queries with pagination — complementary to Datalog.
+Use GraphQL when you need nested data in one query (node + edges + neighbors).
+Use Datalog (query_graph) for pattern matching and logical rules.
+
+SCHEMA HIGHLIGHTS:
+- node(id: ID!): Node — get a single node
+- nodes(filter: {type, name, file, exported}, first, after): NodeConnection — paginated search
+- bfs/dfs(startIds, maxDepth, edgeTypes): [ID!]! — graph traversal
+- reachability(from, to, edgeTypes, maxDepth): Boolean — path existence
+- datalog(query, limit, offset): DatalogResult — Datalog passthrough
+- findCalls(target, className): [CallInfo!]! — call graph
+- traceDataFlow(source, file, direction, maxDepth): [[String!]!]! — data flow
+- stats: GraphStats — node/edge counts
+
+Node fields: id, name, type, file, line, column, exported, metadata,
+  outgoingEdges(types), incomingEdges(types), children, parent
+
+EXAMPLE:
+  query {
+    nodes(filter: {type: "FUNCTION", file: "src/api"}, first: 5) {
+      edges {
+        node {
+          name, file, line
+          outgoingEdges(types: ["CALLS"]) {
+            edges { node { dst { name, file } } }
+          }
+        }
+      }
+      totalCount
+    }
+  }
+
+Use get_documentation(topic="graphql-schema") for the full schema.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'GraphQL query string',
+                },
+                variables: {
+                    type: 'object',
+                    description: 'Optional variables for the query (JSON object)',
+                },
+                operationName: {
+                    type: 'string',
+                    description: 'Optional operation name (when query contains multiple operations)',
+                },
+            },
+            required: ['query'],
+        },
+    },
+];
+//# sourceMappingURL=graphql-tools.js.map

package/dist/definitions/graphql-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphql-tools.js","sourceRoot":"","sources":["../../src/definitions/graphql-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,aAAa,GAAqB;IAC7C;QACE,IAAI,EAAE,eAAe;QACrB,WAAW,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mEAkCkD;QAC/D,WAAW,EAAE;YACX,IAAI,EAAE,QAAiB;YACvB,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,sBAAsB;iBACpC;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,gDAAgD;iBAC9D;gBACD,aAAa,EAAE;oBACb,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mEAAmE;iBACjF;aACF;YACD,QAAQ,EAAE,CAAC,OAAO,CAAC;SACpB;KACF;CACF,CAAC"}

package/dist/definitions/guarantee-tools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Guarantee Tools — creating, checking, and managing code guarantees
+ */
+import type { ToolDefinition } from './types.js';
+export declare const GUARANTEE_TOOLS: ToolDefinition[];
+//# sourceMappingURL=guarantee-tools.d.ts.map

package/dist/definitions/guarantee-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarantee-tools.d.ts","sourceRoot":"","sources":["../../src/definitions/guarantee-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,eAAe,EAAE,cAAc,EAmI3C,CAAC"}

package/dist/definitions/guarantee-tools.js

@@ -0,0 +1,136 @@
+/**
+ * Guarantee Tools — creating, checking, and managing code guarantees
+ */
+export const GUARANTEE_TOOLS = [
+    {
+        name: 'create_guarantee',
+        description: `Create a new code guarantee.
+
+Two types supported:
+1. Datalog-based: Uses rule field with Datalog query (violation/1)
+2. Contract-based: Uses type + schema for JSON validation
+
+Examples:
+- Datalog: name="no-eval" rule="violation(X) :- node(X, \"CALL\"), attr(X, \"name\", \"eval\")."
+- Contract: name="orders" type="guarantee:queue" priority="critical" schema={...}`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Unique name for the guarantee',
+                },
+                // Datalog-based fields
+                rule: {
+                    type: 'string',
+                    description: 'Datalog rule defining violation/1 (for Datalog-based guarantees)',
+                },
+                severity: {
+                    type: 'string',
+                    description: 'Severity for Datalog guarantees: error, warning, or info',
+                    enum: ['error', 'warning', 'info'],
+                },
+                // Contract-based fields
+                type: {
+                    type: 'string',
+                    description: 'Guarantee type for contract-based: guarantee:queue, guarantee:api, guarantee:permission',
+                    enum: ['guarantee:queue', 'guarantee:api', 'guarantee:permission'],
+                },
+                priority: {
+                    type: 'string',
+                    description: 'Priority level: critical, important, observed, tracked',
+                    enum: ['critical', 'important', 'observed', 'tracked'],
+                },
+                status: {
+                    type: 'string',
+                    description: 'Lifecycle status: discovered, reviewed, active, changing, deprecated',
+                    enum: ['discovered', 'reviewed', 'active', 'changing', 'deprecated'],
+                },
+                owner: {
+                    type: 'string',
+                    description: 'Owner of the guarantee (team or person)',
+                },
+                schema: {
+                    type: 'object',
+                    description: 'JSON Schema for contract-based validation',
+                },
+                condition: {
+                    type: 'string',
+                    description: 'Condition expression for the guarantee',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Human-readable description',
+                },
+                governs: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Node IDs that this guarantee governs',
+                },
+            },
+            required: ['name'],
+        },
+    },
+    {
+        name: 'list_guarantees',
+        description: `List all defined code guarantees (rules and contracts).
+
+Use this to:
+- See existing invariants: "What rules does this codebase enforce?"
+- Understand code contracts before modifying code
+- Find Datalog-based rules (e.g., "no-eval", "no-sql-injection")
+- List contract-based guarantees (queue schemas, API contracts)
+
+Returns for each guarantee: name, type, description, rule/schema, priority, status.
+Use BEFORE check_guarantees to see what will be validated.`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'check_guarantees',
+        description: `Validate code against defined guarantees and return violations.
+
+Use this to:
+- Find violations: Run all rules, get list of breaking code
+- Verify specific rule: check_guarantees(names=["no-eval"]) — test one guarantee
+- Pre-commit validation: Catch issues before code review
+- After code changes: Verify you didn't break existing rules
+
+Returns: Violations array with node IDs, file, line, rule name.
+Empty array = all guarantees pass.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                names: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'List of guarantee names to check (omit to check all)',
+                },
+            },
+        },
+    },
+    {
+        name: 'delete_guarantee',
+        description: `Delete a guarantee by name.
+
+Use this when:
+- A guarantee is no longer relevant to the codebase
+- Replacing a guarantee with a new version (delete old, create new)
+- Cleaning up experimental guarantees after testing
+
+This permanently removes the guarantee. Use list_guarantees first to verify the name.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Name of guarantee to delete',
+                },
+            },
+            required: ['name'],
+        },
+    },
+];
+//# sourceMappingURL=guarantee-tools.js.map

package/dist/definitions/guarantee-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarantee-tools.js","sourceRoot":"","sources":["../../src/definitions/guarantee-tools.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,CAAC,MAAM,eAAe,GAAqB;IAC/C;QACE,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE;;;;;;;;kFAQiE;QAC9E,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,+BAA+B;iBAC7C;gBACD,uBAAuB;gBACvB,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,kEAAkE;iBAChF;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0DAA0D;oBACvE,IAAI,EAAE,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC;iBACnC;gBACD,wBAAwB;gBACxB,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yFAAyF;oBACtG,IAAI,EAAE,CAAC,iBAAiB,EAAE,eAAe,EAAE,sBAAsB,CAAC;iBACnE;gBACD,QAAQ,EAAE;oBACR,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wDAAwD;oBACrE,IAAI,EAAE,CAAC,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,CAAC;iBACvD;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,sEAAsE;oBACnF,IAAI,EAAE,CAAC,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,CAAC;iBACrE;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,yCAAyC;iBACvD;gBACD,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,2CAA2C;iBACzD;gBACD,SAAS,EAAE;oBACT,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,wCAAwC;iBACtD;gBACD,WAAW,EAAE;oBACX,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4BAA4B;iBAC1C;gBACD,OAAO,EAAE;oBACP,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,sCAAsC;iBACpD;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF;IACD;QACE,IAAI,EAAE,iBAAiB;QACvB,WAAW,EAAE;;;;;;;;;2DAS0C;QACvD,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE;SACf;KACF;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE;;;;;;;;;mCASkB;QAC/B,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,KAAK,EAAE;oBACL,IAAI,EAAE,OAAO;oBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;oBACzB,WAAW,EAAE,sDAAsD;iBACpE;aACF;SACF;KACF;IACD;QACE,IAAI,EAAE,kBAAkB;QACxB,WAAW,EAAE;;;;;;;sFAOqE;QAClF,WAAW,EAAE;YACX,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,6BAA6B;iBAC3C;aACF;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC;SACnB;KACF;CACF,CAAC"}

package/dist/definitions/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * MCP Tool Definitions — combined re-export
+ */
+export type { ToolDefinition, SchemaProperty } from './types.js';
+import type { ToolDefinition } from './types.js';
+export declare const TOOLS: ToolDefinition[];
+//# sourceMappingURL=index.d.ts.map

package/dist/definitions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/definitions/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAWjD,eAAO,MAAM,KAAK,EAAE,cAAc,EAUjC,CAAC"}

package/dist/definitions/index.js

@@ -0,0 +1,24 @@
+/**
+ * MCP Tool Definitions — combined re-export
+ */
+import { QUERY_TOOLS } from './query-tools.js';
+import { ANALYSIS_TOOLS } from './analysis-tools.js';
+import { GUARANTEE_TOOLS } from './guarantee-tools.js';
+import { CONTEXT_TOOLS } from './context-tools.js';
+import { PROJECT_TOOLS } from './project-tools.js';
+import { GRAPH_TOOLS } from './graph-tools.js';
+import { KNOWLEDGE_TOOLS } from './knowledge-tools.js';
+import { NOTATION_TOOLS } from './notation-tools.js';
+import { GRAPHQL_TOOLS } from './graphql-tools.js';
+export const TOOLS = [
+    ...QUERY_TOOLS,
+    ...ANALYSIS_TOOLS,
+    ...GUARANTEE_TOOLS,
+    ...CONTEXT_TOOLS,
+    ...PROJECT_TOOLS,
+    ...GRAPH_TOOLS,
+    ...KNOWLEDGE_TOOLS,
+    ...NOTATION_TOOLS,
+    ...GRAPHQL_TOOLS,
+];
+//# sourceMappingURL=index.js.map

package/dist/definitions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definitions/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,MAAM,CAAC,MAAM,KAAK,GAAqB;IACrC,GAAG,WAAW;IACd,GAAG,cAAc;IACjB,GAAG,eAAe;IAClB,GAAG,aAAa;IAChB,GAAG,aAAa;IAChB,GAAG,WAAW;IACd,GAAG,eAAe;IAClB,GAAG,cAAc;IACjB,GAAG,aAAa;CACjB,CAAC"}

package/dist/definitions/knowledge-tools.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Knowledge Tools — managing the persistent knowledge layer
+ *
+ * Knowledge nodes (decisions, facts, sessions) are stored as git-tracked
+ * markdown files with YAML frontmatter. These tools provide CRUD operations
+ * on the in-memory KnowledgeBase index.
+ */
+import type { ToolDefinition } from './types.js';
+export declare const KNOWLEDGE_TOOLS: ToolDefinition[];
+//# sourceMappingURL=knowledge-tools.d.ts.map

package/dist/definitions/knowledge-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-tools.d.ts","sourceRoot":"","sources":["../../src/definitions/knowledge-tools.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,eAAe,EAAE,cAAc,EAmS3C,CAAC"}

package/dist/definitions/knowledge-tools.js

@@ -0,0 +1,300 @@
+/**
+ * Knowledge Tools — managing the persistent knowledge layer
+ *
+ * Knowledge nodes (decisions, facts, sessions) are stored as git-tracked
+ * markdown files with YAML frontmatter. These tools provide CRUD operations
+ * on the in-memory KnowledgeBase index.
+ */
+export const KNOWLEDGE_TOOLS = [
+    {
+        name: 'add_knowledge',
+        description: `Add a new knowledge node (decision, fact, session, etc.) to the knowledge base.
+
+Use this when you:
+- Make an architectural decision during a session → type: DECISION
+- Discover a fact about the codebase → type: FACT
+- Want to record a design session → type: SESSION
+- Need to track a commit, ticket, incident, or author → type: COMMIT/TICKET/INCIDENT/AUTHOR
+
+The node is persisted as a markdown file in the knowledge/ directory and tracked by git.
+ID format: kb:<type>:<slug> — generated from type + slug. Slug collision = error (likely a duplicate; use supersede_fact instead).
+
+Example: add_knowledge(type="DECISION", content="Use file-based storage for KB", slug="kb-file-based-storage", status="active", projections=["epistemic"])`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    description: 'Node type',
+                    enum: ['DECISION', 'FACT', 'SESSION', 'COMMIT', 'FILE_CHANGE', 'AUTHOR', 'TICKET', 'INCIDENT'],
+                },
+                content: {
+                    type: 'string',
+                    description: 'Markdown body content for the knowledge node',
+                },
+                slug: {
+                    type: 'string',
+                    description: 'URL-safe slug for the ID (auto-generated from content if omitted). Format: lowercase, hyphens, digits.',
+                },
+                subtype: {
+                    type: 'string',
+                    description: 'Subtype within the node type. FACT: domain, error, preference. DECISION: adr, runbook. Extensible — not restricted to these values.',
+                },
+                scope: {
+                    type: 'string',
+                    description: 'Scope of applicability for this knowledge node',
+                    enum: ['global', 'project', 'module'],
+                },
+                relates_to: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Semantic IDs of related nodes. Creates edges in edges.yaml.',
+                },
+                projections: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Projections this node belongs to (e.g., "epistemic", "temporal", "organizational")',
+                },
+                status: {
+                    type: 'string',
+                    description: 'Decision status (only for DECISION type)',
+                    enum: ['active', 'superseded', 'deprecated', 'proposed'],
+                },
+                confidence: {
+                    type: 'string',
+                    description: 'Confidence level (only for FACT type)',
+                    enum: ['high', 'medium', 'low'],
+                },
+                effective_from: {
+                    type: 'string',
+                    description: 'Date when decision took effect (YYYY-MM-DD, only for DECISION)',
+                },
+                applies_to: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Semantic addresses of code this applies to (only for DECISION)',
+                },
+                task_id: {
+                    type: 'string',
+                    description: 'Associated Linear task ID (only for SESSION)',
+                },
+            },
+            required: ['type', 'content'],
+        },
+    },
+    {
+        name: 'query_knowledge',
+        description: `Query knowledge nodes with filters.
+
+Use this to:
+- Find all decisions: query_knowledge(type="DECISION")
+- Search by keyword: query_knowledge(text="RFDB")
+- Find nodes in a projection: query_knowledge(projection="epistemic")
+- Find related nodes: query_knowledge(relates_to="kb:session:2026-03-06-design")
+- Combine filters: query_knowledge(type="FACT", text="auth")
+- Find facts about code that no longer exists: query_knowledge(include_dangling_only=true)
+
+Returns matching nodes with their full content, metadata, and code reference resolution status.
+Code references (relates_to, applies_to) are resolved against the current code graph — each ref shows [OK] or [DANGLING] status.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    description: 'Filter by node type',
+                    enum: ['DECISION', 'FACT', 'SESSION', 'COMMIT', 'FILE_CHANGE', 'AUTHOR', 'TICKET', 'INCIDENT'],
+                },
+                projection: {
+                    type: 'string',
+                    description: 'Filter by projection (e.g., "epistemic", "temporal")',
+                },
+                relates_to: {
+                    type: 'string',
+                    description: 'Filter by relates_to containing this semantic ID',
+                },
+                text: {
+                    type: 'string',
+                    description: 'Case-insensitive text search in body content',
+                },
+                include_dangling_only: {
+                    type: 'boolean',
+                    description: 'When true, return only nodes with code references that no longer resolve (dangling). Requires code graph to be analyzed.',
+                },
+            },
+        },
+    },
+    {
+        name: 'query_decisions',
+        description: `Query architectural decisions, optionally filtered by module or status.
+
+Use this to:
+- Find decisions affecting a module: query_decisions(module="packages/cli:CLI:MODULE")
+- Find all active decisions: query_decisions(status="active")
+- Find all decisions: query_decisions()
+
+Returns decisions with status, applies_to, and full content.
+Decisions are the core artifact type — they record WHY code is the way it is.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                module: {
+                    type: 'string',
+                    description: 'Semantic address to match against applies_to (string includes matching)',
+                },
+                status: {
+                    type: 'string',
+                    description: 'Filter by decision status',
+                    enum: ['active', 'superseded', 'deprecated', 'proposed'],
+                },
+            },
+        },
+    },
+    {
+        name: 'supersede_fact',
+        description: `Supersede an existing fact with a new version.
+
+Use this when:
+- A fact becomes outdated (e.g., library was upgraded, architecture changed)
+- You discover new information that replaces an existing fact
+- Correcting a previously recorded fact
+
+This creates a NEW fact and marks the OLD fact with superseded_by pointing to the new one.
+The old fact remains in the knowledge base for history.
+
+Example: supersede_fact(old_id="kb:fact:auth-uses-bcrypt", new_content="Auth now uses argon2 after migration in REG-500")`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                old_id: {
+                    type: 'string',
+                    description: 'Semantic ID of the fact to supersede (e.g., "kb:fact:auth-uses-bcrypt")',
+                },
+                new_content: {
+                    type: 'string',
+                    description: 'Markdown content for the new fact',
+                },
+                new_slug: {
+                    type: 'string',
+                    description: 'Optional slug for the new fact (auto-generated if omitted)',
+                },
+            },
+            required: ['old_id', 'new_content'],
+        },
+    },
+    {
+        name: 'get_knowledge_stats',
+        description: `Get statistics about the knowledge base.
+
+Use this to:
+- Check if knowledge base is loaded and has content
+- See counts by node type (DECISION, FACT, SESSION, etc.)
+- See counts by lifecycle (declared, derived, synced)
+- Identify dangling references in edges
+- See dangling code references (KB nodes pointing at code that no longer exists in the graph)
+
+Returns: total nodes, by-type counts, by-lifecycle counts, edge counts, dangling KB refs, dangling code refs.
+Code reference resolution requires the code graph to be analyzed — without it, danglingCodeRefs will be empty.`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    // Disabled: requires git-ingest (US-17). See US-17 in AI-AGENT-STORIES.md
+    // {
+    //   name: 'git_churn',
+    //   description: `Identify hot spots — files ranked by change frequency.
+    //
+    // Use this to:
+    // - Find which files change most often (high churn = high risk or high activity)
+    // - Prioritize code review effort based on change frequency
+    // - Identify files that may need refactoring (too many changes = unstable)
+    //
+    // Returns files sorted by change count, with total lines added/removed.
+    // Requires git history to be ingested first (grafema git-ingest).`,
+    //   inputSchema: {
+    //     type: 'object',
+    //     properties: {
+    //       limit: {
+    //         type: 'number',
+    //         description: 'Maximum number of results (default: 20)',
+    //       },
+    //       since: {
+    //         type: 'string',
+    //         description: 'Only count changes after this date (ISO format, e.g., "2025-01-01")',
+    //       },
+    //     },
+    //   },
+    // },
+    // {
+    //   name: 'git_cochange',
+    //   description: `Find files that frequently change together with a given file.
+    //
+    // Use this to:
+    // - Discover hidden coupling between files (change A → usually change B too)
+    // - Understand the blast radius of modifying a file
+    // - Identify candidates for refactoring into a single module
+    //
+    // Returns files ranked by co-change frequency, with support metric (0-1).
+    // Requires git history to be ingested first (grafema git-ingest).`,
+    //   inputSchema: {
+    //     type: 'object',
+    //     properties: {
+    //       file: {
+    //         type: 'string',
+    //         description: 'File path to find co-changes for',
+    //       },
+    //       min_support: {
+    //         type: 'number',
+    //         description: 'Minimum support threshold (0-1, default: 0.1 = 10% of commits)',
+    //       },
+    //     },
+    //     required: ['file'],
+    //   },
+    // },
+    // {
+    //   name: 'git_ownership',
+    //   description: `Find who knows a file best — authors ranked by contribution.
+    //
+    // Use this to:
+    // - Identify domain experts for a specific file or module
+    // - Find the right person to review changes to a file
+    // - Understand team ownership distribution
+    //
+    // Returns authors sorted by commit count, with lines added/removed.
+    // Requires git history to be ingested first (grafema git-ingest).`,
+    //   inputSchema: {
+    //     type: 'object',
+    //     properties: {
+    //       file: {
+    //         type: 'string',
+    //         description: 'File path to check ownership for',
+    //       },
+    //     },
+    //     required: ['file'],
+    //   },
+    // },
+    // {
+    //   name: 'git_archaeology',
+    //   description: `Get temporal context for a file — when it was first created and last modified.
+    //
+    // Use this to:
+    // - Find when a file was last touched (and by whom)
+    // - Discover the original author of a file
+    // - Assess staleness (old files may need review)
+    // - Understand the timeline of a module's evolution
+    //
+    // Returns first/last commit date, hash, and author.
+    // Requires git history to be ingested first (grafema git-ingest).`,
+    //   inputSchema: {
+    //     type: 'object',
+    //     properties: {
+    //       file: {
+    //         type: 'string',
+    //         description: 'File path to investigate',
+    //       },
+    //     },
+    //     required: ['file'],
+    //   },
+    // },
+];
+//# sourceMappingURL=knowledge-tools.js.map

package/dist/definitions/knowledge-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-tools.js","sourceRoot":"","sources":["../../src/definitions/knowledge-tools.ts"],"names":[],"mappings":"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"}

package/dist/definitions/notation-tools.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Notation Tools — describe tool definition
+ *
+ * The `describe` tool renders a node's neighborhood as compact DSL notation,
+ * replacing verbose edge listings with archetype-grouped visual operators.
+ */
+import type { ToolDefinition } from './types.js';
+export declare const NOTATION_TOOLS: ToolDefinition[];
+//# sourceMappingURL=notation-tools.d.ts.map

package/dist/definitions/notation-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notation-tools.d.ts","sourceRoot":"","sources":["../../src/definitions/notation-tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,cAAc,EAAE,cAAc,EAsD1C,CAAC"}

package/dist/definitions/notation-tools.js

@@ -0,0 +1,62 @@
+/**
+ * Notation Tools — describe tool definition
+ *
+ * The `describe` tool renders a node's neighborhood as compact DSL notation,
+ * replacing verbose edge listings with archetype-grouped visual operators.
+ */
+export const NOTATION_TOOLS = [
+    {
+        name: 'describe',
+        description: `Render a node's neighborhood as compact Grafema DSL notation.
+
+Reduces verbose edge listings to archetype-grouped visual operators:
+  o-  dependency/import
+  >   outward flow (calls, delegates, passes)
+  <   inward flow (reads, extends, receives)
+  =>  persistent write (db, file, redis)
+  >x  exception (throws, rejects)
+  ~>> event/message (emits, publishes)
+  ?|  conditional guard (if, case)
+  |=  governance (governs, monitors)
+
+Containment edges ({ }) define nesting structure.
+
+Example output:
+  login {
+    o- imports bcrypt
+    > calls UserDB.findByEmail, createToken
+    < reads config.auth
+    => writes session
+    >x throws AuthError
+    ~>> emits 'auth:login'
+  }
+
+Use depth to control detail:
+  0 = names only (children listed, no edges)
+  1 = edges (default — shows all relationship lines)
+  2 = nested + folded (compressed view — repetitive siblings collapsed)
+  3 = nested (exact — every node expanded, no folding)
+
+10-30 lines vs 500+ lines of raw edge data. Ideal for LLM context windows.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: {
+                    type: 'string',
+                    description: 'Semantic ID, file path, or node name to describe',
+                },
+                depth: {
+                    type: 'number',
+                    description: 'Level of detail: 0=names, 1=edges (default), 2=nested+folded (compressed), 3=nested (exact, no folding)',
+                },
+                perspective: {
+                    type: 'string',
+                    description: 'Archetype filter preset: "security" (write,exception), "data" (flow_out,flow_in,write), "errors" (exception), "api" (flow_out,publishes,depends), "events" (publishes)',
+                    enum: ['security', 'data', 'errors', 'api', 'events'],
+                },
+            },
+            required: ['target'],
+        },
+    },
+];
+//# sourceMappingURL=notation-tools.js.map