@directive-run/knowledge 1.15.0 → 1.16.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

@@ -286,3 +286,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/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

package/core/naming.md

@@ -2,81 +2,116 @@
 
 > Covers all `@directive-run/*` packages — terminology, parameter names, return-style rules.
 
-Directive naming rules that AI coding assistants must follow. These are non-negotiable project conventions.
+Directive uses precise vocabulary by design: each concept has one canonical name across every package, every language adapter, and every doc. The names are non-negotiable for code Directive ships, AND every term has a cross-paradigm alias so a developer coming from Redux / Zustand / XState / Jotai / React Query can find the right Directive concept on the first search.
 
-## Decision Tree: "What do I call this?"
+This file is both the rules and the bridge. Search for the term you already know; you'll land on the Directive equivalent.
 
-```
-Resolver parameter names?
-  → (req, context)     req = requirement, NEVER "request"
-  → NEVER (req, ctx)   context is NEVER abbreviated
+## Coming from another library? Start here
 
-Computed values?
-  → "derivations" / derive   NEVER "computed", "selectors", "getters"
-  → system.derive.myValue    NEVER system.computed.myValue
+| If you call it… | (in this library) | Directive calls it… | Why the name |
+|---|---|---|---|
+| **state**, **store**, **atom**, **signal**, **observable** | Redux, Zustand, Jotai, Preact Signals, MobX | **facts** | "Facts about the world" — the system observes them. Same value-bag role as state, with a proxy that auto-tracks reads. |
+| **selector**, **computed**, **getter**, **memo**, **derived store** | Redux, Vue/MobX, Zustand getters, Memoize, Svelte | **derivations** / `derive` | Auto-tracked computed values. No dep arrays. Directive's name aligns with "derived from facts." |
+| **action**, **dispatch**, **reducer**, **command**, **intent** | Redux, Redux Toolkit, CQRS | **events** + **resolvers** | Events are the user-facing trigger; resolvers fulfill them. Reducers are split into the two halves Directive cares about. |
+| **thunk**, **saga**, **effect**, **middleware**, **listener** | Redux Toolkit, redux-saga, redux-observable, NgRx | **resolvers** | Async logic that mutates state in response to a requirement. Same role as a thunk; declared once, run by the runtime. |
+| **rule**, **condition**, **guard**, **trigger**, **policy** | XState guards, Cerbos, OPA, business-rule engines | **constraints** | Declarative "when X is true, Y must happen." Constraints emit requirements; resolvers fulfill them. |
+| **request**, **query**, **side-effect spec** | React Query / TanStack Query queries, Apollo queries | **requirements** | The object a constraint emits. The runtime dedupes them, dispatches to resolvers, tracks status. |
+| **subscription**, **listener**, **reaction**, **watcher** | Zustand subscribe, MobX reactions, Redux subscriptions | **effects** | Side-effects that run when watched facts change. Cleaner than `subscribe()` callbacks because effects auto-track. |
+| **slice**, **feature**, **domain**, **bounded context** | Redux Toolkit slices, NgRx feature modules | **modules** | Encapsulates facts + derivations + constraints + resolvers + events for one bounded slice of the system. |
+| **store**, **container**, **context**, **app state** | Redux Store, Pinia, React Context, NgRx Store | **system** | The runtime that wires modules together, evaluates constraints, dispatches resolvers, and exposes observation. |
+| **state machine**, **statechart**, **xstate machine** | XState | (closest: **module** + **constraints**) | Directive isn't a state machine — but if your XState `states` model business rules (not UI flow), constraints + facts express the same logic declaratively with no transition functions. |
+| **cache**, **query cache**, **stale-while-revalidate** | TanStack Query, SWR, Apollo cache | (closest: `@directive-run/query` + **constraints**) | Use `@directive-run/query` for the cache; constraints decide when refetches fire. Directive doesn't replace TanStack Query — it composes with it. |
+| **agent**, **chain**, **graph**, **workflow** | LangChain, LangGraph, OpenAI Assistants | **agent** + **orchestrator** | `@directive-run/ai` keeps the names — agents are agents, orchestrators are orchestrators — but they run under the same constraint engine as the rest of Directive. |
+| **guardrail**, **filter**, **safety check**, **moderation** | OpenAI moderation API, NVIDIA NeMo Guardrails | **guardrails** | Same name, same role; declarative input/output/tool-call checks. |
 
-State values?
-  → "facts"                  NEVER "state", "store", "atoms"
-  → system.facts.count       NEVER system.state.count
+If your term isn't in the table, search the canonical name in this doc's [Terminology quick reference](#terminology-quick-reference) — both directions are listed.
 
-Conditional triggers?
-  → "constraints"            NEVER "rules", "conditions", "triggers"
-  → when() + require()       NEVER if/then, trigger/action
+## Canonical terms (non-negotiable for code Directive ships)
 
-Fulfillment logic?
-  → "resolvers"              NEVER "handlers", "actions", "reducers"
-  → resolve(req, context)    NEVER handle(req, ctx)
-```
+Above is the bridge from your existing vocabulary. Below are the canonical names — the only ones that should appear in `@directive-run/*` source, tests, docs, and generated AI rules.
+
+### `facts` — the value bag
+
+Not state, not store, not atoms. **Facts.** Accessed at `system.facts.x`. Mutated through events and resolvers. Read through derivations, hooks, and `system.facts.$store`.
+
+### `derivations` — auto-tracked computed values
+
+Declared via `derive: { name: (facts) => … }`. Read at `system.derive.name`. The hook is `useDerived` (not `useComputed`, not `useSelector` — Directive's `useSelector` is a different, broader primitive that takes a selector function).
+
+### `constraints` — when-then declarations
+
+Declared via `constraints: { name: { when: …, require: … } }`. The `when` returns a boolean; the `require` returns a requirement.
+
+### `resolvers` — requirement fulfillment
+
+Declared via `resolvers: { name: { requirement: …, resolve: async (req, context) => … } }`. Mutate `context.facts`; never return data from `resolve`.
+
+### `requirements` — what constraints emit
+
+Tagged union `{ type: "FETCH_USER", … }`. Constraints emit them; the runtime dedupes by `type` + `key()`; resolvers fulfill them.
+
+### `effects` — side effects from watched changes
+
+Declared via `effects: { name: { run: (facts, prev) => … } }`. Run on relevant fact changes. The auto-tracking dependency model means no `deps` array unless you specifically need a partial dep set.
+
+### `events` — typed mutation entry points
+
+Declared via `events: { name: (facts, payload) => … }`. Called as `system.events.name(payload)`. The typed events accessor is the canonical way to dispatch — `system.dispatch({type, ...payload})` works but the typed accessor carries autocomplete.
 
-## Parameter Naming
+### `module` — bounded slice
+
+Created via `createModule(name, { schema, init, derive, effects, events, constraints, resolvers })`. Composes into systems.
+
+### `system` — the runtime
+
+Created via `createSystem({ module })` or `createSystem({ modules: { x, y } })`. Hosts the reconciliation loop.
+
+## Parameter naming
 
 ### `req` = requirement (NOT request)
 
-The `req` parameter in resolvers and constraint `key()` functions is short for **requirement** -- the object emitted by a constraint's `require` property.
+The `req` parameter in resolvers and constraint `key()` functions is short for **requirement** — the object emitted by a constraint's `require` property.
 
 ```typescript
-// CORRECT – req is a requirement
+// CORRECT — req is a requirement
 resolvers: {
   fetchUser: {
     requirement: "FETCH_USER",
     key: (req) => `fetch-${req.userId}`,
     resolve: async (req, context) => {
       // req.type === "FETCH_USER"
-      // req.userId from the requirement payload
       const user = await fetchUser(req.userId);
       context.facts.user = user;
     },
   },
 },
 
-// WRONG – never use "request" or "r"
+// WRONG — never "request" or "r"
 resolve: async (request, context) => { /* ... */ },
 resolve: async (r, context) => { /* ... */ },
 ```
 
-### `context` is Never Abbreviated
+### `context` is never abbreviated
 
 ```typescript
 // CORRECT
 resolve: async (req, context) => {
   context.facts.status = "loaded";
-  context.signal; // AbortSignal
-  context.snapshot(); // facts snapshot
+  context.signal;       // AbortSignal
+  context.snapshot();   // facts snapshot
 },
 
-// WRONG – never abbreviate to ctx
+// WRONG — never abbreviate to ctx
 resolve: async (req, ctx) => { /* ... */ },
 ```
 
-## Return Style
+## Return style
 
-### Always Use Braces (for `if` blocks with `return`)
+### Braces for `if` blocks with `return` (NOT for arrow expressions)
 
 The brace rule applies to control-flow blocks — not to arrow-expression bodies.
 
-**Arrow expressions** (single-line derivations, predicates, computed
-requirements): the concise form is preferred. No braces, no explicit
-`return`.
+**Arrow expressions** (single-line derivations, predicates, computed requirements): the concise form is preferred. No braces, no explicit `return`.
 
 ```typescript
 // CORRECT — single-line arrow expressions stay concise
@@ -93,25 +128,24 @@ constraints: {
 },
 ```
 
-**Control-flow statements** (`if`, `for`, `while`): braces required, even
-for single-line bodies. Single-line `if (x) return y` shapes are never used.
+**Control-flow statements** (`if`, `for`, `while`): braces required, even for single-line bodies. Single-line `if (x) return y` shapes are never used.
 
 ```typescript
-// WRONG – single-line if return
+// WRONG — single-line if return
 if (facts.user) return "ready";
 
-// CORRECT – always wrap the body in braces
+// CORRECT — always wrap the body in braces
 if (facts.user) {
   return "ready";
 }
 ```
 
-### Blank Line Before `return`
+### Blank line before `return`
 
 Add a blank line before `return` when there is code above it. Skip the blank line when `return` is the first statement in a block.
 
 ```typescript
-// CORRECT – blank line before return when code precedes it
+// CORRECT — blank line before return when code precedes it
 function getStatus(facts) {
   const phase = facts.phase;
   const hasUser = facts.user !== null;
@@ -119,12 +153,12 @@ function getStatus(facts) {
   return phase === "ready" && hasUser;
 }
 
-// CORRECT – no blank line when return is first statement
+// CORRECT — no blank line when return is first statement
 function isReady(facts) {
   return facts.phase === "ready";
 }
 
-// CORRECT – blank line after brace-style return block
+// CORRECT — blank line after brace-style return block
 function process(facts) {
   if (!facts.ready) {
     return null;
@@ -134,26 +168,20 @@ function process(facts) {
 
   return result;
 }
-
-// WRONG – no blank line before return after code
-function getStatus(facts) {
-  const phase = facts.phase;
-  return phase === "ready"; // Missing blank line
-}
 ```
 
-## Multi-Line Code Formatting
+## Multi-line code formatting
 
 Never put properties or statements on a single line inside braces. Always expand to one item per line with proper indentation. This applies everywhere: schema definitions, init functions, events, effects, requirement types, and any other object or block.
 
 ```typescript
-// WRONG – properties crammed on one line
+// WRONG — properties crammed on one line
 schema: {
   facts: { phase: t.string(), count: t.number() },
   requirements: { FETCH_USER: { id: t.string() }, RESET: {} },
 },
 
-// CORRECT – one property per line, always expanded
+// CORRECT — one property per line, always expanded
 schema: {
   facts: {
     phase: t.string(),
@@ -167,41 +195,31 @@ schema: {
   },
 },
 
-// WRONG – statements crammed on one line
+// WRONG — statements crammed on one line
 init: (facts) => { facts.phase = "idle"; facts.count = 0; },
 
-// CORRECT – one statement per line
+// CORRECT — one statement per line
 init: (facts) => {
   facts.phase = "idle";
   facts.count = 0;
 },
-
-// WRONG
-events: { reset: (facts) => { facts.count = 0; facts.phase = "idle"; } },
-
-// CORRECT
-events: {
-  reset: (facts) => {
-    facts.count = 0;
-    facts.phase = "idle";
-  },
-},
 ```
 
 Single-expression arrows (no braces) are fine on one line. Empty objects `{}` are fine inline.
+
 ```typescript
-// OK – single expression, no braces
+// OK — single expression, no braces
 derive: {
   isReady: (facts) => facts.phase === "ready",
 },
 
-// OK – empty object
+// OK — empty object
 RESET: {},
 ```
 
-## Multi-Module Naming
+## Multi-module naming
 
-### `facts.self.*` for Own Module
+### `facts.self.*` for own module
 
 In multi-module systems, constraints, effects, and derivations with `crossModuleDeps` receive namespaced facts. Own module facts are always at `facts.self.*`.
 
@@ -214,7 +232,7 @@ constraints: {
   },
 },
 
-// WRONG – bare facts.* in multi-module context
+// WRONG — bare facts.* in multi-module context
 constraints: {
   loadWhenAuth: {
     when: (facts) => facts.isAuthenticated && !facts.loaded,
@@ -223,48 +241,48 @@ constraints: {
 },
 ```
 
-### System-Level Access Uses Dot Notation
+### System-level access uses dot notation
 
 ```typescript
-// CORRECT – dot notation through namespace proxy
+// CORRECT — dot notation through namespace proxy
 system.facts.auth.token;
 system.facts.cart.items;
 system.derive.auth.isLoggedIn;
 system.events.auth.login({ token: "..." });
 
-// WRONG – bracket notation with internal separator
+// WRONG — bracket notation with internal separator
 system.facts["auth::token"];
 system.facts["auth_token"];
 ```
 
-## Type Casting Rules
+## Type casting rules
 
-### Never Cast When Reading
+### Never cast when reading
 
 The schema provides all types. Do not add `as` casts when reading facts or derivations from the system.
 
 ```typescript
-// CORRECT – schema provides the type
+// CORRECT — schema provides the type
 const profile = system.facts.profile;
 const isReady = system.derive.isReady;
 
-// WRONG – unnecessary cast
+// WRONG — unnecessary cast
 const profile = system.facts.profile as UserProfile;
 const isReady = system.derive.isReady as boolean;
 ```
 
-### Cast Only in Schema Definition
+### Cast only in schema definition
 
-Type assertions are only valid in schema definition using the `{} as {}` pattern:
+Type assertions are only valid in schema definition using the `{} as {}` pattern, or via the `t.*` builders (preferred):
 
 ```typescript
-// CORRECT – cast in schema definition
+// CORRECT — cast in schema definition
 schema: {
   facts: {} as { profile: UserProfile; settings: AppSettings },
   derivations: {} as { displayName: string },
 },
 
-// OR use t.* builders (preferred)
+// PREFERRED — t.* builders
 schema: {
   facts: {
     profile: t.object<UserProfile>(),
@@ -276,17 +294,28 @@ schema: {
 },
 ```
 
-## Terminology Quick Reference
+## Terminology quick reference
+
+Two-way lookup. Search the term you know.
 
-| Directive Term | NEVER Use |
+| Directive term | Cross-paradigm aliases (use these to search) |
 |---|---|
-| facts | state, store, atoms, signals |
-| derivations / derive | computed, selectors, getters, memos |
-| constraints | rules, conditions, triggers, guards |
-| resolvers | handlers, actions, reducers, sagas |
-| requirements | requests, commands, intents |
-| effects | watchers, subscriptions, reactions |
-| module | slice, feature, domain |
-| system | store, container, context |
-| `req` (parameter) | request, r, requirement (spelled out) |
-| `context` (parameter) | ctx, c, resolverContext |
+| **facts** | state, store, atoms, signals, observables, model |
+| **derivations** / `derive` | computed, selectors, getters, memos, derived stores, $: blocks (Svelte) |
+| **constraints** | rules, conditions, triggers, guards, policies, invariants |
+| **resolvers** | handlers, actions, reducers, sagas, thunks, effects (Redux), middleware, listeners |
+| **requirements** | requests, commands, intents, queries (TanStack), tasks |
+| **effects** | watchers, subscriptions, reactions, autoruns, listeners |
+| **events** | actions, intents, commands, methods (Pinia), signals (NgRx) |
+| **module** | slice, feature, domain, bounded context, NgRx feature module |
+| **system** | store, container, context, app state, app shell |
+| **`req`** (parameter) | request, r, requirement (spelled out) |
+| **`context`** (parameter) | ctx, c, resolverContext |
+
+The forbidden direction is also non-negotiable: in code Directive ships, the columns reverse. Do NOT use `state`, `store`, `selectors`, `computed`, `actions`, `reducers`, `subscriptions`, `slices`, `request`, or `ctx` in `@directive-run/*` source. The alias map is for retrieval — the canonical names are for code.
+
+## See also
+
+- [`core-patterns.md`](./core-patterns.md) — the actual code shapes every naming rule here applies to
+- [`multi-module.md`](./multi-module.md) — `facts.self.*` convention and dot-notation rules
+- [`anti-patterns.md`](./anti-patterns.md) — naming-shaped mistakes (`request` for `req`, `ctx` for `context`, hallucinated TS schema types)

package/core/plugins.md

@@ -354,3 +354,8 @@ persistencePlugin({
   exclude: ["authToken", "isLoading", "error"],
 })
 ```
+
+## See also
+
+- [`system-api.md`](./system-api.md) — `plugins:` option on `createSystem` and the lifecycle hooks plugins observe
+- [`error-boundaries.md`](./error-boundaries.md) — `createCircuitBreaker` and the resilience plugins that pair with error boundaries

package/core/react-adapter.md

@@ -368,3 +368,9 @@ const handleClick = useCallback(() => events.increment(), [events]);
 const events = useEvents(system);
 <button onClick={() => events.increment()}>+</button>
 ```
+
+## See also
+
+- [`system-api.md`](./system-api.md) — the system instance the hooks here read from + the SSR/hydration story
+- [`core-patterns.md`](./core-patterns.md) — the module shape every React example here assumes you've built
+- [`anti-patterns.md`](./anti-patterns.md) — the hallucinated React hooks (`useEvent`, `useSystem`, `DirectiveProvider`) that AI assistants reach for

package/core/resolvers.md

@@ -357,3 +357,11 @@ system.start();
 await system.settle();
 console.log(system.facts.data); // Resolved value
 ```
+
+## See also
+
+- [`constraints.md`](./constraints.md) — the demand side of the loop; what emits the requirements this resolver fulfills
+- [`core-patterns.md`](./core-patterns.md) — how resolvers fit into the module shape
+- [`error-boundaries.md`](./error-boundaries.md) — recovery strategies when a resolver throws (retry, fallback, circuit breaker)
+- [`testing.md`](./testing.md) — mock resolvers via `mocks.resolvers` and the programmatic `mockResolver(type)` helper
+- [`anti-patterns.md`](./anti-patterns.md) — the resolver-shaped mistakes (returning data from `resolve`, abbreviating `context` to `ctx`)

package/core/schema-types.md

@@ -265,3 +265,9 @@ const myModule = createModule("simple", {
 ```
 
 This gives full TypeScript inference but skips runtime validation. Use `t.*()` when you want dev-mode validation, transforms, or self-documenting schemas.
+
+## See also
+
+- [`core-patterns.md`](./core-patterns.md) — where the schemas these builders define get attached (modules)
+- [`system-api.md`](./system-api.md) — schema flows through `createSystem` and shows up on `system.facts.*`
+- [`anti-patterns.md`](./anti-patterns.md) — hallucinated schema types (`t.map`, `t.set`, `t.date`, `t.promise`, `t.tuple`, `t.record`, `t.any`) that don't exist

package/core/system-api.md

@@ -453,3 +453,11 @@ system.start();
 system.stop();
 system.destroy();
 ```
+
+## See also
+
+- [`core-patterns.md`](./core-patterns.md) — the modules that go into `createSystem({ module: ... })`
+- [`multi-module.md`](./multi-module.md) — `createSystem({ modules: { ... } })` for namespaced systems
+- [`history.md`](./history.md) — the `history:` config and the `system.history.*` time-travel surface
+- [`plugins.md`](./plugins.md) — the `plugins:` config and the lifecycle hooks plugins observe
+- [`react-adapter.md`](./react-adapter.md) — consuming a system from React components

package/core/testing.md

@@ -404,3 +404,9 @@ resolve: (req, context) => { context.facts.x = 1; }
 | `system.assertFactSet(key, value?)` | instance method | Assert a fact value |
 | `system.assertFactChanges(key, n)` | instance method | Assert the change count for a fact |
 | `system.waitForIdle(maxWait?)` | instance method | Wait for in-flight resolvers (default 5000ms) |
+
+## See also
+
+- [`resolvers.md`](./resolvers.md) — the resolver shape `mocks.resolvers` replaces and the retry/cancel semantics tests need to know about
+- [`core-patterns.md`](./core-patterns.md) — the module shape `createTestSystem({ module })` is testing
+- [`history.md`](./history.md) — recorded snapshots for replay-based testing patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@directive-run/knowledge",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Knowledge files, examples, and validation for Directive — the constraint-driven TypeScript runtime.",
   "license": "(MIT OR Apache-2.0)",
   "author": "Jason Comes",
@@ -51,8 +51,8 @@
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
     "vitest": "^3.0.0",
-    "@directive-run/core": "1.15.0",
-    "@directive-run/ai": "1.15.0"
+    "@directive-run/core": "1.16.0",
+    "@directive-run/ai": "1.16.0"
   },
   "scripts": {
     "build": "tsx scripts/generate-api-skeleton.ts && tsx scripts/generate-sitemap.ts && tsx scripts/extract-examples.ts && tsup",