@govplane/runtime-sdk 0.2.4 → 0.5.0

package/README.md

@@ -8,15 +8,46 @@ It is intended for backend services, workers, gateways, and critical paths that
 
 ---
 
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Your Application                      │
+│                                                          │
+│  client.evaluate({ target, context })                    │
+│         │                                                │
+│         ▼                                                │
+│  ┌─────────────────┐   bundle cache   ┌───────────────┐ │
+│  │  PolicyEngine   │◄─────────────────│ RuntimeClient │ │
+│  │  (in-process)   │                  │  (polling)    │ │
+│  └────────┬────────┘                  └──────┬────────┘ │
+│           │ Decision                         │ HTTP     │
+│           ▼                                  ▼          │
+│     allow / deny /              Govplane Control Plane   │
+│     throttle / kill_switch /    (bundle endpoint only)  │
+│     custom                                               │
+└─────────────────────────────────────────────────────────┘
+```
+
+| Property | Details |
+|---|---|
+| Decision latency | < 1 ms (in-process evaluation) |
+| Network dependency | Bundle fetch only — evaluation is offline-safe |
+| PII in traces | None — context is never included in trace events |
+| Fail-safe | Deny-by-default when bundle is missing or invalid |
+| Bundle delivery | Server-compiled JSON bundle, not evaluated server-side |
+
+---
+
 ## Design Principles
 
-- 🔒 **No exposed endpoints** – no middleware, no inbound surface
-- 🧠 **Local-first evaluation** – decisions are made in-process
-- 🧼 **Zero PII by design** – strict context validation and allowlists
-- 📦 **Precompiled policies** – no DSL or dynamic code at runtime
-- 🧩 **Deterministic outcomes** – same input, same decision
-- ⚡ **Cheap polling** – HEAD + ETag + conditional GET
-- 🧯 **Failure-safe** – backoff, degraded mode, deny-by-default
+- **No exposed endpoints** – no middleware, no inbound surface
+- **Local-first evaluation** – decisions are made in-process
+- **Zero PII by design** – strict context validation and heuristic PII key blocking
+- **Precompiled policies** – no DSL or dynamic code at runtime
+- **Deterministic outcomes** – same input, same decision
+- **Cheap polling** – HEAD + ETag + conditional GET
+- **Failure-safe** – backoff, degraded mode, deny-by-default
 
 ---
 
@@ -25,51 +56,46 @@ It is intended for backend services, workers, gateways, and critical paths that
 ### Runtime Client
 - Efficient **HEAD-first polling** using `ETag` and `If-None-Match`
 - In-memory bundle cache
-- Automatic request de-duplication
+- `warmStart()` to block until first bundle is ready
 - Configurable polling interval
 - **Burst mode** for incident response
 - **Exponential backoff with jitter**
-- Automatic **degraded state**
-- Status subscriptions (`ok` / `degraded`)
-
-### Policy Engine (SDK-only)
-- Supports:
-  - `allow`
-  - `deny`
-  - `kill_switch`
-  - `throttle`
-- **Deny-by-default**
-- Kill-switch always wins
-- Throttle selects the **most restrictive rule**
-- Deterministic rule ordering
-- Precompiled `when` AST evaluation
-- No dynamic evaluation or code execution
+- Automatic **degraded state** with `nextRetryAt` reporting
+- Status subscriptions via `onStatus()` and bundle update subscriptions via `onUpdate()`
+
+### Policy Engine
+- Five effect types: `allow`, `deny`, `kill_switch`, `throttle`, `custom`
+- **Deny-by-default** – no bundle or no match always denies
+- Fixed precedence: `kill_switch > deny > throttle > allow > custom > deny-by-default`
+- Throttle selects the **most restrictive** matching rule
+- `thenEffect` / `elseEffect` for conditional branching within a single rule
+- Policy-level `defaults` as a fallback when no rule matches
+- Deterministic rule ordering by `priority`, then `policyKey`, then `ruleId`
+- Precompiled `when` AST evaluation — no dynamic code execution
+- Optional automatic JSON parsing of `custom` effect values (`parseCustomEffect`)
 
 ### Security & Context Safety
-- Explicit context allowlist
-- Unknown keys rejected (PII protection)
-- Configurable limits:
-  - max string length
-  - max array length
-  - max depth
-- Context policy is fully configurable per engine
-
-### Decision Trace / Explain (SDK-only)
-- Optional decision trace generation
-- Compact or full trace modes
-- Sampling support (e.g. 1% in production)
-- Force tracing for debugging
-- Structured JSON trace output
-- **Async trace sinks** (fire-and-forget)
-- Bounded queues with drop strategies
+- Explicit context `allowedKeys` allowlist — unknown keys throw immediately
+- Heuristic PII key blocking (`blockLikelyPiiKeys`)
+- Configurable limits: `maxStringLen`, `maxArrayLen`
+- Context policy is fully configurable per engine instance
+- Disable validation only in controlled test environments
+
+### Decision Tracing
+- `evaluate()` for plain decisions; `evaluateWithTrace()` for traced decisions
+- Four trace levels: `off`, `errors`, `sampled`, `full`
+- Sampling rate and per-window budget controls
+- `force: true` to bypass sampling for debug sessions
+- Compact or full format (full includes per-rule breakdown)
+- **Synchronous and async trace sinks** with bounded queues and drop strategies
+- `flushTraces()` for graceful shutdown
 
 ---
 
 ## Requirements
 
 - **Node.js ≥ 18**
-- A valid **Govplane Runtime Key**
-- Access to a Govplane Runtime API (`gp-runtime`)
+- A valid **Govplane Runtime Key** (`rk_live_…` or `rk_test_…`)
 
 ---
 
@@ -79,214 +105,334 @@ It is intended for backend services, workers, gateways, and critical paths that
 npm install @govplane/runtime-sdk
 ```
 
+```bash
+yarn add @govplane/runtime-sdk
+# or
+pnpm add @govplane/runtime-sdk
+```
+
 ---
 
 ## Quick Start
 
-### 1. Create a Runtime Client
-
-```ts
+```typescript
 import { RuntimeClient } from "@govplane/runtime-sdk";
 
 const client = new RuntimeClient({
-  baseUrl: "https://runtime.govplane.com",
+  baseUrl:    "https://123456.runtime.govplane.com/",
   runtimeKey: process.env.GP_RUNTIME_KEY!,
-  orgId: "org_dev",
-  projectId: "prj_web",
-  env: "prod"
 });
 
-client.start();
+await client.warmStart();   // block until the first bundle is cached
+client.start();             // begin background polling (every 5 s by default)
+
+const result = client.evaluate({
+  target:  { service: "payments", resource: "checkout", action: "create" },
+  context: { plan: "pro", country: "ES", isAuthenticated: true },
+});
+
+console.log(result.decision); // "allow" | "deny" | "throttle" | "kill_switch" | "custom"
 ```
 
-### 2. Create a Policy Engine
+---
 
-```ts
-import { createPolicyEngine } from "@govplane/runtime-sdk";
+## Effect Types
 
-const engine = createPolicyEngine({
-  getBundle: () => client.getCached().bundle,
-  validateContext: true,
-  contextPolicy: {
-    allowedKeys: [
-      "ctx.plan",
-      "ctx.country",
-      "ctx.amount",
-      "ctx.isAuthenticated"
-    ],
-    maxStringLen: 64,
-    maxArrayLen: 10
-  }
-});
+The engine returns one of five decision types, applied in this fixed precedence order:
+
+```
+kill_switch  >  deny  >  throttle  >  allow  >  custom  >  deny-by-default
 ```
 
-### 3. Evaluate a Decision
+| `decision`    | When it fires |
+|---------------|---------------|
+| `allow`       | An `allow` rule matched, or the policy default is `allow`. |
+| `deny`        | A `deny` rule matched, no rule matched (deny-by-default), or the policy default is `deny`. |
+| `kill_switch` | A `kill_switch` rule or policy default is active. Always wins. |
+| `throttle`    | A `throttle` rule or policy default matched. Most restrictive wins. |
+| `custom`      | A `custom` rule or policy default matched — carries an arbitrary string value. |
 
-```ts
-const result = engine.evaluate({
-  target: {
-    service: "payments",
-    resource: "checkout",
-    action: "create"
-  },
-  context: {
-    plan: "pro",
-    country: "ES",
-    amount: 42,
-    isAuthenticated: true
-  }
-});
+---
 
-console.log(result.decision); // allow | deny | throttle | kill_switch
+## Decision Shape
+
+`evaluate()` always returns a `Decision` object discriminated by `decision`:
+
+```typescript
+type Decision =
+  | { decision: "allow";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string }
+  | { decision: "deny";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string }
+  | { decision: "kill_switch";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      killSwitch: { service: string; reason?: string } }
+  | { decision: "throttle";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      throttle: { limit: number; windowSeconds: number; key: string } }
+  | { decision: "custom";
+      reason: "default" | "rule"; policyKey?: string; ruleId?: string;
+      value: string; parsedValue?: unknown };
 ```
 
----
+### Handling every decision type
 
-## Runtime Bundle Model
+```typescript
+const result = client.evaluate({ target, context });
 
-The SDK retrieves **materialized runtime bundles** generated by Govplane.
+if (result.decision === "allow") {
+  return next();
+}
 
-```ts
-type RuntimeBundleV1 = {
-  schemaVersion: 1;
-  orgId: string;
-  projectId: string;
-  env: string;
-  generatedAt: string;
-  policies: unknown[];
-};
+if (result.decision === "deny") {
+  return reply.status(403).send({ error: "Forbidden", policy: result.policyKey });
+}
+
+if (result.decision === "throttle") {
+  const allowed = await rateLimiter.check(
+    result.throttle.key === "tenant" ? ctx.tenantId : ctx.userId,
+    result.throttle.limit,
+    result.throttle.windowSeconds,
+  );
+  if (!allowed) return reply.status(429).header("Retry-After", String(result.throttle.windowSeconds)).send();
+  return next();
+}
+
+if (result.decision === "kill_switch") {
+  return reply.status(503).send({ error: "Service Unavailable", reason: result.killSwitch.reason });
+}
+
+if (result.decision === "custom") {
+  const payload = result.parsedValue ?? JSON.parse(result.value);
+  return reply.send(payload);
+}
 ```
 
-The bundle is treated as **immutable and read-only**.
+> **Note:** The SDK does not maintain rate-limit counters. It signals the throttle parameters; your infrastructure (Redis, middleware, etc.) is responsible for enforcement.
 
 ---
 
-## Polling & Burst Mode
+## Custom Effects
 
-```ts
-// Force immediate refresh
-await client.refreshNow();
+A `custom` effect carries an arbitrary string — including a JSON-encoded object — back to the caller. Common uses: feature flags, A/B variants, per-tenant configuration overlays.
 
-// Temporarily increase polling frequency (e.g. incident response)
-await client.refreshNow({ burst: true });
+Enable automatic JSON parsing with `engine.parseCustomEffect`:
+
+```typescript
+const client = new RuntimeClient({
+  baseUrl:    "https://123456.runtime.govplane.com/",
+  runtimeKey: process.env.GP_RUNTIME_KEY!,
+  engine: {
+    parseCustomEffect: true,   // JSON.parse() applied automatically
+  },
+});
+
+const result = client.evaluate({ target, context });
+
+if (result.decision === "custom") {
+  const flags = result.parsedValue as { enabled: boolean; variant: string };
+  if (flags?.enabled) renderNewCheckout();
+}
 ```
 
-Polling strategy:
-1. `HEAD /v1/runtime/bundle`
-2. Compare `ETag`
-3. If changed → `GET`
-4. If unchanged → no download, no JSON parse
+Non-JSON strings leave `parsedValue` as `undefined`; the raw `value` string is always present as a fallback.
 
 ---
 
-## Backoff & Degraded Mode
+## Conditional Rules (`when` / `thenEffect` / `elseEffect`)
 
-On repeated failures, the client:
-- Applies exponential backoff with jitter
-- Enters **degraded** state after N failures
-- Emits status updates
+Rules support an optional `when` condition AST evaluated against the call-time context. The AST is compiled by the control plane and distributed in the bundle — the SDK never executes dynamic code.
 
-```ts
-client.onStatus((status) => {
-  if (status.state === "degraded") {
-    console.warn("Runtime degraded:", status);
-  }
-});
+```
+when absent           → always apply effect
+when == true          → apply thenEffect   (fallback: effect)
+when == false         → apply elseEffect   (fallback: skip rule)
 ```
 
-In degraded mode, cached bundles remain active.
+Supported operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `exists`, `and`, `or`, `not`.
+
+The `ctx.` prefix on paths is optional and stripped automatically (`ctx.plan` ≡ `plan`).
 
 ---
 
-## Runtime Incident Controls
+## Policy Defaults
 
-During an incident (DDoS, fraud spike, abuse, misconfiguration), it may be necessary to:
-- Force faster policy propagation
-- Trigger immediate policy refresh
-- Temporarily increase polling frequency (“burst mode”)
+Every policy can declare a `defaults` object — the fallback effect when no rule matches that target. Defaults are treated as a synthetic rule with `priority = -1`, so any explicit rule always wins.
 
-Govplane Runtime SDK provides **passive incident controls** that allow operators to react to incidents **without exposing endpoints**, **without handling PII**, and **without recompiling application code**.
+```json
+{
+  "policyKey": "strict-rbac",
+  "defaults":  { "effect": "deny" },
+  "rules": [...]
+}
+```
 
-These controls are designed to be:
-- Local-only
-- Zero-network-surface
-- Safe under active attack
-- Compatible with containerized and orchestrated environments
+All five effect types are supported as defaults: `allow`, `deny`, `throttle`, `kill_switch`, `custom`.
+
+---
 
-### Supported Incident Control Mechanisms
+## Runtime Bundle Model
 
-| Mechanism | Restart Required | Network Surface | Hot | Recommended |
-|---------|------------------|-----------------|-----|-------------|
-| Environment Variable | Usually yes | None | ❌ | ✅ |
-| File-based Hot Reload | No | None | ✅ | ⭐ **Primary** |
-| POSIX Signal (SIGUSR1) | No | None | ✅ | Optional |
+The SDK retrieves **compiled runtime bundles** generated by the Govplane control plane.
+
+```typescript
+type RuntimeBundleV1 = {
+  schemaVersion:  1;
+  orgId:          string;
+  projectId:      string;
+  env:            string;
+  generatedAt:    string;       // ISO timestamp
+  bundleVersion?: number;
+  checksum?:      string;       // e.g. "sha256:..."
+  policies:       RuntimePolicy[];
+};
+```
+
+The bundle is treated as **immutable and read-only**. See [Types & Interfaces](docs/reference/TypesAndInterfaces.md) for the full type tree.
 
 ---
 
-**Example: Environment Variable Incident Mode**
+## Bundle Lifecycle & Polling
 
-If the following environment variable is set, the Runtime SDK automatically enters **incident mode**:
+All `evaluate()` calls read from an in-memory cache — there is no network hop at decision time.
 
-```bash
-GP_RUNTIME_INCIDENT=1
+```typescript
+// Block until first bundle is ready, then start background polling
+await client.warmStart({ timeoutMs: 10_000 });
+client.start();
 ```
 
-When detected:
-	•	Burst polling is enabled
-	•	Refresh cadence increases
-	•	Degraded recovery is accelerated
+Polling strategy per cycle:
+1. `HEAD` the bundle endpoint to check the current `ETag`
+2. If `ETag` unchanged → update metadata, skip the `GET`
+3. If `ETag` changed → `GET` the full bundle, parse, update cache
+4. Notify `onUpdate` listeners
+
+| Phase | Interval |
+|---|---|
+| Normal | `pollMs` (default **5 000 ms**) |
+| Burst mode | `burstPollMs` (default **500 ms**) for `burstDurationMs` (default **30 000 ms**) |
+| Backoff | Exponential, capped at `backoffMaxMs` |
+
+### Bundle update subscription
+
+```typescript
+client.onUpdate((result) => {
+  logger.info("Bundle updated", {
+    etag:          result.meta.etag,
+    bundleVersion: result.meta.bundleVersion,
+    updatedAt:     result.meta.updatedAt,
+  });
+});
+```
+
+---
 
-Notes
-	•	In most container platforms (ECS, Kubernetes), environment variables cannot be changed at runtime
-	•	A rolling restart is usually required
-	•	For zero-restart response, use File-based Hot Reload
+## Backoff & Degraded Mode
 
+On repeated failures the client applies exponential backoff with jitter and enters **degraded mode** after a configurable number of consecutive failures. The cached bundle remains active in degraded mode.
 
-**More details: [Govplane Runtime SDK – Runtime Incident Controls](docs/operations/Govplane_Runtime_Incident_Controls.md)**
+```typescript
+const client = new RuntimeClient({
+  ...
+  backoffBaseMs:        500,
+  backoffMaxMs:         30_000,
+  backoffJitter:        0.2,
+  degradeAfterFailures: 3,
+});
+
+client.onStatus((status) => {
+  if (status.state === "degraded") {
+    alerting.trigger("govplane_sdk_degraded", {
+      failures:    status.consecutiveFailures,
+      lastError:   status.lastError.message,
+      nextRetryAt: status.nextRetryAt,
+    });
+  }
+});
+```
+
+Backoff formula: `delay = clamp(base × 2^(failures-1), 0, backoffMaxMs) ± jitter%`
 
 ---
 
-## Throttle Decisions
+## Context Policy & PII Safety
 
-```ts
-if (result.decision === "throttle") {
-  rateLimiter.apply(
-    result.throttle.key,
-    result.throttle.limit,
-    result.throttle.windowSeconds
-  );
-}
+The `context` object is validated synchronously before every evaluation. A violation throws immediately, before any rule is tested.
+
+```typescript
+const client = new RuntimeClient({
+  ...
+  engine: {
+    contextPolicy: {
+      allowedKeys:        ["plan", "role", "country", "isAuthenticated", "requestTier"],
+      maxStringLen:       64,
+      maxArrayLen:        10,
+      blockLikelyPiiKeys: true,   // blocks email, phone, name, ip, ssn, etc.
+    },
+  },
+});
 ```
 
-When multiple throttle rules match, the **most restrictive** one is selected.
+Default allowed keys: `plan`, `country`, `requestTier`, `feature`, `amount`, `isAuthenticated`, `role`.
+
+`object` values are not permitted at the top level. Permitted value types: `string`, `number`, `boolean`, `null/undefined`, `string[]`.
+
+> Disable validation (`engine: { validateContext: false }`) only in controlled test environments.
 
 ---
 
-## Decision Trace / Explain
+## Decision Tracing
 
-### Production (Sampled)
+Use `evaluateWithTrace()` to attach a `DecisionTrace` to the result for observability and debugging. Traces contain only structural metadata — no context values or PII.
 
-```ts
-const out = engine.evaluateWithTrace(
-  { target, context },
-  { sampling: 0.01, mode: "compact" }
-);
+### Production (sampled)
 
-if (out.trace) {
-  console.log(out.trace.summary);
+```typescript
+const client = new RuntimeClient({
+  ...
+  trace: {
+    defaults: {
+      level:    "sampled",
+      sampling: 0.05,   // 5% of evaluations
+      budget:   { maxTraces: 60, windowMs: 60_000 },
+    },
+    onDecisionTraceAsync: async (evt) => {
+      await analyticsClient.ingest("govplane.trace", evt);
+    },
+    queueMax:   1000,
+    dropPolicy: "drop_new",
+  },
+});
+
+const result = client.evaluateWithTrace({ target, context });
+if (result.trace) {
+  console.log(result.trace.summary);
+  console.log(result.trace.winner);
 }
 ```
 
-### Debug (Forced)
+### Debug (forced)
 
-```ts
-engine.evaluateWithTrace(
+```typescript
+const result = client.evaluateWithTrace(
   { target, context },
-  { force: true, mode: "full" }
+  { level: "full", force: true },   // bypass sampling and budget
 );
 ```
 
-### Trace Guarantees
+| Level | Behaviour |
+|---|---|
+| `"off"` | No trace computed. Equivalent to `evaluate()`. |
+| `"errors"` | Trace attached only on `deny` or `kill_switch`. Compact format. |
+| `"sampled"` | Trace attached probabilistically by `sampling` rate and budget. Compact format. |
+| `"full"` | Always attempted (budget permitting). Includes complete per-rule list. |
+
+### Trace sinks
+
+Both synchronous (`onDecisionTrace`) and async (`onDecisionTraceAsync`) sinks are supported. Async evaluations are buffered internally and never block evaluation. Drain on shutdown with `client.flushTraces()`.
+
+### Trace guarantees
 
 - No rule bodies
 - No context values
@@ -295,68 +441,106 @@ engine.evaluateWithTrace(
 
 ---
 
-## Async Trace Sink
-
-```ts
-engine.setTraceSink(
-  createAsyncTraceSink({
-    maxQueue: 100,
-    drop: "drop_new",
-    sink: async (event) => {
-      await fetch("https://trace-endpoint", {
-        method: "POST",
-        body: JSON.stringify(event)
-      });
-    }
-  })
-);
-```
+## Runtime Incident Controls
 
-The sink:
-- Never blocks evaluation
-- Never throws
-- Drops safely under pressure
+Govplane provides **passive incident controls** that allow operators to respond to incidents without exposing endpoints, handling PII, or recompiling application code.
 
----
+| Mechanism | Restart Required | Hot | Recommended |
+|---|---|---|---|
+| Environment Variable (`GP_RUNTIME_INCIDENT=1`) | Usually yes | No | Yes |
+| File-based hot reload (`incidentFilePath`) | No | Yes | **Primary** |
+| POSIX Signal (`SIGUSR1`) | No | Yes | Optional |
 
-## What This SDK Does NOT Do
+```typescript
+const client = new RuntimeClient({
+  ...
+  incidentFilePath:   "/etc/govplane/incident.json",
+  incidentFilePollMs: 1000,
+  incidentSignal:     "SIGUSR1",
+});
+```
 
-- ❌ No HTTP middleware
-- ❌ No inbound endpoints
-- ❌ No request interception
-- ❌ No PII handling
-- ❌ No policy authoring
-- ❌ No dynamic code execution
+Incident file format:
+```json
+{
+  "burst":           true,
+  "burstDurationMs": 60000,
+  "burstPollMs":     200,
+  "refreshNow":      true
+}
+```
+
+See [Incident Playbook](docs/operations/Govplane_Incident_Playbook.md) and [Incident Controls Reference](docs/operations/Govplane_Runtime_Incident_Controls.md) for step-by-step procedures.
 
 ---
 
-## Security Notes
+## Using `createPolicyEngine` Directly
 
-- Runtime keys are **read-only**
-- Keys are scoped by org / project / env
-- Bundles are immutable
-- SDK cannot modify state
-- Safe to embed in critical paths
+If you manage the bundle yourself (loaded from a file, injected from config), you can use the engine without `RuntimeClient`:
+
+```typescript
+import { createPolicyEngine } from "@govplane/runtime-sdk";
+import { readFileSync } from "node:fs";
+
+const bundle = JSON.parse(readFileSync("bundle.json", "utf8"));
 
-### Threat Model
+const engine = createPolicyEngine({
+  getBundle:         () => bundle,
+  parseCustomEffect: true,
+  contextPolicy: {
+    allowedKeys:        ["plan", "role"],
+    maxStringLen:       64,
+    maxArrayLen:        10,
+    blockLikelyPiiKeys: true,
+  },
+});
 
-Please refer to the [Govplane Runtime SDK Threat Model & Security Guarantees](docs/security/Govplane_Threat_Model.md) for a detailed analysis.
+const result = engine.evaluate({ target, context });
+```
 
 ---
 
-## Performance Notes
+## What This SDK Does NOT Do
 
-- Designed for second-level polling
-- Suitable for APIs, workers, gateways
-- Not intended for browser usage
+- No HTTP middleware
+- No inbound endpoints
+- No request interception
+- No PII handling or storage
+- No policy authoring
+- No dynamic code execution
+- No rate-limit counter maintenance
 
 ---
 
-## Versioning & Compatibility
+## Security Notes
+
+- Runtime keys are **read-only** and scoped by org / project / env
+- Bundles are immutable — the SDK cannot modify control-plane state
+- Context validation and PII heuristic blocking are on by default
+- Safe to embed in critical paths
+
+See [Govplane Runtime SDK Threat Model](docs/security/Govplane_Threat_Model.md) for a full security analysis.
+
+---
 
-- Bundles are versioned (`schemaVersion`)
-- Current version: `RuntimeBundleV1`
-- Future versions will be backward-compatible
+## Documentation
+
+| Topic | Link |
+|---|---|
+| Installation & Quick Start | [docs/installation/GettingStarted.md](docs/installation/GettingStarted.md) |
+| Evaluating Decisions | [docs/usage/Evaluate.md](docs/usage/Evaluate.md) |
+| Effect Types | [docs/usage/Effects.md](docs/usage/Effects.md) |
+| Custom Effects | [docs/usage/CustomEffect.md](docs/usage/CustomEffect.md) |
+| Conditional Rules | [docs/usage/ConditionalRules.md](docs/usage/ConditionalRules.md) |
+| Policy Defaults | [docs/usage/PolicyDefaults.md](docs/usage/PolicyDefaults.md) |
+| Context Policy & PII Safety | [docs/usage/ContextPolicy.md](docs/usage/ContextPolicy.md) |
+| Bundle Lifecycle | [docs/usage/BundleLifecycle.md](docs/usage/BundleLifecycle.md) |
+| Decision Tracing | [docs/usage/DecisionTrace.md](docs/usage/DecisionTrace.md) |
+| Configuration Reference | [docs/reference/Configuration.md](docs/reference/Configuration.md) |
+| Types & Interfaces | [docs/reference/TypesAndInterfaces.md](docs/reference/TypesAndInterfaces.md) |
+| Incident Playbook | [docs/operations/Govplane_Incident_Playbook.md](docs/operations/Govplane_Incident_Playbook.md) |
+| Incident Controls Reference | [docs/operations/Govplane_Runtime_Incident_Controls.md](docs/operations/Govplane_Runtime_Incident_Controls.md) |
+| Threat Model | [docs/security/Govplane_Threat_Model.md](docs/security/Govplane_Threat_Model.md) |
 
 ---