@north-light/crouter 0.3.244 → 0.3.245

package/dist/commands/sys/context/admin/rail-panel.js

@@ -1,9 +1,12 @@
-// The rail: two sections in one row grammar. SNAPSHOT holds the configuration
-// axes the page plans against — changing one re-plans every event. FILTERS holds
-// the question asked of that plan — changing one only changes what is shown.
-// An enum cycles in place; a free-text row opens a field.
+// The rail: three sections in one row grammar. EVENTS names every surface the
+// runtime delivers on and how many documents each one delivers, and dials which
+// of them the page is planning. SNAPSHOT holds the configuration axes that plan
+// is computed against — changing one re-plans every event. FILTERS holds the
+// question asked of the plan — changing one only changes what is shown. An enum
+// cycles in place; a free-text row opens a field.
 import { truncateToWidth } from '@earendil-works/pi-tui';
 import { padAnsi, theme } from '../../../../core/tui/panel.js';
+import { tildify } from '../../../../core/fs-utils.js';
 import { KINDS, RUNGS, SURFACE_EVENTS } from '../../../../core/substrate/schema.js';
 import { listProfiles } from '../../../../core/profiles/manifest.js';
 import { payloadAxisFor } from './model.js';
@@ -40,25 +43,11 @@ export function cycleFacet(filters, id, delta) {
             return filters;
     }
 }
-function tildify(path) {
-    const home = process.env['HOME'];
-    return home !== undefined && home !== '' && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
-}
-/** The rail's rows for a snapshot. The payload row appears only for the events
- *  that read one, because on boot there is nothing it could change. */
+/** The configuration rows for a snapshot. The event and its payload are not
+ *  here — they belong to the EVENTS section, where the payload sits under the
+ *  count it explains. */
 export function axesOf(snapshot, profileName) {
-    const payload = payloadAxisFor(snapshot.event);
-    const payloadValue = payload === 'file' ? snapshot.file : payload === 'docName' ? snapshot.docName : payload === 'command' ? snapshot.command : '';
     return [
-        { id: 'event', label: 'event', value: snapshot.event, typed: false },
-        ...(payload === null
-            ? []
-            : [{
-                    id: 'payload',
-                    label: payload === 'file' ? 'file' : payload === 'docName' ? 'doc' : 'command',
-                    value: payloadValue === '' ? '(none — nothing matches)' : payloadValue,
-                    typed: true,
-                }]),
         { id: 'kind', label: 'kind', value: snapshot.kind, typed: true },
         { id: 'mode', label: 'mode', value: snapshot.mode, typed: false },
         { id: 'lifecycle', label: 'lifecycle', value: snapshot.lifecycle, typed: false },
@@ -68,6 +57,21 @@ export function axesOf(snapshot, profileName) {
         { id: 'cwd', label: 'cwd', value: tildify(snapshot.cwd), typed: true },
     ];
 }
+/** The payload field for the dialled event, or nothing when the event reads no
+ *  payload — on boot there is nothing it could change. It renders inside the
+ *  EVENTS section, directly under the count it explains. */
+export function payloadRowOf(snapshot) {
+    const payload = payloadAxisFor(snapshot.event);
+    if (payload === null)
+        return undefined;
+    const value = payload === 'file' ? snapshot.file : payload === 'docName' ? snapshot.docName : snapshot.command;
+    return {
+        id: 'payload',
+        label: payload === 'file' ? 'file' : payload === 'docName' ? 'doc' : 'command',
+        value: value === '' ? '(none — nothing matches)' : value,
+        typed: true,
+    };
+}
 /** Cycle one enum axis, returning the changed snapshot. A typed axis is never
  *  cycled — the shell opens a field for it instead. */
 export function cycleAxis(snapshot, id, delta) {
@@ -126,31 +130,94 @@ export function typedAxisValue(snapshot, id) {
     return axis === 'file' ? snapshot.file : axis === 'docName' ? snapshot.docName : axis === 'command' ? snapshot.command : '';
 }
 const LABEL_WIDTH = 10;
-/** Both sections as one column. `index` runs over the axes and then the facets
- *  — the order the shell routes a cycle in — while the section headings and the
- *  blank rows between them are drawn but never selectable. */
+/** A rail row's identity, which the shell holds the cursor by. The list's
+ *  composition changes whenever the dialled event moves the payload row, so an
+ *  offset kept across that change points at a different row. */
+export function railRowKey(row) {
+    if (row.kind === 'event')
+        return `event:${row.event.event}`;
+    return row.kind === 'axis' ? `axis:${row.axis.id}` : `facet:${row.facet.id}`;
+}
+/** What enter does on a rail row: an event dials it, a typed row opens its
+ *  field, and every other row hands the keyboard to the documents. Space does
+ *  the same thing on the first two and cycles the value on the last. */
+export function railEnter(row) {
+    if (row === undefined)
+        return 'documents';
+    if (row.kind === 'event')
+        return 'dial';
+    if (row.kind === 'axis')
+        return row.axis.typed ? 'edit' : 'documents';
+    return row.facet.typed ? 'edit' : 'documents';
+}
+export function railRowsOf(events, payload, axes, facets) {
+    const rows = [];
+    for (const event of events) {
+        rows.push({ kind: 'event', event });
+        if (event.dialled && payload !== undefined)
+            rows.push({ kind: 'axis', axis: payload, indent: true });
+    }
+    for (const axis of axes)
+        rows.push({ kind: 'axis', axis, indent: false });
+    for (const facet of facets)
+        rows.push({ kind: 'facet', facet });
+    return rows;
+}
+/** All three sections as one column. `index` runs over `rows`, while the
+ *  section headings and the blank rows between them are drawn but never
+ *  selectable. */
 export function renderRail(opts) {
-    const { axes, facets, index, width, height, focused, matched, total } = opts;
+    const { rows, index, width, height, focused, matched, total } = opts;
     const lines = [];
     let cursorLine = 0;
-    const push = (at, label, value) => {
-        const room = Math.max(1, width - LABEL_WIDTH - 2);
-        const padded = padAnsi(truncateToWidth(label, LABEL_WIDTH), LABEL_WIDTH);
-        const shown = truncateToWidth(value, room);
-        const body = ` ${padded} ${shown}`;
+    /** `plain` is the uncoloured body without its leading space — what the accent
+     *  mark recolours, so no inner reset cuts the highlight short. */
+    const push = (at, marked, body, dim, plain) => {
         if (at === index)
             cursorLine = lines.length;
         if (at === index && focused)
             lines.push(theme.bg('selectedBg', padAnsi(body, width)));
-        else if (at === index)
-            lines.push(`${theme.fg('accent', '▌')}${padAnsi(theme.fg('accent', body.slice(1)), width - 1)}`);
+        else if (at === index || marked) {
+            lines.push(`${theme.fg('accent', '▌')}${padAnsi(theme.fg('accent', plain), width - 1)}`);
+        }
         else
-            lines.push(padAnsi(` ${theme.fg('dim', padded)} ${shown}`, width));
+            lines.push(padAnsi(dim, width));
     };
-    lines.push(theme.fg('dim', ' SNAPSHOT'), '');
-    axes.forEach((axis, at) => push(at, axis.label, axis.value));
-    lines.push('', theme.fg('dim', ` FILTERS · ${matched} of ${total}`), '');
-    facets.forEach((facet, at) => push(axes.length + at, facet.label, facet.value));
+    const labelled = (at, label, value, indent) => {
+        const labelRoom = Math.max(1, LABEL_WIDTH - indent);
+        const room = Math.max(1, width - LABEL_WIDTH - 2);
+        const padded = `${' '.repeat(indent)}${padAnsi(truncateToWidth(label, labelRoom), labelRoom)}`;
+        const shown = truncateToWidth(value, room);
+        push(at, false, ` ${padded} ${shown}`, ` ${theme.fg('dim', padded)} ${shown}`, `${padded} ${shown}`);
+    };
+    const evented = (at, row) => {
+        const count = row.delivers === undefined ? '…' : String(row.delivers);
+        const tone = row.delivers === undefined || row.delivers === 0 ? 'dim' : 'success';
+        const room = Math.max(1, width - 2 - count.length);
+        const name = padAnsi(truncateToWidth(row.event, room), room);
+        const toned = theme.fg(tone, count);
+        // The dialled event wears the same mark a selected row wears, because it IS
+        // the selection every other pane is drawn against.
+        push(at, row.dialled, ` ${name} ${toned}`, ` ${theme.fg('dim', name)} ${toned}`, `${name} ${count}`);
+    };
+    const sectionOf = (row) => row.kind === 'facet' ? 'filters' : row.kind === 'event' || row.indent ? 'events' : 'snapshot';
+    const headings = { events: ' EVENTS', snapshot: ' SNAPSHOT', filters: ` FILTERS · ${matched} of ${total}` };
+    let section;
+    rows.forEach((row, at) => {
+        const belongs = sectionOf(row);
+        if (belongs !== section) {
+            if (lines.length > 0)
+                lines.push('');
+            lines.push(theme.fg('dim', headings[belongs]), '');
+            section = belongs;
+        }
+        if (row.kind === 'event')
+            evented(at, row.event);
+        else if (row.kind === 'axis')
+            labelled(at, row.axis.label, row.axis.value, row.indent ? 2 : 0);
+        else
+            labelled(at, row.facet.label, row.facet.value, 0);
+    });
     const maxStart = Math.max(0, lines.length - height);
     const start = Math.min(Math.max(0, cursorLine - Math.floor(height / 2)), maxStart);
     const out = lines.slice(start, start + height);

package/dist/commands/sys/context/admin/read-view.d.ts

@@ -1,5 +1,6 @@
 import { type Rung, type SurfaceEvent } from '../../../../core/substrate/schema.js';
 import type { DeliveryRecord } from '../../../../core/substrate/plan.js';
+import type { NodeConfigSubject } from '../../../../core/substrate/subject-fields.js';
 /** The profile project entry whose `memory` rung ceilings this document's
  *  store, or null when no project governs it. */
 export interface CapOwner {
@@ -13,6 +14,9 @@ export interface DossierContext {
     records: Map<SurfaceEvent, DeliveryRecord>;
     capOwner: CapOwner | null;
     readOnly: boolean;
+    /** The configuration every record here was planned against — what a failed
+     *  gate is explained against. Null when there is no node config at all. */
+    subject: NodeConfigSubject | null;
 }
 /** The resting card, and — when `bodyOpen` — the document's own text beneath
  *  it in place of the affordance line that names it. */

package/dist/commands/sys/context/admin/read-view.js

@@ -13,6 +13,7 @@ import { getMarkdownTheme } from '@earendil-works/pi-coding-agent';
 import { Markdown, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
 import { theme, wrapText } from '../../../../core/tui/panel.js';
 import { SURFACE_EVENTS, rungRank } from '../../../../core/substrate/schema.js';
+import { allMismatches, CLAUSE_SEPARATOR, explainRecordGate, formatClause, } from '../../../../core/substrate/gate-explain.js';
 import { formatCost, plural, rungCostsOf } from './model.js';
 /** Read-only, at rest: no word and no sentence. The refusal itself is a notice
  *  fired at the moment a write is attempted. */
@@ -107,10 +108,29 @@ export function renderDossierDelivery(record, context, width) {
     const warn = (text) => {
         out.push(...indent(wrapped(text, inner)).map((line) => theme.fg('warning', line)));
     };
-    if (!record.docGate.pass)
-        warn(`gate fails: ${record.docGate.reason}`);
-    if (record.entryGate !== null && !record.entryGate.pass)
-        warn(`entry gate fails: ${record.entryGate.reason}`);
+    let unexplained = false;
+    const gateBlock = (side, noun) => {
+        const outcome = side === 'doc' ? record.docGate : record.entryGate;
+        if (outcome === null || outcome.pass)
+            return [];
+        const clauses = explainRecordGate(record, side, context.subject);
+        if (clauses.length === 0) {
+            unexplained = true;
+            warn(`${noun} fails: ${outcome.reason}`);
+            return clauses;
+        }
+        // A gate carrying a defect can never match ANY node, so it names a
+        // different remedy than a node that merely does not qualify.
+        warn(allMismatches(clauses) ? `${noun} fails` : `${noun} never matches`);
+        for (const clause of clauses) {
+            out.push(...clauseRows(formatClause(clause), inner).map((line) => theme.fg('warning', line)));
+        }
+        return clauses;
+    };
+    const failing = [...gateBlock('doc', 'gate'), ...gateBlock('entry', 'entry gate')];
+    if (!unexplained && allMismatches(failing)) {
+        out.push(...dim('dial the snapshot at left to load it here', width));
+    }
     if (record.matchedEntry === null && record.authoredEntries.length > 0) {
         out.push(...indent(wrapped(`${plural(record.authoredEntries.length, 'entry', 'entries')} for this event, none matched`, inner)).map((line) => theme.fg('dim', line)));
     }
@@ -138,6 +158,23 @@ export function bodyLineCount(body) {
 function indent(lines) {
     return lines.map((line) => `${INDENT}${line}`);
 }
+/** Every column a clause line under a gate header carries. */
+const CLAUSE_INDENT = `${INDENT}  `;
+/** One clause, kept on one row while the pane can hold it. Too wide, it breaks
+ *  at the grammar's own separator — the reader's value on one row, the gate's demand beneath it —
+ *  and each half wraps rather than losing a character to an ellipsis. */
+function clauseRows(clause, inner) {
+    const room = Math.max(1, inner - 2);
+    if (visibleWidth(clause) <= room)
+        return [`${CLAUSE_INDENT}${clause}`];
+    const at = clause.indexOf(CLAUSE_SEPARATOR);
+    if (at === -1)
+        return wrapped(clause, room).map((line) => `${CLAUSE_INDENT}${line}`);
+    return [
+        ...wrapped(clause.slice(0, at), room).map((line) => `${CLAUSE_INDENT}${line}`),
+        ...wrapped(clause.slice(at + 1), Math.max(1, room - 2)).map((line) => `${CLAUSE_INDENT}  ${line}`),
+    ];
+}
 /** `wrapText` is the page's prose wrapper, and its word-oriented contract
  *  deliberately leaves a filesystem path or a compact JSON predicate intact.
  *  Values carrying such a token go through pi-tui's character-safe wrapper

package/dist/commands/sys/context/admin/shell.d.ts

@@ -44,6 +44,11 @@ export declare class ContextAdminShell implements Component, Focusable {
     private setFilters;
     private syncDetail;
     private setSnapshot;
+    /** Put the rail cursor back on the row it was on, since dialling a different
+     *  event moves the payload row and every offset below it. The payload belongs
+     *  to the dialled event, so when the new event reads none the cursor falls to
+     *  that event's own row rather than to whatever slid into the offset. */
+    private holdRail;
     private matches;
     private label;
     private isDown;
@@ -54,8 +59,13 @@ export declare class ContextAdminShell implements Component, Focusable {
      *  drawn against, so it earns the page-level gesture. */
     private cyclesEvent;
     handleInput(data: string): void;
-    /** The rail's rows are the snapshot axes followed by the filter facets, so
-     *  one cursor and one gesture drive both sections. */
+    /** Every surface event with what it delivers, which is what the rail states
+     *  instead of the list drawing a cell per event on every row. An event whose
+     *  plan has not warmed yet has no count to state. */
+    private eventRows;
+    /** The rail's rows: the events, then the snapshot axes, then the filter
+     *  facets, so one cursor and one gesture drive all three sections. */
+    private railRows;
     private handleRail;
     private handleDocs;
     private openSearch;
@@ -102,8 +112,8 @@ export declare class ContextAdminShell implements Component, Focusable {
     private handleModal;
     private renderModal;
     private footer;
-    /** What the focused row does when opened. A directory answers to space, a
-     *  document to enter, and a directory that is also a document to both. */
+    /** What the focused row does when opened. A directory expands; a document
+     *  opens its dossier. */
     private docsGesture;
     render(width: number): string[];
     /** What the delivering documents spend on this event. An estimate, and a

package/dist/commands/sys/context/admin/shell.js

@@ -1,7 +1,7 @@
-// The `crtr sys context admin` page: a rail, the document matrix, and the
-// dossier that edits one document's routing. The rail decides WHAT is being
-// planned and WHICH slice of it is shown, the matrix shows WHERE every document
-// lands, and the dossier is the only place a write starts.
+// The `crtr sys context admin` page: a rail, the document list, and the dossier
+// that edits one document's routing. The rail decides WHAT is being planned and
+// WHICH slice of it is shown, the list states what each document does on the
+// dialled event, and the dossier is the only place a write starts.
 import { Input, matchesKey, truncateToWidth, visibleWidth, } from '@earendil-works/pi-tui';
 import { formatGesture, matchesPiTuiInput, } from '../../../../core/keybindings/index.js';
 import { runTuiPage } from '../../../../core/tui/page-host.js';
@@ -10,7 +10,7 @@ import { RUNGS, SURFACE_EVENTS, SURFACE_RUNGS, } from '../../../../core/substrat
 import { profileNameFor } from '../../../../core/substrate/subject-fields.js';
 import { editBufferInEditor } from '../../../../clients/inbox/review/roundtrip.js';
 import { capOwnerFor, moveDoc, readBody, readOnlyReason, toggleFlag, writeBody, writeCap, writeGate, writeRoutingLine, writeShortForm, writeSurfaces, } from './actions.js';
-import { axesOf, cycleAxis, cycleFacet, facetsOf, renderRail, setTypedAxis, typedAxisValue, } from './rail-panel.js';
+import { axesOf, cycleAxis, cycleFacet, facetsOf, payloadRowOf, railEnter, railRowKey, railRowsOf, renderRail, setTypedAxis, typedAxisValue, } from './rail-panel.js';
 import { ContextDetailPanel } from './detail-panel.js';
 import { ContextDocsPanel, buildRows } from './docs-panel.js';
 import { NO_FILTERS, costTotals } from './list-view.js';
@@ -20,8 +20,8 @@ const RAIL_MIN_TOTAL_WIDTH = 86;
 const THREE_COLUMN_MIN_WIDTH = 112;
 /** Columns the two dividers between the three zones spend. */
 const DIVIDER_WIDTH = 6;
-/** Below the floor a row cannot hold a name beside the matrix; above the
- *  ceiling extra width stops buying legibility and the dossier wants it. */
+/** Below the floor a row cannot hold a name beside its state; above the ceiling
+ *  extra width stops buying legibility and the dossier wants it. */
 const DOCS_MIN_WIDTH = 48;
 const DOCS_MAX_WIDTH = 100;
 const DOCS_SHARE = 0.45;
@@ -78,14 +78,14 @@ export class ContextAdminShell {
     // planning
     /** Recompute the focused event's plan, refresh the panels from it, and let
      *  the remaining events fill in behind it. */
-    rebuild(selectedKey) {
+    rebuild() {
         this.plans.plan(this.snapshot.event);
         this.rows = buildRows(this.plans, this.snapshot.event);
-        this.docs.setRows(this.rows, this.snapshot.event, selectedKey ?? this.docs.selected?.key);
+        this.docs.setRows(this.rows, this.snapshot.event);
         this.syncDetail();
         this.plans.warm(() => {
             this.rows = buildRows(this.plans, this.snapshot.event);
-            this.docs.setRows(this.rows, this.snapshot.event, this.docs.selected?.key);
+            this.docs.setRows(this.rows, this.snapshot.event);
             this.syncDetail();
             this.tui.requestRender();
         });
@@ -101,13 +101,29 @@ export class ContextAdminShell {
         const row = this.docs.selected;
         const capOwner = row === undefined ? null : capOwnerFor(row.anchor, this.snapshot.profileId);
         const readOnly = row === undefined ? null : readOnlyReason(row.anchor, this.snapshot.profileId);
-        this.detail.setContext(row, this.snapshot.event, capOwner, readOnly);
+        // The plan's own subject, not a re-derived one: what a failed gate is
+        // explained against must be exactly what it was judged against.
+        this.detail.setContext(row, this.snapshot.event, capOwner, readOnly, this.plans.plan(this.snapshot.event).subject);
     }
     setSnapshot(next) {
+        const held = this.railRows()[this.railIndex];
         this.snapshot = next;
         this.plans.setSnapshot(next);
         this.notice = undefined;
         this.rebuild();
+        this.holdRail(held);
+    }
+    /** Put the rail cursor back on the row it was on, since dialling a different
+     *  event moves the payload row and every offset below it. The payload belongs
+     *  to the dialled event, so when the new event reads none the cursor falls to
+     *  that event's own row rather than to whatever slid into the offset. */
+    holdRail(held) {
+        if (held === undefined)
+            return;
+        const rows = this.railRows();
+        const key = railRowKey(held);
+        const at = rows.findIndex((row) => railRowKey(row) === key);
+        this.railIndex = Math.max(0, at >= 0 ? at : rows.findIndex((row) => row.kind === 'event' && row.event.dialled));
     }
     // input
     matches(id, data) {
@@ -172,31 +188,47 @@ export class ContextAdminShell {
         else
             this.handleDetail(data);
     }
-    /** The rail's rows are the snapshot axes followed by the filter facets, so
-     *  one cursor and one gesture drive both sections. */
+    /** Every surface event with what it delivers, which is what the rail states
+     *  instead of the list drawing a cell per event on every row. An event whose
+     *  plan has not warmed yet has no count to state. */
+    eventRows() {
+        return SURFACE_EVENTS.map((event) => {
+            const plan = this.plans.peek(event);
+            return {
+                event,
+                delivers: plan === undefined ? undefined : plan.docs.filter((record) => record.finalRung !== 'none').length,
+                dialled: event === this.snapshot.event,
+            };
+        });
+    }
+    /** The rail's rows: the events, then the snapshot axes, then the filter
+     *  facets, so one cursor and one gesture drive all three sections. */
+    railRows() {
+        return railRowsOf(this.eventRows(), payloadRowOf(this.snapshot), axesOf(this.snapshot, profileNameFor(this.snapshot.profileId) ?? 'none'), facetsOf(this.filters));
+    }
     handleRail(data) {
-        const axes = axesOf(this.snapshot, profileNameFor(this.snapshot.profileId) ?? 'none');
-        const facets = facetsOf(this.filters);
-        const total = axes.length + facets.length;
-        this.railIndex = Math.max(0, Math.min(this.railIndex, total - 1));
-        const axis = axes[this.railIndex];
-        const facet = facets[this.railIndex - axes.length];
+        const rows = this.railRows();
+        this.railIndex = Math.max(0, Math.min(this.railIndex, rows.length - 1));
+        const row = rows[this.railIndex];
         const change = (delta) => {
-            if (axis !== undefined) {
-                if (axis.typed)
-                    this.openAxisField(axis.id, axis.label);
-                else
-                    this.setSnapshot(cycleAxis(this.snapshot, axis.id, delta));
-            }
-            else if (facet !== undefined) {
-                if (facet.typed)
-                    this.openSearch();
+            if (row === undefined)
+                return;
+            if (row.kind === 'event')
+                this.setSnapshot({ ...this.snapshot, event: row.event.event });
+            else if (row.kind === 'axis') {
+                if (row.axis.typed)
+                    this.openAxisField(row.axis.id, row.axis.label);
                 else
-                    this.setFilters(cycleFacet(this.filters, facet.id, delta));
+                    this.setSnapshot(cycleAxis(this.snapshot, row.axis.id, delta));
             }
+            else if (row.facet.typed)
+                this.openSearch();
+            else
+                this.setFilters(cycleFacet(this.filters, row.facet.id, delta));
         };
+        const onEnter = railEnter(row);
         if (this.isDown(data)) {
-            this.railIndex = Math.min(total - 1, this.railIndex + 1);
+            this.railIndex = Math.min(rows.length - 1, this.railIndex + 1);
         }
         else if (this.isUp(data)) {
             this.railIndex = Math.max(0, this.railIndex - 1);
@@ -205,7 +237,7 @@ export class ContextAdminShell {
             change(1);
         }
         else if (this.isDescend(data)) {
-            if (matchesKey(data, 'enter') && (axis?.typed === true || facet?.typed === true))
+            if (matchesKey(data, 'enter') && onEnter !== 'documents')
                 change(1);
             else
                 this.zone = 'docs';
@@ -231,9 +263,8 @@ export class ContextAdminShell {
             this.syncDetail();
         }
         else if (this.isDescend(data)) {
-            // A directory that is also a document keeps both gestures: space opens it,
-            // and descending goes to its dossier like any other document.
-            if (this.docs.onGroup && !this.docs.onDocument) {
+            // One gesture per row: a header expands, a document opens its dossier.
+            if (this.docs.onGroup) {
                 this.docs.toggleGroup();
                 this.syncDetail();
             }
@@ -695,7 +726,7 @@ export class ContextAdminShell {
         return out.slice(0, height);
     }
     // rendering
-    footer(width) {
+    footer(width, railRow) {
         if (this.busy !== undefined)
             return theme.fg('warning', this.busy);
         if (this.modal?.kind === 'choice')
@@ -710,7 +741,7 @@ export class ContextAdminShell {
             return theme.fg(this.notice.ok ? 'success' : 'warning', truncateToWidth(this.notice.text, width));
         const move = `${this.label('crtr.setup.list-down', 'j')}/${this.label('crtr.setup.list-up', 'k')}`;
         const left = this.zone === 'rail'
-            ? `${move} row · space change · enter documents`
+            ? `${move} row · ${railGesture(railRow)}`
             : this.zone === 'docs'
                 ? `${move} row · ${this.docsGesture()} · / search`
                 : this.detail.editing
@@ -724,23 +755,19 @@ export class ContextAdminShell {
             ? `${theme.fg('dim', left)}${' '.repeat(gap)}${theme.fg('dim', right)}`
             : theme.fg('dim', truncateToWidth(`${left} · ${this.label('crtr.setup.cancel', 'q')} close`, width));
     }
-    /** What the focused row does when opened. A directory answers to space, a
-     *  document to enter, and a directory that is also a document to both. */
+    /** What the focused row does when opened. A directory expands; a document
+     *  opens its dossier. */
     docsGesture() {
-        if (!this.docs.onGroup)
-            return 'enter dossier';
-        return this.docs.onDocument ? 'space open · enter dossier' : 'space/enter open';
+        return this.docs.onGroup ? 'space/enter open' : 'enter dossier';
     }
     render(width) {
         const height = this.terminalRows();
         const bodyHeight = Math.max(1, height - PAGE_CHROME_ROWS);
         const railVisible = width >= RAIL_MIN_TOTAL_WIDTH;
-        const axes = axesOf(this.snapshot, profileNameFor(this.snapshot.profileId) ?? 'none');
-        const facets = facetsOf(this.filters);
-        this.railIndex = Math.max(0, Math.min(this.railIndex, axes.length + facets.length - 1));
+        const rows = this.railRows();
+        this.railIndex = Math.max(0, Math.min(this.railIndex, rows.length - 1));
         const rail = (railWidth) => renderRail({
-            axes,
-            facets,
+            rows,
             index: this.railIndex,
             width: railWidth,
             height: bodyHeight,
@@ -752,7 +779,7 @@ export class ContextAdminShell {
         if (width >= THREE_COLUMN_MIN_WIDTH) {
             const docsWidth = docsWidthFor(width);
             const detailWidth = Math.max(1, width - RAIL_WIDTH - docsWidth - DIVIDER_WIDTH);
-            const middle = columns(this.docs.render(docsWidth, bodyHeight, this.zone === 'docs', this.plans), docsWidth, this.modal === undefined
+            const middle = columns(this.docs.render(docsWidth, bodyHeight, this.zone === 'docs'), docsWidth, this.modal === undefined
                 ? this.detail.render(detailWidth, bodyHeight, this.zone === 'detail')
                 : this.renderModal(detailWidth, bodyHeight), detailWidth);
             body = columns(rail(RAIL_WIDTH), RAIL_WIDTH, middle, width - RAIL_WIDTH - 3);
@@ -763,7 +790,7 @@ export class ContextAdminShell {
                 ? this.renderModal(panelWidth, bodyHeight)
                 : this.zone === 'detail'
                     ? this.detail.render(panelWidth, bodyHeight, true)
-                    : this.docs.render(panelWidth, bodyHeight, this.zone === 'docs', this.plans);
+                    : this.docs.render(panelWidth, bodyHeight, this.zone === 'docs');
             body = columns(rail(RAIL_WIDTH), RAIL_WIDTH, panel, panelWidth);
         }
         else if (this.modal !== undefined) {
@@ -776,7 +803,7 @@ export class ContextAdminShell {
             body = this.detail.render(width, bodyHeight, true);
         }
         else {
-            body = this.docs.render(width, bodyHeight, true, this.plans);
+            body = this.docs.render(width, bodyHeight, true);
         }
         const pending = SURFACE_EVENTS.filter((event) => this.plans.peek(event) === undefined).length;
         const meta = [
@@ -787,7 +814,14 @@ export class ContextAdminShell {
         ]
             .filter((part) => part !== '')
             .join(' · ');
-        return pageFrame({ width, height, title: 'crouter context', meta, body, footer: this.footer(width) });
+        return pageFrame({
+            width,
+            height,
+            title: 'crouter context',
+            meta,
+            body,
+            footer: this.footer(width, rows[this.railIndex]),
+        });
     }
     /** What the delivering documents spend on this event. An estimate, and a
      *  floor on the rendered prompt: boot wraps these documents in its own intro
@@ -803,6 +837,19 @@ export class ContextAdminShell {
         return `docs load ${formatCost(total)} — ${split}`;
     }
 }
+/** What the focused rail row does, which differs by row: an event dials, a
+ *  typed row opens its field, and an enum cycles in place with enter left free
+ *  to move zones. */
+function railGesture(row) {
+    switch (railEnter(row)) {
+        case 'dial':
+            return 'space/enter dial · l documents';
+        case 'edit':
+            return 'space/enter edit · l documents';
+        default:
+            return 'space change · enter documents';
+    }
+}
 /** Every field here is an edit-or-accept, never a blank to retype, so the
  *  cursor lands at the end (`\x05`) — `setValue` alone leaves it at 0, where
  *  typing prepends and backspace does nothing. */

package/dist/commands/sys/context/doc.js

@@ -7,6 +7,7 @@ import { realpathOrSelf } from '../../../core/fs-utils.js';
 import { resolveMemoryDocForTarget } from '../../../core/memory-resolver.js';
 import { InputError } from '../../../core/io.js';
 import { planDelivery } from '../../../core/substrate/plan.js';
+import { explainRecordGate } from '../../../core/substrate/gate-explain.js';
 import { parseSubstrateDoc, SURFACE_EVENTS } from '../../../core/substrate/schema.js';
 import { buildSnapshot, cell, delivers, describeSubject, entryText, exclusionReason, gateText, optionalString, payloadFor, subjectSummary, } from './resolve.js';
 export const docLeaf = defineLeaf({
@@ -58,7 +59,7 @@ export const docLeaf = defineLeaf({
         const recordPathCache = new Map();
         const rows = events.map((event) => {
             const plan = planDelivery(snapshot.subject, snapshot.target, event, payloadFor(event, flags, snapshot.target));
-            return eventRow(event, findRecord(plan.docs, targetPath, recordPathCache));
+            return eventRow(event, findRecord(plan.docs, targetPath, recordPathCache), plan.subject);
         });
         return {
             name: doc.name,
@@ -111,7 +112,7 @@ function surfaceRow(entry) {
         at: entry.at,
     };
 }
-function eventRow(event, record) {
+function eventRow(event, record, subject) {
     if (record === null) {
         return {
             event,
@@ -133,12 +134,12 @@ function eventRow(event, record) {
         authored_rung: record.authoredRung,
         capped_rung: record.cappedRung,
         final_rung: record.finalRung,
-        doc_gate: gateText(record.docGate),
-        entry_gate: record.entryGate === null ? null : gateText(record.entryGate),
+        doc_gate: gateText(record.docGate, explainRecordGate(record, 'doc', subject)),
+        entry_gate: record.entryGate === null ? null : gateText(record.entryGate, explainRecordGate(record, 'entry', subject)),
         matched_entry: entryText(record.matchedEntry),
         winner: record.winner,
         shadowed_by: record.shadowedBy === null ? null : `${record.shadowedBy.scope}:${record.shadowedBy.path}`,
-        excluded: delivers(record) ? null : exclusionReason(record),
+        excluded: delivers(record) ? null : exclusionReason(record, subject),
     };
 }
 function corpusNote(event) {