arkgate 4.8.6 → 4.8.8

package/CHANGELOG.md

@@ -3,16 +3,67 @@
 All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are documented here or
 in the immutable pre-2.0 archive linked below.
 
+## 4.8.8 — 2026-09-01
+
+**Patch** over **4.8.7**. ArkRun gains an opt-in terminal dashboard and bounded,
+payload-free inspector monitors. ArkOrder and first-contact docs gain honesty copy.
+**No required config migration.** No `ark.config.json` schema bump. Does not close
+`K01` / `Z09`.
+
+**Status: prepared** (tree candidate; npm `latest` remains **4.8.7** until the
+signed-tag provenance workflow succeeds).
+
+### Added
+- Dual **`ark-dashboard` / `arkgate-dashboard`** bins render the loopback ArkRun
+  inspector with ANSI and polling. `ark dashboard` / `arkgate dashboard` dispatch
+  to the same executable; this is a view, never a gate verdict.
+- ArkRun inspector snapshots report explicit store durability facts. Default
+  `InMemory*` stores remain visibly memory-only and never earn a durable green.
+- Loopback-only **`GET /outbox`** and **`GET /workflows`** return sanitized queue
+  summaries and full counts. Samples are capped at 32, payloads are omitted, the
+  inspector still refuses production, and nothing here supplies durable storage.
+
+### Changed
+- Existing skills and docs now teach the elimination question before a modeller
+  names `xiKeys`: recomputable statuses such as `paid` are derived, not frozen.
+  This is guidance, not a runtime invariant or new sensor; the check remains
+  silent on semantic entailment.
+- Eight canonical public openings now share the same four plain-English story
+  paragraphs. STAR remains the writing method, not a visible heading or labels.
+
+## 4.8.7 — 2026-08-31
+
+**Patch** over **4.8.6**. Phase **LD** — layer description projection. Optional
+`layers[].description` is an **app-context caption** (what this folder is in the
+product), not architecture jargon. Place, doctor, coverage, and the HTML report
+show it when present. Caption-only edits do not change `policyHash`.
+**No required config migration.** No `schemaVersion` bump. Does not close `K01` / `Z09`.
+No new skill names.
+
+**Status: published** (on npm `latest`; see `docs/releases/4.8.7.md`).
+
+### Added
+- Public name for existing `layers[].description`. Example:
+  `"Purchase requests — from asked to received."`
+- Place / prepare-write / MCP JSON, doctor JSON + human, coverage JSON, and the
+  HTML Purpose column project the caption when present.
+- `/ark-adopt` writes the caption from the product map or glossary; `/ark-place`
+  prints it next to layer name + globs.
+
+### Changed
+- `policyHash` omits `layers[].description` the same way it omits `stewards`.
+  Caption-only is neutral. Absence stays silent: never a residual, never a
+  score, never `--strict-config` fail.
+
 ## 4.8.6 — 2026-08-31
 
 **Patch** over **4.8.5**. Phase **LV** — ArkOrder valved loop. First `release()`
 freezes ξ; later pattern change is `proposeRelease` then `apply`. σ identity is
 not ξ identity. ingest returns a closed residual. Capacity is data. ArkRun
 carries the decision tape. **No required config migration.** Does not close
-`K01` / `Z09`. No `/ark-order` skill. Do not npm-publish from this item until
-the maintainer tag.
+`K01` / `Z09`. No `/ark-order` skill.
 
-**Status: prepared** (tree ready; npm `latest` remains **4.8.5** until publish).
+**Status: published** (see `docs/releases/4.8.6.md`).
 
 ### Added
 - **`apply(ProposeResult)`** on `createOrderPlane`. Unvalved second freeze of a
@@ -42,7 +93,7 @@ now has a canonical page. The runtime half (shadow / replay / compare) is
 ArkRun and in-memory. **No required config migration.** Does not close `K01` /
 `Z09`.
 
-**Status: published** (on npm `latest`; see `docs/releases/4.8.5.md`).
+**Status: published** (see `docs/releases/4.8.5.md`).
 
 ### Added
 - **`docs/arkorder.md`:** named APIs adopters were redesigning (`createOrderPlane`,

package/README.md

@@ -7,6 +7,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.
+
 Works with Cursor, Claude, Codex, and Grok.
 
 [![Website](https://img.shields.io/badge/website-arkgate.online-0a0a0a)](https://www.arkgate.online/)
@@ -29,7 +37,7 @@ Works with Cursor, Claude, Codex, and Grok.
 
 </div>
 
-> **ArkGate 4.8.5** is on npm `latest`. This tree is **4.8.6** (prepared patch; not published).
+> **ArkGate 4.8.8** is prepared on this tree; npm `latest` remains **4.8.7**.
 > Write. Check. Ship. Adopted = required GitHub
 > status running `arkgate-check --strict-merge`, or an explicit `advisory-only` stance.
 > Status is compact (`arkgate-check --doctor`; `--all` for Details). Optional **ArkRun**
@@ -37,7 +45,7 @@ Works with Cursor, Claude, Codex, and Grok.
 > (`arkgate/order`) stops the agent rewriting the few slow product decisions as CRUD;
 > later pattern change is `proposeRelease` then `apply`.
 > `@arkgate/runtime` is deprecated.
-> [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
+> [4.8.8 prepared](docs/releases/4.8.8.md) · [4.8.7 published](docs/releases/4.8.7.md) · [4.8.6](docs/releases/4.8.6.md) · [4.8.5](docs/releases/4.8.5.md) · [4.8.4](docs/releases/4.8.4.md) · [4.8.3](docs/releases/4.8.3.md) · [4.8.2](docs/releases/4.8.2.md) · [4.8.1](docs/releases/4.8.1.md) · [4.8.0](docs/releases/4.8.0.md) · [Docs hub](docs/README.md) · [Voice](docs/product-voice.md)
 
 ---
 
@@ -245,6 +253,8 @@ npx arkgate-check --install-agent-gates --tools claude,cursor,codex,grok,antigra
 # npx arkgate-check --install-agent-gates --skills-only --agent-homes --force
 # optional: same 13 skills via Agent Skills ecosystem (no new names)
 # npx skills add ./node_modules/arkgate/templates/agent-skills
+# optional ArkRun: poll the loopback inspector (ANSI TUI — not a gate)
+# npx ark-dashboard --url http://127.0.0.1:<port>/snapshot
 ```
 
 More: [docs/develop.md](docs/develop.md) · skills install: [docs/agent-guide.md](docs/agent-guide.md#install-skills-ark-and-ecosystem) · enthusiast track: [docs/enthusiast/](docs/enthusiast/README.md)
@@ -261,6 +271,26 @@ for decoupling.
 lives in memory and **dies on restart**. Fine for local. Not Postgres, not an
 outbox, not Temporal. `@arkgate/runtime` is deprecated.
 
+### Dev inspector and observability dashboard
+
+Opt-in `startInspector()` binds **loopback only** (`127.0.0.1`), refuses
+`NODE_ENV=production`, and serves JSON facts — not a TUI. Alongside
+`GET /snapshot`, `GET /events` (SSE), and `GET /graph`, the inspector exposes
+queue monitors:
+
+| Path | Body (JSON) |
+|------|-------------|
+| `GET /outbox` | Pending/failed outbox **summaries** + counts (`available`, `pendingCount`, `failedCount`, `pending`, `failed`) — no event payloads |
+| `GET /workflows` | Workflow **summaries** + counts (`available`, `total`, `runningCount`, …, `workflows`) |
+
+Poll those facts from the dual bins **`ark-dashboard`** / **`arkgate-dashboard`**
+(`bin/ark-dashboard.mjs`). ANSI + polling only (no React/Ink/Blessed). Point
+`--url` / `-u` at the inspector snapshot (default
+`http://127.0.0.1:3000/snapshot`); the dashboard also fetches sibling `/outbox`
+and `/workflows`. `--interval` / `-i` is clamped to 200–60000 ms (default 2000).
+Also available as `ark dashboard` / `arkgate dashboard` (passthrough to the same bin). Kernel stays
+JSON-only; presentation stays in `bin/`.
+
 ### Durability stance
 
 Default stores (`InMemoryEventBuffer`, `InMemoryAuditStore`, `InMemoryReadModelStore`,
@@ -282,6 +312,7 @@ because “what may be the plan” was never a rule.
 
 **ArkOrder** (`arkgate/order`) is that rule. Off unless you add `arkOrder`.
 Name the slow keys (`xiKeys`: plan, protocol, cost-code bound — not `projectId`).
+A status you can recompute from data you already have is not a slow decision. Derive it. Do not freeze it.
 Posting an invoice is absorbed. Changing plan is `proposeRelease` then `apply`.
 `refreshSigma`; ingest residual `absorb | escalate_up | hold` + `reasonCode`;
 capacity pack as data; in-memory `ReleaseStore`; `ingestTravelAction`; ArkRun
@@ -309,8 +340,10 @@ three keys. Compact starters leave it off. Details:
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Tree prepared (4.8.6, not published) | [docs/releases/4.8.6.md](docs/releases/4.8.6.md) · [CHANGELOG](CHANGELOG.md) |
-| Current published (4.8.5 on npm `latest`) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) · [CHANGELOG](CHANGELOG.md) |
+| Prepared (4.8.8; not published) | [docs/releases/4.8.8.md](docs/releases/4.8.8.md) · [CHANGELOG](CHANGELOG.md) |
+| Current published (4.8.7 on npm `latest`) | [docs/releases/4.8.7.md](docs/releases/4.8.7.md) · [CHANGELOG](CHANGELOG.md) |
+| Prior published (4.8.6) | [docs/releases/4.8.6.md](docs/releases/4.8.6.md) |
+| Prior published (4.8.5) | [docs/releases/4.8.5.md](docs/releases/4.8.5.md) |
 | Prior published (4.8.4) | [docs/releases/4.8.4.md](docs/releases/4.8.4.md) |
 | Prior published (4.8.3) | [docs/releases/4.8.3.md](docs/releases/4.8.3.md) |
 | Prior published (4.8.2) | [docs/releases/4.8.2.md](docs/releases/4.8.2.md) |

package/bin/ark-dashboard.mjs

@@ -0,0 +1,423 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+
+const DEFAULT_INTERVAL_MS = '2000';
+const DEFAULT_SNAPSHOT_URL = 'http://127.0.0.1:3000/snapshot';
+const DEFAULT_FETCH_TIMEOUT_MS = 5_000;
+const MAX_FIELD_LEN = 120;
+
+const args = parseArgs({
+  options: {
+    interval: {
+      type: 'string',
+      short: 'i',
+      default: DEFAULT_INTERVAL_MS
+    },
+    url: {
+      type: 'string',
+      short: 'u',
+      default: DEFAULT_SNAPSHOT_URL
+    },
+    timeout: {
+      type: 'string',
+      short: 't',
+      default: String(DEFAULT_FETCH_TIMEOUT_MS)
+    }
+  },
+  allowPositionals: true
+});
+
+const parsedInterval = parseInt(args.values.interval, 10);
+const interval =
+  Number.isFinite(parsedInterval) && parsedInterval >= 200 && parsedInterval <= 60_000
+    ? parsedInterval
+    : Number(DEFAULT_INTERVAL_MS);
+const targetUrl = args.values.url || DEFAULT_SNAPSHOT_URL;
+const parsedTimeout = parseInt(args.values.timeout, 10);
+const fetchTimeoutMs =
+  Number.isFinite(parsedTimeout) && parsedTimeout >= 200 && parsedTimeout <= 60_000
+    ? parsedTimeout
+    : DEFAULT_FETCH_TIMEOUT_MS;
+
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const MUTED = '\x1b[2m';
+const SAMPLE_LIMIT = 8;
+
+const DRIFT_FLOW_KEYS = [
+  'declaredButUnobserved',
+  'observedButUndeclared',
+  'unknownSources',
+];
+const DRIFT_ID_KEYS = [
+  'unregisteredObservedSources',
+  'unregisteredObservedIntents',
+  'registeredButNeverObserved',
+];
+
+/** Strip ANSI CSI / OSC / other C0+C1 terminal control sequences; bound length. */
+function sanitizeField(value, maxLen = MAX_FIELD_LEN) {
+  let text = value === undefined || value === null ? '' : String(value);
+  // OSC: ESC ] … BEL or ESC ]
+  text = text.replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?/g, '');
+  // CSI / Fe sequences
+  text = text.replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '');
+  // Remaining ESC + final byte / 8-bit C1
+  text = text.replace(/\u001b[@-Z\\-_]/g, '');
+  text = text.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, '');
+  if (text.length > maxLen) {
+    return `${text.slice(0, Math.max(0, maxLen - 1))}…`;
+  }
+  return text;
+}
+
+function siblingUrl(snapshotUrl, suffix) {
+  try {
+    const u = new URL(snapshotUrl);
+    let basePath = u.pathname;
+    if (basePath.endsWith('/snapshot')) {
+      basePath = basePath.slice(0, -'/snapshot'.length);
+    } else if (basePath.endsWith('/snapshot/')) {
+      basePath = basePath.slice(0, -'/snapshot/'.length);
+    }
+    u.pathname = `${basePath}${suffix}`;
+    return u.toString();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @returns {{ ok: true, data: unknown } | { ok: false, kind: 'waiting' | 'failure', error?: string }}
+ */
+async function fetchJsonResult(url) {
+  if (!url) return { ok: false, kind: 'waiting' };
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), fetchTimeoutMs);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    if (!res.ok) {
+      return { ok: false, kind: 'failure', error: `HTTP ${res.status}` };
+    }
+    const data = await res.json();
+    return { ok: true, data };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const aborted =
+      (error && typeof error === 'object' && error.name === 'AbortError') ||
+      /aborted|timeout/i.test(message);
+    return {
+      ok: false,
+      kind: 'failure',
+      error: sanitizeField(aborted ? `timeout after ${fetchTimeoutMs}ms` : message),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function isObservabilityReady(obs) {
+  if (!obs || typeof obs !== 'object' || Array.isArray(obs)) return false;
+  if (Object.keys(obs).length === 0) return false;
+  return [...DRIFT_FLOW_KEYS, ...DRIFT_ID_KEYS].some((k) => Array.isArray(obs[k]));
+}
+
+function formatFlow(flow) {
+  if (!flow || typeof flow !== 'object') return sanitizeField(flow);
+  const from = sanitizeField(flow.from ?? '?');
+  const to = sanitizeField(flow.to ?? '?');
+  return `${from}→${to}`;
+}
+
+function listSamples(items, formatter) {
+  const sample = items.slice(0, SAMPLE_LIMIT);
+  for (const item of sample) {
+    console.log(`    • ${formatter(item)}`);
+  }
+  if (items.length > SAMPLE_LIMIT) {
+    console.log(`    … +${items.length - SAMPLE_LIMIT} more`);
+  }
+}
+
+function renderDriftRadar(observability) {
+  console.log(`\n--- Drift Radar ---`);
+  if (!isObservabilityReady(observability)) {
+    console.log(`${MUTED}Waiting for observability…${RESET}`);
+    return;
+  }
+
+  const flows = Object.fromEntries(
+    DRIFT_FLOW_KEYS.map((k) => [k, Array.isArray(observability[k]) ? observability[k] : []]),
+  );
+  const ids = Object.fromEntries(
+    DRIFT_ID_KEYS.map((k) => [k, Array.isArray(observability[k]) ? observability[k] : []]),
+  );
+
+  const counts = {
+    declaredButUnobserved: flows.declaredButUnobserved.length,
+    observedButUndeclared: flows.observedButUndeclared.length,
+    unknownSources: flows.unknownSources.length,
+    unregisteredObservedSources: ids.unregisteredObservedSources.length,
+    unregisteredObservedIntents: ids.unregisteredObservedIntents.length,
+    registeredButNeverObserved: ids.registeredButNeverObserved.length,
+  };
+  const totalDrift = Object.values(counts).reduce((a, b) => a + b, 0);
+
+  if (observability.generatedAt) {
+    console.log(`Generated: ${sanitizeField(observability.generatedAt)}`);
+  }
+
+  console.log(
+    `Counts: declaredButUnobserved=${counts.declaredButUnobserved} ` +
+      `observedButUndeclared=${counts.observedButUndeclared} ` +
+      `unknownSources=${counts.unknownSources} ` +
+      `unregisteredSources=${counts.unregisteredObservedSources} ` +
+      `unregisteredIntents=${counts.unregisteredObservedIntents} ` +
+      `neverObserved=${counts.registeredButNeverObserved}`,
+  );
+
+  if (totalDrift === 0) {
+    console.log(`${GREEN}No drift${RESET}`);
+    return;
+  }
+
+  const critical =
+    counts.observedButUndeclared > 0 ||
+    counts.unknownSources > 0 ||
+    counts.unregisteredObservedSources > 0 ||
+    counts.unregisteredObservedIntents > 0;
+  const color = critical ? RED : YELLOW;
+  console.log(`${color}[DRIFT] ${totalDrift} issue(s) detected${RESET}`);
+
+  for (const key of DRIFT_FLOW_KEYS) {
+    const items = flows[key];
+    if (items.length === 0) continue;
+    console.log(`  ${YELLOW}${key}${RESET} (${items.length}):`);
+    listSamples(items, formatFlow);
+  }
+  for (const key of DRIFT_ID_KEYS) {
+    const items = ids[key];
+    if (items.length === 0) continue;
+    console.log(`  ${YELLOW}${key}${RESET} (${items.length}):`);
+    listSamples(items, (id) => sanitizeField(id));
+  }
+}
+
+function formatOutboxRow(row) {
+  const intent = row.intent ? ` ${sanitizeField(row.intent)}` : '';
+  const err = row.error ? ` err=${sanitizeField(row.error)}` : '';
+  return `${sanitizeField(row.status)} ${sanitizeField(row.id)}${intent} attempts=${row.attempts ?? 0}${err}`;
+}
+
+function formatWorkflowRow(row) {
+  const step = row.currentStep ? ` @${sanitizeField(row.currentStep)}` : '';
+  const err = row.error ? ` err=${sanitizeField(row.error)}` : '';
+  return `${sanitizeField(row.status)} ${sanitizeField(row.name)} (${sanitizeField(row.id)})${step}${err}`;
+}
+
+function isOutboxReady(outbox) {
+  return Boolean(outbox && typeof outbox === 'object' && outbox.available === true);
+}
+
+function isWorkflowsReady(workflows) {
+  return Boolean(workflows && typeof workflows === 'object' && workflows.available === true);
+}
+
+function renderFetchStatus(label, result) {
+  if (result.ok) return;
+  if (result.kind === 'waiting') {
+    console.log(`${MUTED}${label}: Waiting…${RESET}`);
+    return;
+  }
+  const detail = result.error ? ` (${result.error})` : '';
+  console.log(`${RED}${label}: Failure${detail}${RESET}`);
+}
+
+function renderQueuesAndWorkflows(outboxResult, workflowsResult, snapshotOutbox, snapshotWorkflows) {
+  console.log(`\n--- Queues & Workflows ---`);
+
+  const outbox = isOutboxReady(outboxResult.ok ? outboxResult.data : null)
+    ? outboxResult.data
+    : isOutboxReady(snapshotOutbox)
+      ? snapshotOutbox
+      : null;
+  const workflows = isWorkflowsReady(workflowsResult.ok ? workflowsResult.data : null)
+    ? workflowsResult.data
+    : isWorkflowsReady(snapshotWorkflows)
+      ? snapshotWorkflows
+      : null;
+
+  if (!outbox && !workflows) {
+    if (!outboxResult.ok && !workflowsResult.ok) {
+      renderFetchStatus('Outbox', outboxResult);
+      renderFetchStatus('Workflows', workflowsResult);
+      return;
+    }
+    console.log(`${MUTED}Waiting for queues & workflows…${RESET}`);
+    return;
+  }
+
+  if (!outbox) {
+    renderFetchStatus('Outbox', outboxResult.ok ? { ok: false, kind: 'waiting' } : outboxResult);
+  } else {
+    const pending = Array.isArray(outbox.pending) ? outbox.pending : [];
+    const failed = Array.isArray(outbox.failed) ? outbox.failed : [];
+    const pendingCount = outbox.pendingCount ?? pending.length;
+    const failedCount = outbox.failedCount ?? failed.length;
+    console.log(`Outbox: pending=${pendingCount} failed=${failedCount}`);
+
+    if (pendingCount === 0 && failedCount === 0) {
+      console.log(`${GREEN}Outbox empty${RESET}`);
+    } else {
+      if (failedCount > 0) {
+        console.log(`${RED}[OUTBOX] ${failedCount} failed${RESET}`);
+        listSamples(failed, (row) => `${RED}${formatOutboxRow(row)}${RESET}`);
+      }
+      if (pendingCount > 0) {
+        console.log(`${YELLOW}[OUTBOX] ${pendingCount} pending${RESET}`);
+        listSamples(pending, (row) => `${YELLOW}${formatOutboxRow(row)}${RESET}`);
+      }
+    }
+  }
+
+  if (!workflows) {
+    renderFetchStatus(
+      'Workflows',
+      workflowsResult.ok ? { ok: false, kind: 'waiting' } : workflowsResult,
+    );
+    return;
+  }
+
+  const rows = Array.isArray(workflows.workflows) ? workflows.workflows : [];
+  const running = workflows.runningCount ?? rows.filter((w) => w.status === 'running').length;
+  const compensating =
+    workflows.compensatingCount ?? rows.filter((w) => w.status === 'compensating').length;
+  const failedWf = workflows.failedCount ?? rows.filter((w) => w.status === 'failed').length;
+  const pendingWf =
+    workflows.pendingCount ??
+    rows.filter((w) => w.status === 'idle' || w.status === 'waiting').length;
+  console.log(
+    `Workflows: total=${workflows.total ?? rows.length} running=${running} ` +
+      `compensating=${compensating} failed=${failedWf} pending=${pendingWf}`,
+  );
+
+  if (failedWf === 0 && running === 0 && compensating === 0 && pendingWf === 0) {
+    console.log(`${GREEN}No active workflows${RESET}`);
+    return;
+  }
+
+  if (failedWf > 0) {
+    console.log(`${RED}[WORKFLOWS] ${failedWf} failed${RESET}`);
+    listSamples(
+      rows.filter((w) => w.status === 'failed'),
+      (row) => `${RED}${formatWorkflowRow(row)}${RESET}`,
+    );
+  }
+  const yellowRows = rows.filter((w) =>
+    w.status === 'running' ||
+    w.status === 'compensating' ||
+    w.status === 'idle' ||
+    w.status === 'waiting',
+  );
+  if (yellowRows.length > 0) {
+    console.log(`${YELLOW}[WORKFLOWS] ${yellowRows.length} pending/running/compensating${RESET}`);
+    listSamples(yellowRows, (row) => `${YELLOW}${formatWorkflowRow(row)}${RESET}`);
+  }
+}
+
+function durabilityStores(snapshot) {
+  const stores = snapshot?.hardening?.durability?.stores;
+  return Array.isArray(stores) ? stores : [];
+}
+
+function renderHardening(snapshotResult) {
+  console.log(`--- Hardening Status ---`);
+  if (!snapshotResult.ok) {
+    if (snapshotResult.kind === 'waiting') {
+      console.log(`${YELLOW}Waiting for kernel...${RESET}`);
+    } else {
+      const detail = snapshotResult.error ? ` (${snapshotResult.error})` : '';
+      console.log(`${RED}Failure contacting kernel${detail}${RESET}`);
+    }
+    return;
+  }
+
+  const snapshot = snapshotResult.data;
+  const stores = durabilityStores(snapshot);
+  const memoryStores = stores.filter((s) => s && s.kind === 'memory');
+  const durableStores = stores.filter((s) => s && s.kind === 'durable');
+
+  if (stores.length === 0) {
+    // Missing durability facts must never read as green OK.
+    console.log(`${YELLOW}[WARNING] Store durability facts unavailable${RESET}`);
+    return;
+  }
+
+  if (memoryStores.length > 0) {
+    console.log(`${RED}[WARNING] Memory defaults in use!${RESET}`);
+    for (const store of memoryStores) {
+      const role = sanitizeField(store.role ?? 'store');
+      const id = sanitizeField(store.id ?? store.name ?? 'unknown');
+      console.log(`  - ${YELLOW}${role}: ${id}${RESET}`);
+    }
+    if (durableStores.length > 0) {
+      for (const store of durableStores) {
+        const role = sanitizeField(store.role ?? 'store');
+        const id = sanitizeField(store.id ?? store.name ?? 'unknown');
+        console.log(`  - ${MUTED}${role}: ${id} (durable)${RESET}`);
+      }
+    }
+    return;
+  }
+
+  console.log(`${GREEN}[OK] Durable Stores Configured${RESET}`);
+  for (const store of durableStores) {
+    const role = sanitizeField(store.role ?? 'store');
+    const id = sanitizeField(store.id ?? store.name ?? 'unknown');
+    console.log(`  - ${MUTED}${role}: ${id}${RESET}`);
+  }
+}
+
+async function render() {
+  process.stdout.write('\x1b[2J\x1b[H');
+  console.log(`ArkGate Observability Dashboard`);
+  console.log(`Time: ${sanitizeField(new Date().toISOString())}`);
+  console.log(`Endpoint: ${sanitizeField(targetUrl)}\n`);
+
+  const outboxUrl = siblingUrl(targetUrl, '/outbox');
+  const workflowsUrl = siblingUrl(targetUrl, '/workflows');
+  const [snapshotResult, outboxResult, workflowsResult] = await Promise.all([
+    fetchJsonResult(targetUrl),
+    fetchJsonResult(outboxUrl),
+    fetchJsonResult(workflowsUrl),
+  ]);
+
+  renderHardening(snapshotResult);
+
+  const snapshot = snapshotResult.ok ? snapshotResult.data : null;
+  renderDriftRadar(snapshot?.observability);
+  renderQueuesAndWorkflows(
+    outboxResult,
+    workflowsResult,
+    snapshot?.outbox,
+    snapshot?.workflows,
+  );
+}
+
+async function startDashboard() {
+  console.log(
+    `Starting ArkGate Observability Dashboard (polling every ${interval}ms, fetch timeout ${fetchTimeoutMs}ms)`,
+  );
+
+  while (true) {
+    await render();
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+}
+
+startDashboard().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/bin/ark-mcp-runtime.mjs

@@ -27,6 +27,7 @@ import { effectiveCapabilityDeny, stableSerialize } from './lib/analysis-engine.
 import { createImportTargetResolver } from './lib/import-resolve.mjs';
 import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mjs';
 import { composePrepareWrite } from './lib/prepare-write.mjs';
+import { placementDescriptionFields } from './lib/layer-description.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
 import { loadEffectiveArkRulesFromDisk } from './lib/effective-contract-load.mjs';
 import {
@@ -1925,6 +1926,7 @@ export async function runArkMcp({ hookInput } = {}) {
         'Place a file in the architecture: filePath is required (fail-closed without it — never invents components/*.tsx or defaults to Presentation). ' +
         'Returns layer, mayImport / mustNotImport, forbiddenGlobals, and goldenPattern ' +
         '(load-bearing for NEW code when .ark/golden-pattern.json exists — adopt generates it). ' +
+        'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
         'Call BEFORE writing a new file. ' +
         'Prefer ark_prepare_write when you already have the source snippet (place+validate+autoPatch in one call).',
       inputSchema: {
@@ -1950,7 +1952,8 @@ export async function runArkMcp({ hookInput } = {}) {
         'mechanical-safe autoPatch + judgmentBrief when judgment is needed + contentHash for host commit. ' +
         'Also returns the versioned new/worsened designDelta for the proposed full file. ' +
         'Composes ark_place + write-gate — call BEFORE Write/Edit when you have the snippet. ' +
-        'Returns { filePath, layer, valid, violations?, autoPatch?, judgmentBrief?, contentHash, ... }.',
+        'When the matched layer has layers[].description, the JSON includes description; the field is omitted when absent. ' +
+        'Returns { filePath, layer, description?, valid, violations?, autoPatch?, judgmentBrief?, contentHash, ... }.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -2393,6 +2396,9 @@ export async function runArkMcp({ hookInput } = {}) {
   // `allowed:false` denies) — which layers it may and must not import.
   // Q03: when present, attach optional `.ark/golden-pattern.json` (advisory for NEW code only).
   function placeResult(filePath, description) {
+    // Input `description` is the pre-existing "what you are building" hint — not
+    // layers[].description — and must not be copied onto the caption key (ADR 0035 D5).
+    void description;
     const golden = loadGoldenPattern(args.root);
     const withGolden = (placement) => attachGoldenToPlacement(placement, golden);
 
@@ -2433,7 +2439,7 @@ export async function runArkMcp({ hookInput } = {}) {
       filePath,
       layer: layerName,
       governed: true,
-      description: layerMeta?.description,
+      ...placementDescriptionFields(layerMeta),
       forbiddenGlobals: layerMeta?.forbiddenGlobals ?? [],
       ...(layerMeta?.mayImportInfrastructure ? { mayImportInfrastructure: true } : {}),
       mayImport,