@directive-run/knowledge 1.15.0 → 1.17.0

package/ai/ai-adapters.md

@@ -250,3 +250,8 @@ const orchestrator = createAgentOrchestrator({ runner });
 | Gemini | `@directive-run/ai/gemini` | `apiKey`, `defaultModel` |
 
 All adapters support: `baseURL`, `defaultHeaders`, `hooks`, streaming variant.
+
+## See also
+
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — where the `AgentRunner` an adapter produces gets consumed
+- [`ai-agents-streaming.md`](./ai-agents-streaming.md) — the `StreamingCallbackRunner` shape each adapter's streaming variant satisfies

package/ai/ai-agents-streaming.md

@@ -300,3 +300,8 @@ case "guardrail_triggered":
 | `orchestrator.runStream(agent, input, opts?)` | instance method | Returns `{ stream, result, abort }` |
 | `createStreamingRunner(baseRunner, opts?)` | `@directive-run/ai` | Wrap a `StreamingCallbackRunner` into a `StreamRunner` |
 | `createSSETransport(config?)` | `@directive-run/ai` | `{ toResponse, toStream }` for piping a stream to SSE |
+
+## See also
+
+- [`ai-adapters.md`](./ai-adapters.md) — provider runners that produce the streams this file consumes
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — `orchestrator.runStream(agent, input)` returns the `{ stream, result, abort }` triple this file documents

package/ai/ai-budget-resilience.md

@@ -400,3 +400,9 @@ const orchestrator = createAgentOrchestrator({ runner: baseRunner, guardrails: {
 | `createHealthMonitor(config?)` | returns `HealthMonitor`; push outcomes in via `recordSuccess/Failure` | — |
 | `createSemanticCache(config)` | returns `SemanticCache`; use via `createSemanticCacheGuardrail({ cache })` | — |
 | `createConstraintRouter(config)` | returns an `AgentRunner` that picks providers at call time | — |
+
+## See also
+
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — `circuitBreaker` / `selfHealing` / `agentRetry` / `maxTokenBudget` options on `createAgentOrchestrator`
+- [`ai-guardrails-memory.md`](./ai-guardrails-memory.md) — `createSemanticCacheGuardrail({ cache })` wires this file's `SemanticCache` into the orchestrator
+- [`ai-debug-observability.md`](./ai-debug-observability.md) — recording retry storms, circuit-breaker state changes, and budget warnings in the debug timeline

package/ai/ai-communication.md

@@ -297,3 +297,8 @@ return JSON.stringify({ ...JSON.parse(input), researchData: data, timestamp: Dat
 | `network.delegate(from, to, task, context)` | Delegated task with result | `Promise<DelegationResultMessage>` |
 | `orchestrator.system.facts[agentId].x` | Cross-agent fact read | each agent is a namespaced module |
 | `context.scratchpad` | Per-pattern ephemeral state | Readonly inside tasks/agents |
+
+## See also
+
+- [`ai-multi-agent.md`](./ai-multi-agent.md) — the orchestrator that owns the namespaced facts this file's primitives read
+- [`ai-tasks.md`](./ai-tasks.md) — tasks share the scratchpad surface this file documents

package/ai/ai-debug-observability.md

@@ -321,3 +321,9 @@ timeline.subscribe((e) => {
 | `createOtelPlugin(config)` | Plugin that emits spans for orchestrator activity |
 | `createOTLPExporter(config)` | Returns `{ exportMetrics, exportTraces }` for OTel backends |
 | `createDevtoolsServer({ timeline, port })` | WebSocket-bridged timeline for browser devtools |
+
+## See also
+
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — `debug: { verboseTimeline }` config + `orchestrator.timeline` access + breakpoint surface
+- [`ai-budget-resilience.md`](./ai-budget-resilience.md) — retry storms, circuit-breaker state changes, and budget warnings all flow through the debug timeline
+- [`ai-testing-evals.md`](./ai-testing-evals.md) — `createTestTimeline` and `assertTimelineEvents` for asserting against recorded events

package/ai/ai-guardrails-memory.md

@@ -362,3 +362,9 @@ await memory.manage(); // awaits the async summarizer
 | `createOutputTypeGuardrail` | output | `type` |
 | `createLengthGuardrail` | output | one of `maxCharacters` or `maxTokens` |
 | `createContentFilterGuardrail` | output | `blockedPatterns` |
+
+## See also
+
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — `guardrails: { input, output, toolCall }` and `memory:` options on `createAgentOrchestrator`
+- [`ai-security.md`](./ai-security.md) — `createPIIGuardrail`, `createPromptInjectionGuardrail`, `createAuditTrail`, `createCompliance` — the security-flavored guardrails
+- [`ai-budget-resilience.md`](./ai-budget-resilience.md) — `createSemanticCache` pairs with `createSemanticCacheGuardrail` for caching-as-guardrail

package/ai/ai-mcp-rag.md

@@ -4,6 +4,8 @@
 
 Model Context Protocol (MCP) server integration and Retrieval-Augmented Generation (RAG) enrichment for Directive AI agents. Import from `@directive-run/ai/mcp` for the MCP adapter (the main barrel re-exports it with `@deprecated` notices for v2 removal), and from `@directive-run/ai` for the RAG enricher + embedder utilities.
 
+> **Client vs. server, two different packages.** This page covers the MCP **client** side — Directive AI agents calling out to external MCP servers. For the **server** side — exposing Directive itself (knowledge files, code examples, Claude Code skills) so other AI clients can consume it — that's `@directive-run/mcp`. Same protocol, opposite arrows.
+
 ## Decision tree
 
 ```
@@ -286,3 +288,8 @@ type EmbedderFn = (text: string) => Promise<number[]>;
 | `createBatchedEmbedder(config)` | `@directive-run/ai` | `{ embed, flush, dispose }` | Wrap an EmbedderFn with batching |
 | `createTestEmbedder(dim?)` | `@directive-run/ai` | `EmbedderFn` | Deterministic embedder for tests |
 | `createJSONFileStore(options)` | `@directive-run/ai` | `RAGStorage` | File-backed vector store for prototyping |
+
+## See also
+
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — where MCP-supplied tools and RAG-enriched runners flow into agent runs
+- [`ai-security.md`](./ai-security.md) — `toolConstraints[…].requireApproval` and the per-tool approval workflow the MCP adapter exposes

package/ai/ai-multi-agent.md

@@ -366,3 +366,10 @@ orch.start();
 | `race(handlers, options?)` | `string[], { timeout?, minSuccess?, extract? }` | — |
 | `debate(config)` | `{ handlers, evaluator, maxRounds?, extract?, parseJudgement? }` | — (single arg) |
 | `goal(nodes, when, options?)` | `Record<string, GoalNode>, (facts) => boolean, { maxSteps?, extract?, satisfaction? }` | when |
+
+## See also
+
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — the single-agent flavor; covers options and lifecycle this file builds on
+- [`ai-communication.md`](./ai-communication.md) — `createMessageBus` / `createAgentNetwork` for inter-agent messaging within a pattern
+- [`ai-tasks.md`](./ai-tasks.md) — deterministic task handlers that compose with agents inside `dag` / `sequential` patterns
+- [`ai-testing-evals.md`](./ai-testing-evals.md) — `createTestMultiAgentOrchestrator` and pattern-shape assertions

package/ai/ai-orchestrator.md

@@ -455,3 +455,12 @@ const final = await result;
 | `orch.facts.agent.*` | Read built-in agent state |
 | `orch.totalTokens` | Cumulative token count |
 | `orch.timeline` | DebugTimeline (when `debug: true`); `null` otherwise |
+
+## See also
+
+- [`ai-multi-agent.md`](./ai-multi-agent.md) — the multi-agent flavor; 8 composition patterns and pattern factories
+- [`ai-adapters.md`](./ai-adapters.md) — provider runners that produce the `runner` this orchestrator wraps
+- [`ai-guardrails-memory.md`](./ai-guardrails-memory.md) — full surface of the `guardrails:` and `memory:` options on this orchestrator
+- [`ai-budget-resilience.md`](./ai-budget-resilience.md) — full surface of the `circuitBreaker:`, `selfHealing:`, `agentRetry:`, `maxTokenBudget:` options
+- [`ai-debug-observability.md`](./ai-debug-observability.md) — full surface of the `debug:`, `breakpoints:`, `onBreakpoint:` options + `orchestrator.timeline`
+- [`ai-testing-evals.md`](./ai-testing-evals.md) — `createTestOrchestrator` for unit testing this surface

package/ai/ai-security.md

@@ -393,3 +393,8 @@ createCompliance({
 | `createToolGuardrail` | `@directive-run/ai/guardrails` | guardrail | Tool allow/deny lists |
 | `createContentFilterGuardrail` | `@directive-run/ai/guardrails` | guardrail | Block sensitive patterns (block-only — no redact) |
 | `GuardrailError` / `isGuardrailError` | `@directive-run/ai` | error class + guard | Carries `code`, `guardrailName`, `userMessage` |
+
+## See also
+
+- [`ai-guardrails-memory.md`](./ai-guardrails-memory.md) — the broader guardrail surface (length, schema, content filter, tool allowlist) this file's security-flavored guardrails compose with
+- [`ai-mcp-rag.md`](./ai-mcp-rag.md) — `toolConstraints[…].requireApproval` is where MCP tool calls thread into the approval workflow surfaced here

package/ai/ai-tasks.md

@@ -261,3 +261,8 @@ tasks: {
 | Concurrency control | Via patterns | `maxConcurrent` |
 | Scratchpad access | No | Yes |
 | Works in all patterns | Yes | Yes |
+
+## See also
+
+- [`ai-multi-agent.md`](./ai-multi-agent.md) — tasks share the `handler:` namespace with agents inside `dag` / `sequential` / `parallel` patterns
+- [`ai-communication.md`](./ai-communication.md) — tasks read the scratchpad this file's `context.scratchpad` surface exposes

package/ai/ai-testing-evals.md

@@ -477,3 +477,9 @@ const suite = createEvalSuite({
 | `assertOrchestratorState` / `assertMultiAgentState` / `assertScratchpadState` / `assertDerivedValues` / `assertTimelineEvents` / `assertDagExecution` / `assertBreakpointHit` / `assertRerouted` / `assertAgentHealth` / `assertCheckpoint` / `assertMultiplexedStream` | `@directive-run/ai/testing` | State/topology/event assertions |
 | `createEvalSuite` | `@directive-run/ai/evals` | Dataset-driven multi-criterion eval runner |
 | `evalCost` / `evalLatency` / `evalOutputLength` / `evalSafety` / `evalStructure` / `evalMatch` / `evalJudge` / `evalFaithfulness` / `evalRelevance` / `evalCoherence` / `evalAssert` | `@directive-run/ai/evals` | Built-in criterion factories |
+
+## See also
+
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — `createTestOrchestrator` wraps this orchestrator; the prod surface is what your tests are exercising
+- [`ai-multi-agent.md`](./ai-multi-agent.md) — `createTestMultiAgentOrchestrator` for testing pattern execution
+- [`ai-debug-observability.md`](./ai-debug-observability.md) — recorded debug events feed `assertTimelineEvents` / `assertDagExecution` / `assertBreakpointHit`

package/compositions.json

@@ -0,0 +1,216 @@
+{
+  "$schema": "./compositions.schema.json",
+  "version": 1,
+  "edges": [
+    {
+      "from": "@directive-run/query",
+      "to": "@directive-run/mutator",
+      "reason": "discriminated-union mutators pair with query's invalidation tags for end-to-end optimistic writes"
+    },
+    {
+      "from": "@directive-run/query",
+      "to": "@directive-run/optimistic",
+      "reason": "withOptimistic / withOptimisticHandlers add client-side rollback when a mutation fails"
+    },
+    {
+      "from": "@directive-run/query",
+      "to": "@directive-run/timeline",
+      "reason": "timeline captures every cache invalidation + refetch so flaky tests reproduce byte-for-byte"
+    },
+    {
+      "from": "@directive-run/mutator",
+      "to": "@directive-run/query",
+      "reason": "pair mutators with query's invalidation tags so a successful mutation refetches the right resources"
+    },
+    {
+      "from": "@directive-run/mutator",
+      "to": "@directive-run/optimistic",
+      "reason": "withOptimisticHandlers wraps a defineMutator handler with snapshot + rollback in one call"
+    },
+    {
+      "from": "@directive-run/mutator",
+      "to": "@directive-run/timeline",
+      "reason": "every mutation cycle records into the timeline for replay-based test reproduction"
+    },
+    {
+      "from": "@directive-run/optimistic",
+      "to": "@directive-run/mutator",
+      "reason": "defineMutator handlers wrapped with withOptimisticHandlers get rollback for free"
+    },
+    {
+      "from": "@directive-run/optimistic",
+      "to": "@directive-run/query",
+      "reason": "an optimistic mutation that invalidates a query tag also reverts the invalidation on rollback"
+    },
+    {
+      "from": "@directive-run/optimistic",
+      "to": "@directive-run/timeline",
+      "reason": "optimistic writes AND their rollbacks both record into the timeline"
+    },
+    {
+      "from": "@directive-run/timeline",
+      "to": "@directive-run/mutator",
+      "reason": "every mutation cycle records into the timeline; replay a failed test's exact mutation sequence"
+    },
+    {
+      "from": "@directive-run/timeline",
+      "to": "@directive-run/optimistic",
+      "reason": "captures optimistic writes AND rollbacks for byte-for-byte test reproduction"
+    },
+    {
+      "from": "@directive-run/timeline",
+      "to": "@directive-run/query",
+      "reason": "every query invalidation + refetch records into the timeline"
+    },
+    {
+      "from": "@directive-run/timeline",
+      "to": "@directive-run/core",
+      "reason": "core's reconciliation cycles are the source events the timeline captures"
+    },
+    {
+      "from": "@directive-run/core",
+      "to": "@directive-run/react",
+      "reason": "useFact / useDerived / useEvents hooks subscribe to the core system from React components"
+    },
+    {
+      "from": "@directive-run/core",
+      "to": "@directive-run/vue",
+      "reason": "useFact / useDerived composables expose the core system to Vue components"
+    },
+    {
+      "from": "@directive-run/core",
+      "to": "@directive-run/svelte",
+      "reason": "Svelte store adapters wrap the core system for component subscription"
+    },
+    {
+      "from": "@directive-run/core",
+      "to": "@directive-run/solid",
+      "reason": "Solid signal adapters wrap the core system"
+    },
+    {
+      "from": "@directive-run/core",
+      "to": "@directive-run/lit",
+      "reason": "Lit controllers wrap the core system for Web Component subscription"
+    },
+    {
+      "from": "@directive-run/core",
+      "to": "@directive-run/el",
+      "reason": "framework-free DOM bindings — bind, bindText, mount thread schema typing into vanilla DOM updaters"
+    },
+    {
+      "from": "@directive-run/core",
+      "to": "@directive-run/ai",
+      "reason": "AI orchestrator modules ARE Directive modules — constraints trigger agent runs, resolvers execute them"
+    },
+    {
+      "from": "@directive-run/ai",
+      "to": "@directive-run/core",
+      "reason": "agent orchestrators are built on core's constraint-resolver loop with custom resolvers that call LLMs"
+    },
+    {
+      "from": "@directive-run/ai",
+      "to": "@directive-run/knowledge",
+      "reason": "knowledge package is the source of truth for the rules + examples that ai/mcp's RAG enricher serves"
+    },
+    {
+      "from": "@directive-run/ai",
+      "to": "@directive-run/mcp",
+      "reason": "ai/mcp is the CLIENT side (createMCPAdapter); @directive-run/mcp is the SERVER side — opposite arrows, same protocol"
+    },
+    {
+      "from": "@directive-run/mcp",
+      "to": "@directive-run/knowledge",
+      "reason": "MCP server tools (list_knowledge, get_knowledge, search_knowledge) front the knowledge package's data APIs"
+    },
+    {
+      "from": "@directive-run/mcp",
+      "to": "@directive-run/claude-plugin",
+      "reason": "MCP server tools (list_skills, get_skill) expose the Claude Code skill bundles to non-Claude MCP clients"
+    },
+    {
+      "from": "@directive-run/mcp",
+      "to": "@directive-run/scaffold",
+      "reason": "generate_module MCP tool wraps the scaffold package's pure generators and returns source as a string"
+    },
+    {
+      "from": "@directive-run/mcp",
+      "to": "@directive-run/lint",
+      "reason": "review_source and fix_code MCP tools wrap the lint package's ts-morph rule registry"
+    },
+    {
+      "from": "@directive-run/cli",
+      "to": "@directive-run/scaffold",
+      "reason": "directive new <name> delegates to scaffold's generators and writes the result to disk"
+    },
+    {
+      "from": "@directive-run/cli",
+      "to": "@directive-run/knowledge",
+      "reason": "directive ai-rules bundles the knowledge package's content into per-assistant rule files (.cursorrules, CLAUDE.md, etc.)"
+    },
+    {
+      "from": "@directive-run/cli",
+      "to": "@directive-run/claude-plugin",
+      "reason": "directive ai-rules can install the Claude Code plugin bundle as one of its targets"
+    },
+    {
+      "from": "@directive-run/claude-plugin",
+      "to": "@directive-run/knowledge",
+      "reason": "skill bundles copy supporting files from the knowledge package at build time"
+    },
+    {
+      "from": "@directive-run/scaffold",
+      "to": "@directive-run/core",
+      "reason": "generated modules import createModule, t, and ModuleSchema from core"
+    },
+    {
+      "from": "@directive-run/lint",
+      "to": "@directive-run/knowledge",
+      "reason": "rule IDs match the anti-pattern IDs parsed from knowledge/core/anti-patterns.md"
+    },
+    {
+      "from": "@directive-run/react",
+      "to": "@directive-run/core",
+      "reason": "all React hooks consume systems built with @directive-run/core"
+    },
+    {
+      "from": "@directive-run/vue",
+      "to": "@directive-run/core",
+      "reason": "all Vue composables consume systems built with @directive-run/core"
+    },
+    {
+      "from": "@directive-run/svelte",
+      "to": "@directive-run/core",
+      "reason": "Svelte adapter consumes systems built with @directive-run/core"
+    },
+    {
+      "from": "@directive-run/solid",
+      "to": "@directive-run/core",
+      "reason": "Solid adapter consumes systems built with @directive-run/core"
+    },
+    {
+      "from": "@directive-run/lit",
+      "to": "@directive-run/core",
+      "reason": "Lit controllers consume systems built with @directive-run/core"
+    },
+    {
+      "from": "@directive-run/el",
+      "to": "@directive-run/core",
+      "reason": "framework-free DOM bindings consume systems built with @directive-run/core"
+    },
+    {
+      "from": "@directive-run/knowledge",
+      "to": "@directive-run/cli",
+      "reason": "knowledge ships as the data layer for directive ai-rules / directive install"
+    },
+    {
+      "from": "@directive-run/knowledge",
+      "to": "@directive-run/mcp",
+      "reason": "knowledge ships as the data layer for MCP tools (list_knowledge, get_knowledge, etc.)"
+    },
+    {
+      "from": "@directive-run/knowledge",
+      "to": "@directive-run/claude-plugin",
+      "reason": "knowledge ships as the data layer for Claude Code skill bundles"
+    }
+  ]
+}

package/core/anti-patterns.md

@@ -371,3 +371,12 @@ Before generating any Directive code, verify:
 8. Multi-module uses `facts.self.*` for own facts
 9. Imports from `@directive-run/core`, not deep paths
 10. `await system.settle()` after `system.start()`
+
+## See also
+
+- [`naming.md`](./naming.md) — the strict canonical-term rules AND the alias map for cross-paradigm searches
+- [`constraints.md`](./constraints.md) — the constraint shape these anti-patterns reference (`facts` not in scope inside static `require:`, etc.)
+- [`resolvers.md`](./resolvers.md) — the resolver shape these anti-patterns reference (return `void`, mutate `context.facts`, `(req, context)` not `(req, ctx)`)
+- [`schema-types.md`](./schema-types.md) — the `t.*()` builders that exist and the hallucinated ones (`t.map`, `t.set`, `t.promise`, `t.date`) that don't
+- [`react-adapter.md`](./react-adapter.md) — the React hooks that exist and the hallucinated ones (`useEvent`, `useSystem`, `DirectiveProvider`) that don't
+- [`error-boundaries.md`](./error-boundaries.md) — error-handling shapes AI assistants sometimes invent

package/core/constraints.md

@@ -265,3 +265,10 @@ constraints: {
 "Whenever X changes, log it" → Effect
 "X is always facts.a + facts.b" → Derivation
 ```
+
+## See also
+
+- [`resolvers.md`](./resolvers.md) — the other half of the constraint-resolver loop; the supply side that fulfills the requirements constraints emit
+- [`core-patterns.md`](./core-patterns.md) — how constraints fit into the module shape alongside facts, derivations, events, and effects
+- [`multi-module.md`](./multi-module.md) — `crossModuleDeps` for constraints that fire on facts owned by another module
+- [`anti-patterns.md`](./anti-patterns.md) — the constraint-shaped mistakes AI assistants reliably make

package/core/core-patterns.md

@@ -228,3 +228,13 @@ const typed = createModule("typed", {
   },
 });
 ```
+
+## See also
+
+- [`constraints.md`](./constraints.md) — the demand side of the constraint-resolver loop
+- [`resolvers.md`](./resolvers.md) — the supply side that fulfills requirements
+- [`schema-types.md`](./schema-types.md) — the `t.*()` builders that define fact and derivation types
+- [`multi-module.md`](./multi-module.md) — when a single module isn't enough
+- [`system-api.md`](./system-api.md) — `createSystem` and the runtime instance once your module is defined
+- [`naming.md`](./naming.md) — terminology conventions every example here follows
+- [`testing.md`](./testing.md) — `createTestSystem` for the modules you're learning to write

package/core/error-boundaries.md

@@ -322,3 +322,9 @@ try {
 6. Add `onError` callback for logging/monitoring
 7. Use `"throw"` for derivation errors (they indicate bugs)
 8. Use `"skip"` for non-critical effects (logging, analytics)
+
+## See also
+
+- [`resolvers.md`](./resolvers.md) — retry policies and cancellation; the most common error source
+- [`plugins.md`](./plugins.md) — `createCircuitBreaker` lives in `@directive-run/core/plugins`; pair it with error boundaries for cascading-failure isolation
+- [`anti-patterns.md`](./anti-patterns.md) — common error-handling mistakes (catching the wrong type, swallowing recoverable errors)

package/core/history.md

@@ -344,3 +344,8 @@ const system = createSystem({
   history: true,
 });
 ```
+
+## See also
+
+- [`system-api.md`](./system-api.md) — `history` config in `createSystem` + the full `system.history.*` API
+- [`testing.md`](./testing.md) — replay-driven testing patterns that pair with recorded snapshots

package/core/multi-module.md

@@ -318,3 +318,10 @@ system.events.cart.addItem({ id: "item-1", qty: 1 });
 // object form is valid.
 system.dispatch({ type: "login", token: "abc" });
 ```
+
+## See also
+
+- [`core-patterns.md`](./core-patterns.md) — start here for the single-module shape before going namespaced
+- [`system-api.md`](./system-api.md) — `createSystem({ modules: { ... } })` and the namespaced facts proxy
+- [`constraints.md`](./constraints.md) — `crossModuleDeps` for constraints that fire on facts owned by another module
+- [`naming.md`](./naming.md) — `facts.self.*` convention; dot-notation vs bracket-notation rules