@directive-run/knowledge 1.14.0 → 1.16.0

package/core/anti-patterns.md

@@ -1,5 +1,7 @@
 # Anti-Patterns
 
+> Covers `@directive-run/core` and `@directive-run/react` — hallucination-prone API patterns to avoid.
+
 19 most common mistakes when generating Directive code, ranked by AI hallucination frequency. Every code generation MUST be checked against this list.
 
 ## 1. Unnecessary Type Casting on Facts/Derivations
@@ -113,11 +115,16 @@ createModule("timer", {
 ## 7. String-Based Event Dispatch
 
 ```typescript
-// WRONG – events are not dispatched by string
+// WRONG – there is no two-argument string-keyed dispatch signature
 system.dispatch("login", { token: "abc" });
 
-// CORRECT – use the events accessor
+// CORRECT – use the typed events accessor (preferred — autocomplete + payload typing)
 system.events.login({ token: "abc" });
+
+// ALSO VALID – the single-arg object form of dispatch() is supported when you
+// need to forward a programmatically-built event. Prefer the events accessor
+// for normal code.
+system.dispatch({ type: "login", token: "abc" });
 ```
 
 ## 8. Direct Array/Object Mutation
@@ -364,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

@@ -1,5 +1,7 @@
 # Constraints
 
+> Covers `@directive-run/core` — constraint definition: `when` / `require`, async constraints with `deps`, priority, data-form predicates.
+
 Constraints declare WHEN something is needed. They are the demand side of the constraint-resolver pattern. Constraints evaluate conditions against facts and emit requirements that resolvers fulfill.
 
 ## Decision Tree: "Should this be a constraint?"
@@ -22,8 +24,10 @@ constraints: {
     // when() returns boolean – evaluated on every fact change
     when: (facts) => facts.isAuthenticated && !facts.user,
 
-    // require – the requirement to emit when condition is true
-    require: { type: "FETCH_USER", userId: facts.userId },
+    // require – the requirement to emit when condition is true.
+    // Use the function form whenever you need to read facts —
+    // facts is NOT in scope inside the static object form.
+    require: (facts) => ({ type: "FETCH_USER", userId: facts.userId }),
   },
 },
 ```
@@ -261,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

@@ -1,5 +1,7 @@
 # Core Patterns
 
+> Covers `@directive-run/core` — modules, facts, derivations, effects, events, and the constraint-resolver loop.
+
 How to think about building with Directive: modules, systems, and the constraint-resolver pattern.
 
 ## Decision Tree: "Where does this logic go?"
@@ -226,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

@@ -1,5 +1,7 @@
 # Error Boundaries
 
+> Covers `@directive-run/core` — error boundaries, recovery strategies, lifecycle hooks, and circuit breakers.
+
 How to handle errors in Directive: recovery strategies, error boundaries, lifecycle hooks, and the circuit breaker pattern.
 
 ## Decision Tree: "How should errors be handled?"
@@ -320,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

@@ -1,5 +1,7 @@
 # History & Snapshots
 
+> Covers `@directive-run/core` — time-travel: snapshot, undo/redo, replay, export/import, changeset grouping.
+
 Directive records fact changes as snapshots, enabling undo/redo, replay, export/import, and changeset grouping.
 
 ## Decision Tree: "Should I enable history?"
@@ -342,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

@@ -1,5 +1,7 @@
 # Multi-Module Systems
 
+> Covers `@directive-run/core` — namespaced multi-module systems, cross-module deps, `facts.self.*`.
+
 How to compose multiple modules into a namespaced system with cross-module type safety.
 
 ## Decision Tree: "Single or Multi-Module?"
@@ -303,13 +305,23 @@ system.registerModule("chat", chatModule.default);
 
 ## Cross-Module Events
 
-Events are namespaced at the system level but dispatched through the events accessor:
+Events are namespaced at the system level. **Prefer the typed events accessor** — it carries autocomplete and per-event payload typing.
 
 ```typescript
-// Multi-module events
+// Multi-module events — canonical form
 system.events.auth.login({ token: "abc" });
 system.events.cart.addItem({ id: "item-1", qty: 1 });
 
-// dispatch() also works with type discriminator
+// dispatch() is supported when you need to forward a programmatically-built
+// event (e.g., replaying a serialized event). The string form
+// (system.dispatch("login", payload)) does NOT exist — only the single-arg
+// 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

@@ -1,81 +1,123 @@
 # Naming Conventions
 
-Directive naming rules that AI coding assistants must follow. These are non-negotiable project conventions.
+> Covers all `@directive-run/*` packages — terminology, parameter names, return-style rules.
 
-## Decision Tree: "What do I call this?"
+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.
 
-```
-Resolver parameter names?
-  → (req, context)     req = requirement, NEVER "request"
-  → NEVER (req, ctx)   context is NEVER abbreviated
+This file is both the rules and the bridge. Search for the term you already know; you'll land on the Directive equivalent.
 
-Computed values?
-  → "derivations" / derive   NEVER "computed", "selectors", "getters"
-  → system.derive.myValue    NEVER system.computed.myValue
+## Coming from another library? Start here
 
-State values?
-  → "facts"                  NEVER "state", "store", "atoms"
-  → system.facts.count       NEVER system.state.count
+| 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. |
 
-Conditional triggers?
-  → "constraints"            NEVER "rules", "conditions", "triggers"
-  → when() + require()       NEVER if/then, trigger/action
+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.
 
-Fulfillment logic?
-  → "resolvers"              NEVER "handlers", "actions", "reducers"
-  → resolve(req, context)    NEVER handle(req, ctx)
-```
+## Canonical terms (non-negotiable for code Directive ships)
+
+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.
+
+### `module` — bounded slice
 
-## Parameter Naming
+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
+### Braces for `if` blocks with `return` (NOT for arrow expressions)
 
-No single-line returns. Always wrap in braces.
+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`.
 
 ```typescript
-// WRONG
+// CORRECT — single-line arrow expressions stay concise
 derive: {
   isReady: (facts) => facts.phase === "ready",
+  greeting: (facts) => `Hi, ${facts.name}!`,
 },
 
 constraints: {
@@ -84,25 +126,26 @@ constraints: {
     require: { type: "PROCESS" },
   },
 },
+```
 
-// Wait -- the above IS correct for one-line arrow expressions.
-// The brace rule applies to if/return blocks:
+**Control-flow statements** (`if`, `for`, `while`): braces required, even for single-line bodies. Single-line `if (x) return y` shapes are never used.
 
-// WRONG – single-line if return
+```typescript
+// WRONG — single-line if return
 if (facts.user) return "ready";
 
-// CORRECT – always use 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;
@@ -110,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;
@@ -125,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(),
@@ -158,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.*`.
 
@@ -205,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,
@@ -214,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>(),
@@ -267,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

@@ -1,5 +1,7 @@
 # Plugins
 
+> Covers `@directive-run/core/plugins` — plugin authoring + built-ins (logging, devtools, persistence, audit-ledger, observability, OTLP).
+
 Plugins extend Directive systems with cross-cutting functionality like logging, persistence, devtools, and resilience patterns.
 
 ## Decision Tree: "Which plugin do I need?"
@@ -352,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