arkgate 4.8.6 → 4.8.8

package/dist/{types-BuM8WNqe.d.ts → types-BK47clMl.d.ts}

@@ -1,4 +1,4 @@
-import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-dy5PfTqS.js';
+import { a as ArkConfigRule, f as ArkConfigLayer, A as ArkConfig } from './configTypes-0eHpocR3.js';
 
 /**
  * Policy types for the Ark kernel.

package/dist/{types-DrqsOiTY.d.ts → types-DxvmJO-D.d.ts}

@@ -1,4 +1,4 @@
-import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-BuM8WNqe.js';
+import { i as Policy, P as PolicyViolation, I as IntentName, j as IntentCreator, k as IntentRelationship, b as ArchitectureProfile, D as DomainEvent, E as EventMetadata, h as PolicyEnforcementMode, A as ArchitectureLayer, c as ArchitectureRule, d as ArkCheckConfig } from './types-BK47clMl.js';
 
 /**
  * PolicyEngine
@@ -1030,8 +1030,67 @@ declare const ARK_RUN_INSPECTOR_DEFAULT_PORT = 0;
 declare const ARK_RUN_INSPECTOR_SNAPSHOT_PATH = "/snapshot";
 declare const ARK_RUN_INSPECTOR_EVENTS_PATH = "/events";
 declare const ARK_RUN_INSPECTOR_GRAPH_PATH = "/graph";
+declare const ARK_RUN_INSPECTOR_OUTBOX_PATH = "/outbox";
+declare const ARK_RUN_INSPECTOR_WORKFLOWS_PATH = "/workflows";
 declare const ARK_RUN_INSPECTOR_SSE_EVENT = "snapshot";
 declare const ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK: "in-process-local";
+/** Server-side sample cap for outbox/workflows monitors (DoS floor). */
+declare const ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT = 32;
+/** Outbox statuses the Queues monitor surfaces (dispatched is omitted). */
+declare const ARK_RUN_INSPECTOR_OUTBOX_MONITOR_STATUSES: readonly ["pending", "failed"];
+type ArkRunInspectorOutboxMonitorStatus = (typeof ARK_RUN_INSPECTOR_OUTBOX_MONITOR_STATUSES)[number];
+type ArkRunInspectorStoreDurabilityKind = 'memory' | 'durable';
+type ArkRunInspectorStoreRole = 'outbox' | 'audit' | 'workflow';
+type ArkRunInspectorStoreDurability = {
+    role: ArkRunInspectorStoreRole;
+    id: string;
+    kind: ArkRunInspectorStoreDurabilityKind;
+};
+type ArkRunInspectorHardeningDurability = {
+    stores: ArkRunInspectorStoreDurability[];
+};
+type ArkRunInspectorHardening = {
+    durability: ArkRunInspectorHardeningDurability;
+};
+type ArkRunInspectorOutboxRecordSummary = {
+    id: string;
+    status: ArkRunInspectorOutboxMonitorStatus;
+    attempts: number;
+    intent?: string;
+    error?: string;
+    updatedAt?: string;
+};
+type ArkRunInspectorOutboxMonitor = {
+    available: boolean;
+    pendingCount: number;
+    failedCount: number;
+    pending: ArkRunInspectorOutboxRecordSummary[];
+    failed: ArkRunInspectorOutboxRecordSummary[];
+    /** Cap applied to pending/failed sample arrays (counts remain accurate). */
+    sampleLimit: number;
+};
+type ArkRunInspectorWorkflowSummary = {
+    id: string;
+    name: string;
+    status: string;
+    currentStep?: string;
+    error?: string;
+};
+type ArkRunInspectorWorkflowsMonitor = {
+    available: boolean;
+    total: number;
+    runningCount: number;
+    compensatingCount: number;
+    failedCount: number;
+    pendingCount: number;
+    workflows: ArkRunInspectorWorkflowSummary[];
+    /** Cap applied to workflows sample array (counts remain accurate). */
+    sampleLimit: number;
+};
+type ArkRunInspectorMonitorBuildOptions = {
+    /** Bound samples; clamped to 0…ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT. Default 32. */
+    sampleLimit?: number;
+};
 declare class ArkRunInspectorProductionError extends Error {
     constructor();
 }
@@ -1060,6 +1119,12 @@ type ArkRunInspectorSnapshot = {
     package: DependencyInformationPackage;
     transport: ArkRunInspectorTransportFacts;
     observability: unknown;
+    /** Explicit store durability facts from real kernel ports (never component-id inference). */
+    hardening: ArkRunInspectorHardening;
+    /** Optional OD04 queue facts when the caller supplies them (endpoints preferred). */
+    outbox?: ArkRunInspectorOutboxMonitor;
+    /** Optional OD04 workflow facts when the caller supplies them (endpoints preferred). */
+    workflows?: ArkRunInspectorWorkflowsMonitor;
 };
 type ArkRunInspectorBindInput = {
     host?: unknown;
@@ -1075,11 +1140,34 @@ type ArkRunInspectorSnapshotInput = {
     observability?: unknown;
     ephemeralDefault?: unknown;
     brokerBound?: unknown;
+    hardening?: unknown;
+    outbox?: unknown;
+    workflows?: unknown;
 };
 declare function isArkRunInspectorProductionEnv(nodeEnv: unknown): boolean;
 declare function isArkRunInspectorLoopbackHost(host: unknown): boolean;
 declare function resolveArkRunInspectorBind(input?: ArkRunInspectorBindInput): ArkRunInspectorBind;
 declare function arkRunInspectorUrl(host: string, port: number, path: string): string;
+/**
+ * Classify a store port by constructor / declared id. `InMemory*` → memory; else durable.
+ */
+declare function classifyArkRunInspectorStoreDurability(id: unknown, role: ArkRunInspectorStoreRole): ArkRunInspectorStoreDurability;
+/**
+ * Build hardening.durability facts from explicit store rows (not package.components).
+ */
+declare function buildArkRunInspectorHardening(input?: unknown): ArkRunInspectorHardening;
+/**
+ * Sanitize EventBufferStore.list rows into pending/failed monitor facts (no payloads).
+ * Counts cover the full input; sample arrays are capped at sampleLimit (≤32).
+ */
+declare function buildArkRunInspectorOutboxMonitor(records?: unknown, options?: ArkRunInspectorMonitorBuildOptions): ArkRunInspectorOutboxMonitor;
+declare function unavailableArkRunInspectorOutboxMonitor(): ArkRunInspectorOutboxMonitor;
+/**
+ * Sanitize WorkflowEngine.list rows into monitor facts (id/name/status/step/error only).
+ * Counts cover the full input; the workflows sample is capped at sampleLimit (≤32).
+ */
+declare function buildArkRunInspectorWorkflowsMonitor(snapshots?: unknown, options?: ArkRunInspectorMonitorBuildOptions): ArkRunInspectorWorkflowsMonitor;
+declare function unavailableArkRunInspectorWorkflowsMonitor(): ArkRunInspectorWorkflowsMonitor;
 declare function buildArkRunInspectorSnapshot(input?: ArkRunInspectorSnapshotInput): ArkRunInspectorSnapshot;
 declare function formatArkRunInspectorSseEvent(snapshot: unknown): string;
 
@@ -1107,6 +1195,8 @@ type ArkRunInspectorHandle = {
     snapshotUrl: string;
     eventsUrl: string;
     graphUrl: string;
+    outboxUrl: string;
+    workflowsUrl: string;
     close(): Promise<void>;
 };
 
@@ -1125,6 +1215,20 @@ type StartArkRunInspectorOptions = {
 type ArkRunInspectorSource = {
     getInspectorSnapshot(bind: ArkRunInspectorBind): ArkRunInspectorSnapshot;
     requestGraph(query?: ArkRunGraphQuery): ArkRunGraph;
+    /** OD04: pending/failed outbox summaries (EventBufferStore.list). */
+    listInspectorOutbox?(): Promise<ArkRunInspectorOutboxMonitor>;
+    /** OD04: workflow/saga summaries (WorkflowEngine.list). */
+    listInspectorWorkflows?(): Promise<ArkRunInspectorWorkflowsMonitor>;
+    /** Duck-typed kernel ports when explicit list* helpers are absent. */
+    outbox?: {
+        list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
+    };
+    eventBuffer?: {
+        list(status?: 'pending' | 'dispatched' | 'failed'): Promise<unknown[]>;
+    };
+    workflowEngine?: {
+        list(workflowName?: string): Promise<unknown[]>;
+    };
 };
 declare function startArkRunInspector(source: ArkRunInspectorSource, options?: StartArkRunInspectorOptions): Promise<ArkRunInspectorHandle>;
 
@@ -1249,4 +1353,4 @@ interface CreateArkKernelFromConfigOptions extends Omit<CreateArkKernelOptions,
 }
 type ArkKernelConfig = ArkCheckConfig;
 
-export { ARK_RUN_INSPECTOR_EVENTS_PATH as $, type ArkKernel as A, type OutboxStatus as B, type CreateArkKernelOptions as C, type DefineIntentOptions as D, type EventContractRegistry as E, type OutboxRecord as F, type GraphEdge as G, type ObservabilityDriftReport as H, IntentRegistry as I, ARK_RUN_COMPONENT_LIFETIMES as J, ARK_RUN_EPHEMERAL_DEFAULT as K, ARK_RUN_GRAPH_DEFAULT_SLICE as L, type MetadataRegistry as M, ARK_RUN_GRAPH_NODE_KINDS as N, type ObservabilityReporter as O, type ProjectionRegistry as P, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as Q, type ReadModelStore as R, type SagaContext as S, type TraceRecordType as T, ARK_RUN_GRAPH_SCHEMA_VERSION as U, ARK_RUN_GRAPH_SLICES as V, type WorkflowStore as W, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as X, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as Y, ARK_RUN_INSPECTOR_DEFAULT_HOST as Z, ARK_RUN_INSPECTOR_DEFAULT_PORT as _, type DependencyGraph as a, InvalidArkRunSendOptionError as a$, ARK_RUN_INSPECTOR_GRAPH_PATH as a0, ARK_RUN_INSPECTOR_SCHEMA_VERSION as a1, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as a2, ARK_RUN_INSPECTOR_SSE_EVENT as a3, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as a4, ARK_RUN_TRANSPORT_KINDS as a5, type ArkManifestArchitecture as a6, type ArkManifestData as a7, type ArkManifestEntityLink as a8, type ArkManifestGraph as a9, type ArkRunInspectorSnapshotInput as aA, type ArkRunInspectorSource as aB, type ArkRunInspectorTransportFacts as aC, type ArkRunPublisher as aD, type ArkRunRegisterOptions as aE, type ArkRunRegistrationHandle as aF, type ArkRunSendOptions as aG, type ArkRunSendPlan as aH, type ArkRunSendPlanInput as aI, type ArkRunSendResult as aJ, type ArkRunTransportKind as aK, type AuditRecordInput as aL, type AuditRecordType as aM, type EntityMeta as aN, type EventContractIssue as aO, type EventHandler as aP, type EventInterceptionInfo as aQ, type EventInterceptor as aR, type EventInterceptorContext as aS, type EventPayloadPatch as aT, type EventPayloadSchema as aU, type EventPublisher as aV, type EventSchemaField as aW, type EventSchemaFieldType as aX, type FieldMeta as aY, type GraphNode as aZ, InvalidArkRunGraphQueryError as a_, type ArkManifestIntent as aa, type ArkManifestPolicy as ab, type ArkManifestProjection as ac, type ArkRunBrokerAdapter as ad, type ArkRunComponentLifetime as ae, type ArkRunDeliveredVia as af, type ArkRunExtendedInfo as ag, type ArkRunGraph as ah, type ArkRunGraphEdge as ai, type ArkRunGraphEdgeKind as aj, type ArkRunGraphMatch as ak, type ArkRunGraphMatchInput as al, type ArkRunGraphNode as am, type ArkRunGraphNodeKind as an, type ArkRunGraphProcessEdgeKind as ao, type ArkRunGraphQuery as ap, type ArkRunGraphResolvedQuery as aq, type ArkRunGraphSlice as ar, type ArkRunGraphTechnicalEdgeKind as as, type ArkRunInformationPackageComponent as at, type ArkRunInspectorBind as au, ArkRunInspectorBindError as av, type ArkRunInspectorBindInput as aw, type ArkRunInspectorHandle as ax, ArkRunInspectorProductionError as ay, type ArkRunInspectorSnapshot as az, type AuditStore as b, type ObservabilityFlow as b0, type ObservedLayerFlowMode as b1, type OutboxStore as b2, type PolicyEvaluationResult as b3, type ProjectionCheckpoint as b4, type ProjectionDefinition as b5, type PublishedEventRecord as b6, type RetryPolicy as b7, type SagaStatus as b8, type SagaStep as b9, type StartArkRunInspectorOptions as ba, type TraceSink as bb, type Unsubscribe as bc, type WorkflowDefinition as bd, type WorkflowStatus as be, type WorkflowStep as bf, appendDecisionTape as bg, arkRunGraphQueryFromSearchParams as bh, arkRunInspectorUrl as bi, buildArkRunInspectorSnapshot as bj, buildDependencyInformationPackage as bk, closeArkRunGraphQuery as bl, closedArkRunEphemeral as bm, closedArkRunTransportKind as bn, formatArkRunGraphMermaid as bo, formatArkRunInspectorSseEvent as bp, isArkRunInspectorLoopbackHost as bq, isArkRunInspectorProductionEnv as br, requestArkRunGraph as bs, resolveArkRunInspectorBind as bt, resolveArkRunSendPlan as bu, startArkRunInspector as bv, type AuditRecord as c, type AuditQuery as d, type CreateAuditTrailOptions as e, type AuditTrail as f, type EventContract as g, type EventContractValidationResult as h, type CreateProjectionRegistryOptions as i, type EventBufferStore as j, type EventBufferRecord as k, type EventBufferStatus as l, type EventBusOptions as m, type EventBus as n, type CreateObservabilityReporterOptions as o, PolicyEngine as p, type ArkManifest as q, type WorkflowSnapshot as r, type SagaDefinition as s, type CreateWorkflowEngineOptions as t, type SagaInstance as u, type WorkflowEngine as v, type DependencyInformationPackage as w, type ArkKernelConfig as x, type CreateArkKernelFromConfigOptions as y, type TraceRecord as z };
+export { ARK_RUN_INSPECTOR_EVENTS_PATH as $, type ArkKernel as A, type OutboxStatus as B, type CreateArkKernelOptions as C, type DefineIntentOptions as D, type EventContractRegistry as E, type OutboxRecord as F, type GraphEdge as G, type ObservabilityDriftReport as H, IntentRegistry as I, ARK_RUN_COMPONENT_LIFETIMES as J, ARK_RUN_EPHEMERAL_DEFAULT as K, ARK_RUN_GRAPH_DEFAULT_SLICE as L, type MetadataRegistry as M, ARK_RUN_GRAPH_NODE_KINDS as N, type ObservabilityReporter as O, type ProjectionRegistry as P, ARK_RUN_GRAPH_PROCESS_EDGE_KINDS as Q, type ReadModelStore as R, type SagaContext as S, type TraceRecordType as T, ARK_RUN_GRAPH_SCHEMA_VERSION as U, ARK_RUN_GRAPH_SLICES as V, type WorkflowStore as W, ARK_RUN_GRAPH_TECHNICAL_EDGE_KINDS as X, ARK_RUN_INFORMATION_PACKAGE_SCHEMA_VERSION as Y, ARK_RUN_INSPECTOR_DEFAULT_HOST as Z, ARK_RUN_INSPECTOR_DEFAULT_PORT as _, type DependencyGraph as a, type EventContractIssue as a$, ARK_RUN_INSPECTOR_GRAPH_PATH as a0, ARK_RUN_INSPECTOR_MONITOR_SAMPLE_LIMIT as a1, ARK_RUN_INSPECTOR_OUTBOX_PATH as a2, ARK_RUN_INSPECTOR_SCHEMA_VERSION as a3, ARK_RUN_INSPECTOR_SNAPSHOT_PATH as a4, ARK_RUN_INSPECTOR_SSE_EVENT as a5, ARK_RUN_INSPECTOR_TRANSPORT_FALLBACK as a6, ARK_RUN_INSPECTOR_WORKFLOWS_PATH as a7, ARK_RUN_TRANSPORT_KINDS as a8, type ArkManifestArchitecture as a9, type ArkRunInspectorHandle as aA, type ArkRunInspectorHardening as aB, type ArkRunInspectorHardeningDurability as aC, type ArkRunInspectorMonitorBuildOptions as aD, type ArkRunInspectorOutboxMonitor as aE, type ArkRunInspectorOutboxRecordSummary as aF, ArkRunInspectorProductionError as aG, type ArkRunInspectorSnapshot as aH, type ArkRunInspectorSnapshotInput as aI, type ArkRunInspectorSource as aJ, type ArkRunInspectorStoreDurability as aK, type ArkRunInspectorStoreDurabilityKind as aL, type ArkRunInspectorStoreRole as aM, type ArkRunInspectorTransportFacts as aN, type ArkRunInspectorWorkflowSummary as aO, type ArkRunInspectorWorkflowsMonitor as aP, type ArkRunPublisher as aQ, type ArkRunRegisterOptions as aR, type ArkRunRegistrationHandle as aS, type ArkRunSendOptions as aT, type ArkRunSendPlan as aU, type ArkRunSendPlanInput as aV, type ArkRunSendResult as aW, type ArkRunTransportKind as aX, type AuditRecordInput as aY, type AuditRecordType as aZ, type EntityMeta as a_, type ArkManifestData as aa, type ArkManifestEntityLink as ab, type ArkManifestGraph as ac, type ArkManifestIntent as ad, type ArkManifestPolicy as ae, type ArkManifestProjection as af, type ArkRunBrokerAdapter as ag, type ArkRunComponentLifetime as ah, type ArkRunDeliveredVia as ai, type ArkRunExtendedInfo as aj, type ArkRunGraph as ak, type ArkRunGraphEdge as al, type ArkRunGraphEdgeKind as am, type ArkRunGraphMatch as an, type ArkRunGraphMatchInput as ao, type ArkRunGraphNode as ap, type ArkRunGraphNodeKind as aq, type ArkRunGraphProcessEdgeKind as ar, type ArkRunGraphQuery as as, type ArkRunGraphResolvedQuery as at, type ArkRunGraphSlice as au, type ArkRunGraphTechnicalEdgeKind as av, type ArkRunInformationPackageComponent as aw, type ArkRunInspectorBind as ax, ArkRunInspectorBindError as ay, type ArkRunInspectorBindInput as az, type AuditStore as b, type EventHandler as b0, type EventInterceptionInfo as b1, type EventInterceptor as b2, type EventInterceptorContext as b3, type EventPayloadPatch as b4, type EventPayloadSchema as b5, type EventPublisher as b6, type EventSchemaField as b7, type EventSchemaFieldType as b8, type FieldMeta as b9, buildDependencyInformationPackage as bA, classifyArkRunInspectorStoreDurability as bB, closeArkRunGraphQuery as bC, closedArkRunEphemeral as bD, closedArkRunTransportKind as bE, formatArkRunGraphMermaid as bF, formatArkRunInspectorSseEvent as bG, isArkRunInspectorLoopbackHost as bH, isArkRunInspectorProductionEnv as bI, requestArkRunGraph as bJ, resolveArkRunInspectorBind as bK, resolveArkRunSendPlan as bL, startArkRunInspector as bM, unavailableArkRunInspectorOutboxMonitor as bN, unavailableArkRunInspectorWorkflowsMonitor as bO, type GraphNode as ba, InvalidArkRunGraphQueryError as bb, InvalidArkRunSendOptionError as bc, type ObservabilityFlow as bd, type ObservedLayerFlowMode as be, type OutboxStore as bf, type PolicyEvaluationResult as bg, type ProjectionCheckpoint as bh, type ProjectionDefinition as bi, type PublishedEventRecord as bj, type RetryPolicy as bk, type SagaStatus as bl, type SagaStep as bm, type StartArkRunInspectorOptions as bn, type TraceSink as bo, type Unsubscribe as bp, type WorkflowDefinition as bq, type WorkflowStatus as br, type WorkflowStep as bs, appendDecisionTape as bt, arkRunGraphQueryFromSearchParams as bu, arkRunInspectorUrl as bv, buildArkRunInspectorHardening as bw, buildArkRunInspectorOutboxMonitor as bx, buildArkRunInspectorSnapshot as by, buildArkRunInspectorWorkflowsMonitor as bz, type AuditRecord as c, type AuditQuery as d, type CreateAuditTrailOptions as e, type AuditTrail as f, type EventContract as g, type EventContractValidationResult as h, type CreateProjectionRegistryOptions as i, type EventBufferStore as j, type EventBufferRecord as k, type EventBufferStatus as l, type EventBusOptions as m, type EventBus as n, type CreateObservabilityReporterOptions as o, PolicyEngine as p, type ArkManifest as q, type WorkflowSnapshot as r, type SagaDefinition as s, type CreateWorkflowEngineOptions as t, type SagaInstance as u, type WorkflowEngine as v, type DependencyInformationPackage as w, type ArkKernelConfig as x, type CreateArkKernelFromConfigOptions as y, type TraceRecord as z };

package/docs/README.md

@@ -6,6 +6,14 @@
 Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
 is just documentation.
 
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
 Pick your path. Skip everything else.
 
 | You are… | Start here |
@@ -58,14 +66,14 @@ These are **not** the day-to-day product path. They stay in the repo for evidenc
 | Area | Path |
 |------|------|
 | Release notes (by version) | [releases/](releases/) · npm [CHANGELOG.md](../CHANGELOG.md) (Unreleased + 4.6.x) · [pre-4.6 archive](archive/CHANGELOG-pre-4.6.md) |
-| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN17` done; shipped **4.7.0** + companion **4.7.4**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). [arkorder](plans/arkorder/README.md) (Phase OR; `OR01`–`OR07` done; shipped **4.8.0**; extra **inside** package `arkgate` as `arkgate/order`; ADRs [0027](adr/0027-arkorder-gated-extra-plane.md)–[0031](adr/0031-one-package-extras-deprecate-companion.md)). [arkorder-arkrun](plans/arkorder-arkrun/README.md) (Phase XP; `XP01`–`XP08` done; shipped **4.8.5**; ADR [0033](adr/0033-arkorder-runtime-half-is-arkrun.md)). [arkorder-valve-loop](plans/arkorder-valve-loop/README.md) (Phase LV; `LV01`–`LV09` done on tree; **4.8.6** prepared; [ADR 0034](adr/0034-arkorder-valved-loop.md); does not close K01). |
+| Epic plans | [plans/](plans/) — maintainer seeds, not required to use the package. Live: [alive-in-six-months](plans/alive-in-six-months/README.md) (`AL01`–`AL04` done; `AL05` parked). [arkrun](plans/arkrun/README.md) (Phase RN; `RN01`–`RN17` done; shipped **4.7.0** + companion **4.7.4**; ADRs [0020](adr/0020-arkrun-gated-extra-plane.md)–[0024](adr/0024-arkrun-transport-ports.md) accepted). [one-catalog-one-root](plans/one-catalog-one-root/README.md) (Phase HS; `HS01`–`HS05` done; shipped **4.7.1**). [arkorder](plans/arkorder/README.md) (Phase OR; `OR01`–`OR07` done; shipped **4.8.0**; extra **inside** package `arkgate` as `arkgate/order`; ADRs [0027](adr/0027-arkorder-gated-extra-plane.md)–[0031](adr/0031-one-package-extras-deprecate-companion.md)). [arkorder-arkrun](plans/arkorder-arkrun/README.md) (Phase XP; `XP01`–`XP08` done; shipped **4.8.5**; ADR [0033](adr/0033-arkorder-runtime-half-is-arkrun.md)). [arkorder-valve-loop](plans/arkorder-valve-loop/README.md) (Phase LV; `LV01`–`LV09` done; shipped **4.8.6**; [ADR 0034](adr/0034-arkorder-valved-loop.md); does not close K01). [layer-description-projection](plans/layer-description-projection/README.md) (Phase LD; `LD01`–`LD06` done; shipped **4.8.7**; [ADR 0035](adr/0035-layer-description-projection.md); project `layers[].description`; no schema bump). [observability-tui](plans/observability-tui/README.md) (`OD01`–`OD04` done on the **4.8.8 prepared tree**; not yet published; in-memory honesty retained). |
 | Claims audit | [audit/claims-matrix.md](audit/claims-matrix.md) |
 | Field adoption kit (scaffolding, not closed) | [field/](field/) |
 | Runtime hardening (experimental) | [production-hardening.md](production-hardening.md) |
 
-Current published: [releases/4.8.5.md](releases/4.8.5.md) (`arkgate@4.8.5` on npm `latest`; does not close `K01`).
-Tree: [releases/4.8.6.md](releases/4.8.6.md) (`arkgate@4.8.6` prepared).
-Prior: [releases/4.8.4.md](releases/4.8.4.md) · [releases/4.8.3.md](releases/4.8.3.md) · [releases/4.8.2.md](releases/4.8.2.md) · [releases/4.8.1.md](releases/4.8.1.md) · [4.8.0](releases/4.8.0.md) · [4.7.6](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
+Prepared: [releases/4.8.8.md](releases/4.8.8.md) (`arkgate@4.8.8`; not published).
+Current published: [releases/4.8.7.md](releases/4.8.7.md) (`arkgate@4.8.7` on npm `latest`; does not close `K01`).
+Prior: [releases/4.8.6.md](releases/4.8.6.md) · [releases/4.8.5.md](releases/4.8.5.md) · [releases/4.8.4.md](releases/4.8.4.md) · [releases/4.8.3.md](releases/4.8.3.md) · [releases/4.8.2.md](releases/4.8.2.md) · [releases/4.8.1.md](releases/4.8.1.md) · [4.8.0](releases/4.8.0.md) · [4.7.6](releases/4.7.6.md) · [4.7.5](releases/4.7.5.md) · [4.7.4](releases/4.7.4.md) · [4.7.3](releases/4.7.3.md) · [4.7.2](releases/4.7.2.md) · [4.7.1](releases/4.7.1.md) · [4.7.0](releases/4.7.0.md) · [4.6.7](releases/4.6.7.md) · [4.6.6](releases/4.6.6.md) · [4.6.5](releases/4.6.5.md) · [4.6.4](releases/4.6.4.md) · [4.6.3](releases/4.6.3.md) · [4.6.2](releases/4.6.2.md) · [4.6.1](releases/4.6.1.md) · [4.6.0](releases/4.6.0.md).
 Older notes: [releases/](releases/). Config: [configuration.md](configuration.md).
 
 ---

package/docs/agent-guide.md

@@ -2,8 +2,20 @@
 
 **Write. Check. Ship.**
 **When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
+
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
+is just documentation.
+
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
 This guide is the **develop** reference for agents and codegen: write hooks, advisory MCP tools,
-CI, and `/ark-*` skills. Not an API Gateway. Not a folder linter.
+CI, and `/ark-*` skills.
 
 - Product path (anyone): [use.md](use.md)  
 - Integration overview: [develop.md](develop.md)  
@@ -1413,3 +1425,26 @@ doctor → compact router (and `/ark-autopilot` only after the skill pack).
 6. **Wire** relationships via `registry.define(..., { dependsOn, produces })`
 7. **Register** event contracts before publishing in strict mode
 8. **Observe** runtime via `bus.getTrace()`, `auditTrail.query()`, outbox records, projection checkpoints, and `ark.observability.report()`
+9. **Optional loopback inspector** via `ark.startInspector()` — JSON facts only (see below); poll with `ark-dashboard` / `arkgate-dashboard` when you want a terminal view
+
+### Dev inspector queue endpoints and dashboard bins
+
+`startInspector()` / `startArkRunInspector()` bind loopback only, refuse
+`NODE_ENV=production`, and lazy-load HTTP. The kernel exposes JSON monitor facts
+(snapshot / graph / queue endpoints) — not a TUI.
+
+| Method + path | Role |
+|---------------|------|
+| `GET /snapshot` (also `/`) | Information package + transport + observability snapshot |
+| `GET /events` | SSE of the same snapshot |
+| `GET /graph` | `requestGraph` slice (+ Mermaid helper) |
+| `GET /outbox` | Outbox monitor: `available`, `pendingCount`, `failedCount`, `pending[]` / `failed[]` row summaries (`id`, `status`, `attempts`, optional `intent` / `error` / `updatedAt`) — **no event payloads** |
+| `GET /workflows` | Workflows monitor: counts + `workflows[]` summaries (`id`, `name`, `status`, optional `currentStep` / `error`) |
+
+Dual package bins **`ark-dashboard`** and **`arkgate-dashboard`**
+(`bin/ark-dashboard.mjs`) poll `--url` (default `http://127.0.0.1:3000/snapshot`)
+and sibling `/outbox` + `/workflows` on an interval (`--interval`, 200–60000 ms).
+ANSI escape sequences + polling only — no React, Ink, or Blessed. Use
+`ark dashboard` / `arkgate dashboard` (passthrough to `bin/ark-dashboard.mjs`) or the
+dual bins `ark-dashboard` / `arkgate-dashboard`.
+Presentation stays in Tooling (`bin/`); do not couple a TUI into `src/kernel`.

package/docs/ai-gates.md

@@ -2,7 +2,19 @@
 
 **Write. Check. Ship.**
 **When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
-This page is host install depth (hooks / MCP / CI). Not an API Gateway. Not a folder linter.
+
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
+is just documentation.
+
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
+This page is host install depth (hooks / MCP / CI).
 
 This page is **develop** depth (install hooks/MCP/CI per host). Product path: [use.md](use.md) ·
 overview: [develop.md](develop.md) · hub: [README.md](README.md).

package/docs/arkorder.md

@@ -139,12 +139,18 @@ does not change `h(ξ)` fails closed (`ARKORDER_EMPTY_BLAST`).
 | `managedLayers` | Layers whose persistence writes of `xiKeys` are the skip |
 | `planeRoots` | Files allowed to call `createOrderPlane` |
 | `maxXiKeys` | Cap on ξ (default 7). Haken: few slow modes |
-| `xiKeys` | Optional 3–5 slow names. Empty → `ARKORDER_XI_FIELD_WRITE` silent |
+| `xiKeys` | Optional 3–5 slow names chosen by the modeller. Empty → `ARKORDER_XI_FIELD_WRITE` silent |
 
 Unknown keys fail closed. Empty `planeRoots` in `enforced` fails
 `ARKORDER_MISSING_PLANE`. Demotion or deletion is a policy-delta **weakening**.
 This library’s 4-layer authoring contract does **not** turn the extra on.
 
+The modeller names the keys. Empty blast is a mechanical rejection, but a large
+blast does not make `paid` independent of current state. Whether a candidate is
+entailed by current state remains a modeller and skill obligation. Invoices stay
+on ingest. A `paid` flag is not a fourth slow key: derive it from cash received
+against the invoice amount.
+
 ---
 
 ## Activation (same shape as ArkRun)
@@ -212,6 +218,10 @@ Durability (`K01`) stays parked. In-memory is the honesty line.
 - a degraded-mode contract (nothing can be down)
 
 If a “slow parameter” changes with every click, it is not an order parameter.
+A status you can recompute from data you already have is not a slow decision. Derive it. Do not freeze it. The check remains silent on semantic entailment.
+For example, cash arrives through ingest; `paid` is a conclusion derived from
+cash received against amount due, not a key to freeze or change with
+`proposeRelease`.
 
 The valved loop ships in **4.8.6** ([ADR 0034](adr/0034-arkorder-valved-loop.md)).
 In-memory `ReleaseStore` is **not** durable. Doctor / status `arkOrder` stays

package/docs/configuration.md

@@ -130,7 +130,8 @@ Top-level fields:
   Import `createOrderPlane` from `arkgate/order` (same package). Empty `planeRoots` in
   `enforced` mode fails closed (`ARKORDER_MISSING_PLANE`). `xiKeys` are the 3–5 slow
   names the product already knows (plan, protocol, cost-code bound). Empty `xiKeys`
-  leaves `ARKORDER_XI_FIELD_WRITE` silent. Membership ids are not keys. Factory options
+  leaves `ARKORDER_XI_FIELD_WRITE` silent. Membership ids and recomputable statuses
+  such as `paid` / `overdue` are not keys. Factory options
   `informationBudget`, `sigmaMaxAgeMs`, `store` (`ReleaseStore`), and capacity packs
   belong on `createOrderPlane`, not this extra object. Later ξ is `proposeRelease`
   then `apply`; `refreshSigma`; ingest residual `absorb | escalate_up | hold`.
@@ -144,7 +145,28 @@ name different factories: `arkRun.kernelRoots` (`compositionRoots` alias) vs
 
 Layer fields:
 
-- `name`, `patterns`, `exclude`, `description`
+- `name`, `patterns`, `exclude`
+- **`layers[].description`** (optional) — **app-context caption**: one product sentence for what
+  this folder is *in the app*, not architecture jargon. `/ark-place` prints it next to
+  the layer name and globs; doctor, coverage, and the HTML report show the same text.
+  Changing the sentence does **not** change `policyHash` (same strip as `stewards`) and
+  does **not** need a weakening ack. Absence is silent: never fails `--strict-config`,
+  never invents a doctor residual, never flips `valid`. Empty string is invalid JSON for
+  the field (`minLength: 1`). Compact starters may omit it. `/ark-adopt` writes it when
+  the product map or glossary names the house; it does not invent captions. No
+  `/ark-describe`.
+
+```json
+"layers": [
+  {
+    "name": "Application",
+    "patterns": ["src/application/**"],
+    "description": "Purchase requests — from asked to received."
+  }
+]
+```
+
+That sentence is product copy. Not “Rich domain model, business rules, and domain events.”
 - `intentPrefixes`, `forbiddenGlobals`, `mayImportInfrastructure`, `optional`
 - `reserved` / `allowEmpty` — future houses whose globs match nothing yet. `--strict-config` does not fail; `CONFIG_LAYER_PATTERN_NO_MATCHES` (typo warning) is skipped. A typo warning fires only when the glob is not reserved.
 - `capabilities: { deny: [...] }` — opt-in effect walls over the seven capability ids
@@ -353,7 +375,7 @@ changing either contract changes its hash and invalidates the acknowledgement.
 
 Optional `stewards` lists **GitHub handles or emails** who may **loosen** the contract or
 **grow** the baseline (`pedroknigge` or `pedroknigge@users.noreply.github.com` — not
-`Pedro Knigge`). The field is metadata — it does not change the policy hash. The lock
+`Pedro Knigge`). The field is metadata — it does not change the policy hash. `layers[].description` is stripped the same way (caption-only edits do not change `policyHash` and do not need a weakening ack; `contractHash` still fingerprints the raw config). The lock
 matches `--author`, then `GITHUB_ACTOR` / `ARK_STEWARD`, then `GIT_AUTHOR_EMAIL`. A
 noreply GitHub mail and the handle are the same person. Git `user.name` is not identity.
 

package/docs/develop.md

@@ -2,13 +2,20 @@
 
 **Write. Check. Ship.**
 
-For **developers** integrating ArkGate into a product repo: agents, CI, config, brownfield, and power tools.
+**When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
+
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
+is just documentation.
+
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
 
-When the agent writes a bad import, the write doesn’t land. The same check fails the pull
-request. Not an API Gateway. Not a folder linter. Without a required CI status,
-`ark.config.json` is just documentation. ArkGate is import rules. ArkRules, ArkRun,
-and ArkOrder are optional — policies, an experimental runtime, and the extra that
-stops slow product decisions being CRUD. Not a second install.
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
+For **developers** integrating ArkGate into a product repo: agents, CI, config, brownfield, and power tools.
 
 If you only want the happy path, start at [use.md](use.md). Optional ArkOrder
 (library + sensors, not a service): [arkorder.md](arkorder.md).

package/docs/enthusiast/README.md

@@ -1,8 +1,19 @@
 # ArkGate — enthusiast track
 
 **Write. Check. Ship.**
-When the agent writes a bad import, the write doesn’t land. The same check fails the pull
-request. Not an API Gateway. Not a folder linter.
+
+**When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
+
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
+is just documentation.
+
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
 
 Plain-language onboarding for builders who use AI agents but are not professional
 developers. This track follows [Diátaxis](https://diataxis.fr/): tutorial, how-to,

package/docs/package-surface.md

@@ -2,6 +2,18 @@
 
 **Write. Check. Ship.**
 **When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
+
+Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
+is just documentation.
+
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
 That is the product wedge (host hook + required CI). Skills name the next step after that.
 **Not the wedge:** the optional in-process **ArkRun** runtime (`arkgate/runtime`) and the
 optional **ArkOrder** pattern extra (`arkgate/order`).
@@ -25,7 +37,7 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 
 | Surface | How you use it | Stability notes |
 |---------|----------------|-----------------|
-| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`) | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). |
+| **CLI** | `arkgate` / `arkgate-check` (aliases `ark` / `ark-check`); optional ArkRun **`ark-dashboard`** / **`arkgate-dashboard`** | Flags and human text may improve; **JSON output shapes** for `--json` (check, doctor, plan, coverage, recommend, **status**, **agents-md**) are stable within a major. Additive fields OK; removals/renames are major. From 4.2, `--require-gates` implies strict config and verifies semantic Ark AGENTS, project-rooted MCP/compact Codex registration, and fail-closed CI rather than file presence alone. `ark status --json` is the unified status snapshot. `ark agents-md` is the version-matched agent projection (non-authoritative). **Dashboard bins** poll an ArkRun inspector snapshot (ANSI + interval polling; `--url` / `--interval`); they are not a gate verdict. The main CLI also accepts `ark dashboard` / `arkgate dashboard` as a passthrough to those bins. |
 | **Host write boundaries** | Generated trusted PreToolUse/preToolUse hooks + `ark-mcp --hook`; inspect with doctor/status | Hard is always operation-scoped and runtime-evidenced. From 4.6.3, Codex CLI and local ChatGPT Desktop/App Server can hard-block a complete `apply_patch` sent as `tool_input.command`; `.codex/hooks.json` on disk remains unverified until a fresh covered invocation. Hosted tools, specialized hook opt-outs, shell/direct writes, incomplete reconstruction, and humans rely on required CI. Repair envelopes may emit, but Codex reinjection is not guaranteed. |
 | **Programmatic gate API** | `import { analyzeProject, loadContract, createAICodeGate, ... } from 'arkgate'` | The root export is the static gate/config/analysis contract listed below. It intentionally contains no runtime-kernel implementation. |
 | **Improvement compass (4.4; status honesty 4.5)** | `ark-check --doctor --json` → `doctor.improvementCompass`; human doctor section **Improvement compass (not a score)**; HTML report `data-advisory="improvementCompass"`. **`ark status --json` / MCP `ark_status`** project a thin `improvementCompass` residual map with explicit honesty **`mode`**: `full` \| `subset` \| `unavailable` (always `notAScore: true`). When `mode` is `full`, status residual lens **ids** are a **subset of** doctor residual for the same facts (report snapshot stores the thin slice after `--report`). Incomplete or missing session facts → `subset` / `unavailable` + `reasonCode` / `reason` — **never invent green residual**. Residual never flips `valid` / strict-merge / `goal.met`. When status mode ≠ full, run doctor for full 15-lens detail. | Additive schema `1.0`. Closed **15** lens ids (`soc`, `cohesion`, `coupling`, `srp`, `dip`, `ocp`, `encapsulation`, `modularity`, `scalability`, `resilience`, `security`, `maintainability`, `testability`, `domain`, `stack`) with status `ok` \| `residual` \| `not-instrumented` \| `out-of-scope`, evidence refs, optional `nextAction`, capped `topResidual`, always **`notAScore: true`**. Projection from existing smells / walls / cohesion / ArkRules / design-weak only — **never** a gate input. Out-of-scope locked for scalability, resilience, and app security (no residual invent from missing SAST/APM). Root API: `buildImprovementCompass` / `IMPROVEMENT_LENS_IDS`; status: `projectStatusImprovementCompass` / `STATUS_COMPASS_MODES`. |
@@ -51,14 +63,15 @@ hardening guide remains repository-hosted rather than duplicated in the gate tar
 | **Report parity and snapshot evidence (4.2)** | `ark-check --report` → advisory sections (`data-advisory="contractHealth\|ambientState\|parseHealth\|arkRun"`, nested `governanceWeight`) + layer wall badges; `.ark/reports/*.json` | The report is a rendering of doctor truth. **Standing rule:** every doctor advisory ships with its report section — enforced by the `reportParity` guard, which enumerates the doctor's advisory keys and fails on any missing section. Snapshots add best-effort Git `HEAD`/branch/dirty provenance without a shell; unavailable Git is explicit. Evolution renders the Ark score delta only when both snapshots name the same ArkGate version, while retaining raw facts across versions. Thin `arkRun` on `latest.json` is `notAScore` residual honesty for `ark status`. |
 | **MCP project identity (4.2)** | `ark_identity`; `arkgate/schema/project-identity` or `arkgate/schema/ark.project-identity.schema.json`; root API constants/helpers/types | Schema `1.0`. `projectId` hashes canonical root + config path and stays stable across contract edits/restarts; runtime id/start time are separate. Every project-bound tool result and error carries `projectIdentity`, `binding` (`matched` / `unverified` / `mismatch`), and `authoritative`. Canonical out-of-root config/file evidence fails before project data. |
 | **MCP tools and compatibility resource** | `arkgate-mcp`; `ark_manifest`; `ark_status`; `ark://manifest` | Tool names and primary argument shapes are stable within a major. Every tool accepts additive `project.expectedRoot` / optional `expectedProjectId`. The initial handshake requires the exact project root; a contained descendant is authoritative only together with the matching project id. Legacy tool calls remain callable but `unverified` and non-authoritative. `ark_manifest` is the authoritative contract surface after binding. **`ark_status`** returns the status manifest envelope (parity with `ark status --json`). Standard `resources/read` cannot portably carry the expectation, so `ark://manifest` remains compatibility-only and always unverified/non-authoritative. The server never retargets from input. |
-| **`ark.config.json`** | Layer globs, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
+| **`ark.config.json`** | Layer globs, optional `layers[].description`, rules, include/exclude, forbiddenGlobals, intent prefixes, `peerIsolation`, `dynamicImportAllowlist`, `safety` thresholds; optional **`coverage`** controls (`testGlobs`, `maxFiles`); optional **`arkRules`** map (schema `1.1+`); optional **`arkRun`** extra (schema `1.2+`); optional **`arkOrder`** extra (schema `1.3+`) | Versioned by `schemaVersion`; unknown fields fail closed and migrations preserve the previous supported major. Absence of `coverage`, `arkRules`, `arkRun`, or `arkOrder` is byte-for-byte silent on Layers / ArkRules verdicts. Enforced extra teeth share the CLI / MCP / hook / preflight / CI verdict and arm only when the layer plane is classified (same ArkRules floor). |
+| **Layer caption (`layers[].description`, 4.8.7)** | Optional string on each layer. Projected onto `ark_place` / prepare-write / MCP place JSON, doctor JSON + human, coverage JSON, and the HTML Purpose column when present. `/ark-adopt` writes it from the product map or glossary; `/ark-place` prints it next to layer name + globs. | Existing optional field — **no `schemaVersion` bump**, no new key, no 14th skill. Copy is **app context** (a product sentence such as `Purchase requests — from asked to received.`), not architecture jargon. Stripped from `policyHash` like `stewards`; caption-only edits are neutral. Absence is silent: never a residual, never a score, never `--strict-config` fail, never flips `valid`. Compact starters may omit. |
 | **ArkRules inventory / under-contract (4.0; layer context 4.2)** | `ark-check --rules-inventory [--json]`; doctor `rulesUnderContract`; MCP `ark_rules_inventory` | Additive. Honest counts (inventoried / under-contract / frozen) — **never a score**. When configured layer evidence exists it overrides filename role guesses: a Domain file named `handler` is not a controller candidate. Test/fixture/seed/migration/exclusion surfaces plus narrow development-identity, PostgreSQL OID, and technical I/O constants are silent. Without layer evidence, backward-compatible path/content heuristics remain. Structure/invariant diagnostics use adapter `1.4` provenance. |
 | **`arkgate/schema/project-identity`** or **`arkgate/schema/ark.project-identity.schema.json`** | MCP canonical project, contract, runtime, expectation, and binding envelope | Schema `1.0`. Initial `expectedRoot` must be the exact project root. A contained descendant can match only when `expectedProjectId` is also present and correct; id-only matching stays non-authoritative. Mismatch codes are `PROJECT_ROOT_MISMATCH`, `PROJECT_ID_MISMATCH`, and `INVALID_PROJECT_EXPECTATION`. |
 | **Package pin dual-truth (4.0)** | doctor JSON `packageVersionTruth`; upgrade JSON/human note when pin behind CLI | Additive, advisory. Surfaces after `upgrade --no-install` when managed CLI is ahead of package.json. |
 | **Managed upgrade self-service honesty (4.5 / DF05)** | `ark upgrade [--json]` → `selfService` (+ human “Self-service honesty” lines) | Additive, advisory. Answers without a maintainer: write-path activation labels per selected host (`hard`\|`advisory`\|`unavailable`) and customized content-identity preserve (`customizedPaths` / `customizedContentPreserved`). Soft hosts never hard; upgrade never invents `hardWriteActive` from disk alone. Always `notAScore: true`. Not a gate input; not part of `planDigest`. |
 | **Product honesty readiness split (4.1.1)** | doctor JSON `productHonesty` | Additive. `unfinished` / `headline` / `primaryNextAction` / `reasonIds` remain; EH adds `contractReadiness` (`ready`\|`partial`\|`not-ready`), `localWriteBoundary` (`advisory`\|`hard`\|`unverified`\|`unknown`), `architectureReasonIds`, `environmentResidualIds` / `environmentResiduals`. Soft-write hosts stay in evidence without alone forcing global **Not finished**. `notAScore: true` always. |
 | **Policy transition analysis (3.1.0)** | `analyzePolicyDelta(...)`; MCP `ark_policy_delta`; CLI `--policy-base` / `--policy-base-ref` / `--policy-ack`; check JSON `policyDelta` | Additive schema `1.0`. Classifications and finding ids are deterministic. Weakening/judgment requires an acknowledgement bound to both policy hashes and the exact blocking finding set. |
-| **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources. `stewards` is excluded from policy hash. Identity is handle or email, not git `user.name`. No org plane. |
+| **Team parliament (law vs feature)** | Optional `stewards` on `ark.config.json` (GitHub handle or email); CLI `--changed` / `--against` / `--base` / `--contract-diff` / `--contract-session` / `--persona` / `--author`; check JSON `teamParliament`; `ark status --vs`; write-gate mixed-batch deny | Additive. Law files must not mix with product source. Loosen / baseline-grow are steward-only when `stewards` is set. `--against` ratchets vs the base-ref baseline. `--changed` scans touched sources. `stewards` and `layers[].description` are excluded from policy hash. Identity is handle or email, not git `user.name`. No org plane. |
 | **Atomic change preflight (3.1.0)** | `preflightChange(...)`; CLI `ark preflight --changes <file> --json`; MCP `ark_prepare_change` | Additive schema `1.0`. One complete governed production-source `{path,content}` / `{path,delete:true}` batch; read-only; returns operation, content/tree/policy/compiler fingerprints and stable graph findings. MCP availability alone is advisory. |
 | **Architecture change map (3.1.0)** | `arkgate/schema/change-map` or `arkgate/schema/ark.change-map.schema.json`; CLI `ark preflight --change-map <file>`; MCP `ark_prepare_change.changeMap` | Optional strict schema `1.0`. Canonical planned paths + operations + resolved Ark layers + dependencies between planned files. Preflight returns `changeMapHash`; absence is normal and adds no project file. Structural intent only, never behavioral completion. |
 | **Structural convergence (3.1.0)** | `analyzeArchitectureConvergence(...)`; map-enabled `preflightChange(...)`; existing CLI/MCP preflight adapters | Additive `convergence` result with stable `satisfied`, `missing`, `contradictory`, and `unplanned` findings. Uses the supplied/current project tree as base and the explicit complete change set as candidate; no implicit Git or LLM input. `readOnly: true`; `behavioralCompletion: "not-evaluated"`. Structural mismatch makes preflight invalid. |
@@ -176,7 +189,7 @@ claims. Static architecture enforcement does not depend on them.
 
 | Surface | Import path | Notes |
 |---------|-------------|--------|
-| **ArkRun kernel** | **`arkgate/runtime`** | Public brand **ArkRun**. Same npm package `arkgate` (ADR 0031). Factory `createStrictArkKernel` (each call is an isolated instance; no process-wide `getKernel()` singleton). Root export does **not** include the factory. Optional extra `arkRun` on schema `1.2+`. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Managed components declare `uses` / `reactsTo` / `raises` / `sends` on `register()`; `getDependencyInformationPackage()` is a JSON snapshot of ids, lifetime, and declarations and never includes factories, live instances, or input DTOs (ADR 0023). `requestGraph()` slices that snapshot into **process** or **technical** graphs with optional `nodeIds`, `degreesOfSeparation`, and include/exclude query; `formatArkRunGraphMermaid()` (also `graph.mermaid`) is a helper string, never a score. `send()` is the transport port (local / localBlocking / broker); missing broker falls back to in-process local delivery, `ephemeral` defaults true, and **no cloud SDKs ship** in the package (ADR 0024). Opt-in `startInspector()` / `startArkRunInspector()` binds **`127.0.0.1` only**, refuses `NODE_ENV=production`, lazy-loads HTTP, and serves JSON snapshots, SSE, and `/graph` slices of the information package (no public / authless bind). **Shadow / replay / compare** (`shadowInformationPackage`, `compareInformationPackages`, `replayInformationPackages`) are in-memory helpers on that snapshot — not durable, not a second bus (ADR 0033). **Decision tape** `decisionTape` `{ xiHash, event, residual }` via `appendDecisionTape` (ADR 0034). Built-in stores are **InMemory reference only**. Branding ArkRun is not a production-durability claim. **`@arkgate/runtime` is deprecated** leftover 0.x (`experimental` dist-tag). |
+| **ArkRun kernel** | **`arkgate/runtime`** | Public brand **ArkRun**. Same npm package `arkgate` (ADR 0031). Factory `createStrictArkKernel` (each call is an isolated instance; no process-wide `getKernel()` singleton). Root export does **not** include the factory. Optional extra `arkRun` on schema `1.2+`. Event bus, intents, policies, sagas, event buffer, projections, and strict helpers. Managed components declare `uses` / `reactsTo` / `raises` / `sends` on `register()`; `getDependencyInformationPackage()` is a JSON snapshot of ids, lifetime, and declarations and never includes factories, live instances, or input DTOs (ADR 0023). `requestGraph()` slices that snapshot into **process** or **technical** graphs with optional `nodeIds`, `degreesOfSeparation`, and include/exclude query; `formatArkRunGraphMermaid()` (also `graph.mermaid`) is a helper string, never a score. `send()` is the transport port (local / localBlocking / broker); missing broker falls back to in-process local delivery, `ephemeral` defaults true, and **no cloud SDKs ship** in the package (ADR 0024). Opt-in `startInspector()` / `startArkRunInspector()` binds **`127.0.0.1` only**, refuses `NODE_ENV=production`, lazy-loads HTTP, and serves JSON snapshots, SSE, `/graph` slices of the information package, plus queue monitors **`GET /outbox`** and **`GET /workflows`** (full counts + sanitized samples capped at 32; no full event payloads; missing ports are unavailable; no public / authless bind). Snapshot `hardening.durability` classifies the explicit outbox/audit/workflow store ports; default `InMemory*` stores stay visibly `memory`, never durable. Dual bins **`ark-dashboard`** / **`arkgate-dashboard`** poll those JSON facts (ANSI TUI in `bin/` only — presentation is not in the kernel); `ark dashboard` / `arkgate dashboard` dispatch to the same executable. **Shadow / replay / compare** (`shadowInformationPackage`, `compareInformationPackages`, `replayInformationPackages`) are in-memory helpers on that snapshot — not durable, not a second bus (ADR 0033). **Decision tape** `decisionTape` `{ xiHash, event, residual }` via `appendDecisionTape` (ADR 0034). Built-in stores are **InMemory reference only**. Branding ArkRun is not a production-durability claim. **`@arkgate/runtime` is deprecated** leftover 0.x (`experimental` dist-tag). |
 | **NestJS adapter** | **`arkgate/nestjs`** | Experimental optional peer `@nestjs/common` for the ArkRun kernel. Same npm package. `@arkgate/runtime/nestjs` is deprecated. |
 | **ArkOrder plane** | **`arkgate/order`** | Public brand **ArkOrder**. Same npm package `arkgate` (ADR 0030) — not `@arkgate/order`. Factory `createOrderPlane`. Valved verbs: `release` / `project` / `ingest` / `proposeRelease` / `apply` / `refreshSigma`. No `update`. First freeze is `release()`; later ξ change is `apply` (`ARKORDER_UNVALVED_RELEASE`). Haken: few slow keys; ingest residual `absorb | escalate_up | hold` + closed `reasonCode`; empty blast fails closed. Capacity pack as data (`kind` / `sigmaKey` / `payloadKey` / `op`). Factory options (not config keys): `informationBudget.cannotObserve`, `sigmaMaxAgeMs`, `store` (`ReleaseStore` / `createMemoryReleaseStore`), `catalogDigest`. Thin travel: `ingestTravelAction` absorb→`send` / escalate_up human→`raises`. `IngestEscalate.target` includes `human`. Root `arkgate` export does **not** include the factory. Optional extra `arkOrder` on schema `1.3`. In-memory; not durable; does not close K01. Does not replace ArkRun. Runtime half (shadow/replay/compare + `decisionTape` / `appendDecisionTape`) is ArkRun (ADR 0033 / 0034). Canonical: [ArkOrder](arkorder.md). |
 
@@ -252,7 +265,10 @@ production deployment would need to satisfy; it is not a readiness certification
 ## Release notes (maintainers)
 
 Ship notes for a version live under [releases/](https://github.com/pedroknigge/arkgate/tree/main/docs/releases)
-(current published: [4.8.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.5.md);
+(current tree candidate: [4.8.8.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.8.md), prepared and not published;
+current published: [4.8.7.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.7.md);
+prior published: [4.8.6.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.6.md);
+prior published: [4.8.5.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.5.md);
 prior published: [4.8.4.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.4.md);
 prior published: [4.8.3.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.3.md);
 prior published: [4.8.2.md](https://github.com/pedroknigge/arkgate/blob/main/docs/releases/4.8.2.md);

package/docs/product-voice.md

@@ -45,12 +45,15 @@ human copy says **status**.
 
 ## Locked first-contact
 
-On README, use, develop, the docs hub, and the product site:
+On the eight canonical public openings — `README.md`, `docs/use.md`,
+`docs/develop.md`, `docs/README.md`, `docs/enthusiast/README.md`,
+`docs/agent-guide.md`, `docs/ai-gates.md`, and `docs/package-surface.md` — use:
 
 1. **Verbs:** `Write. Check. Ship.`
 2. **Deny:** `When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.`
 3. **Not-that (below the fold, one line):** `Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config is just documentation.`
-4. **Nouns (once, below the deny):** ArkGate is import rules. ArkRules is optional policies. ArkRun is an optional experimental runtime. ArkOrder is the extra that stops the agent from rewriting the few slow product decisions (plan, protocol) as CRUD — named when the consumer opts in, never as the first noun.
+4. **Story:** the exact four-paragraph introduction below, with no visible heading or labels.
+5. **Technical nouns (below the introduction):** ArkGate is import rules. ArkRules is optional policies. ArkRun is an optional experimental runtime. ArkOrder is the extra that stops the agent from rewriting the few slow product decisions (plan, protocol) as CRUD — named when the consumer opts in, never as the first noun.
 
 Do not lead with folders, `ark.config.json`, “contract”, “gate”, “house”, or “doctor”
 as the first noun. Historical: `If the AI writes an illegal import, the write is rejected`
@@ -61,6 +64,26 @@ ADR 0001 keeps the public name **ArkGate**.
 
 ---
 
+## Unlabeled four-paragraph introduction
+
+STAR is an internal writing method only. Public openings never print the formula's
+name, a heading for this block, bullets, or Situation/Task/Action/Result labels.
+Use these exact four paragraphs and put technical precision below them.
+
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
+Do not add technical terms to these four paragraphs. In the next section, explain that
+ArkGate checks imports, ArkRules is optional, ArkRun is experimental and in-memory,
+and ArkOrder is optional and for a few slow product decisions.
+
+---
+
 ## How it sounds
 
 Short. Product nouns. Scene English (Vercel / Supabase / GitHub Checks).

package/docs/use.md

@@ -2,13 +2,21 @@
 
 **Write. Check. Ship.**
 
-For **anyone** shipping TypeScript with an AI coding agent.
-
 **When the agent writes a bad import, the write doesn’t land. The same check fails the pull request.**
 
 Not an API Gateway. Not a folder linter. If the check is not required on the PR, the config
 is just documentation.
 
+AI can build fast—and make a mess just as fast.
+
+Keep the product easy to understand, change, and trust.
+
+ArkGate stops bad shortcuts. ArkRules protects how each part should behave. ArkRun keeps work moving. ArkOrder protects the few big choices that should not change by accident.
+
+Safer changes, fewer surprises, and extra protection only when you choose it.
+
+For **anyone** shipping TypeScript with an AI coding agent.
+
 ---
 
 ## In one minute
@@ -81,7 +89,7 @@ The config only binds when the write doesn’t land and CI is required.
 | **ArkGate** (layers) | Import rules. The write doesn’t land. The PR fails. | Always — this is the product |
 | **ArkRules** | Optional policies *inside* a layer. | Off until you turn it on (start may ship advisory templates) |
 | **ArkRun** | Optional experimental runtime (`arkgate/runtime`) | Off. In-memory. Not Postgres. |
-| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`). Library + sensors, [not a service](arkorder.md). Valve: `proposeRelease` then `apply`; `refreshSigma`; ingest residual; capacity pack; `ReleaseStore`; ArkRun `decisionTape`. ArkOrder freezes the pattern through a valve. ArkRun is how the residual travels. | Off. Name `xiKeys` (plan / protocol, not `projectId`). Invoices and seats still flow. In-memory. Not durable. |
+| **ArkOrder** | Stops the agent rewriting the few slow product decisions as CRUD (`arkgate/order`). Library + sensors, [not a service](arkorder.md). Valve: `proposeRelease` then `apply`; `refreshSigma`; ingest residual; capacity pack; `ReleaseStore`; ArkRun `decisionTape`. ArkOrder freezes the pattern through a valve. ArkRun is how the residual travels. | Off. Name `xiKeys` (plan / protocol, not `projectId`). Derive recomputable statuses; invoices and seats still flow. In-memory. Not durable. |
 
 Start always gives you **layers**. Compact starters do **not** turn on ArkRun or
 ArkOrder. No extras is fine — only ArkGate runs. Leftovers are labeled