@north-light/crouter 0.3.242 → 0.3.244

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

@@ -17,34 +17,45 @@ export interface Filters {
     query: string;
 }
 export declare const NO_FILTERS: Filters;
-/** One drawn line. A group carries what its members add up to, so a collapsed
- *  list still states where the corpus and its cost sit. */
+/** One drawn line. A group carries what its whole subtree adds up to, so a
+ *  collapsed list still states where the corpus and its cost sit. `depth` is
+ *  how many name segments sit above the line, which the renderer spends on
+ *  indent. */
 export type ListLine = {
     kind: 'group';
     key: string;
     label: string;
+    depth: number;
     docs: number;
     rungs: Record<Exclude<Rung, 'none'>, number>;
     cost: number;
     expanded: boolean;
-    /** The first member, so the dossier has a document to describe while the
-     *  cursor rests on the header. */
+    /** The document the dossier describes while the cursor rests on the
+     *  header: this directory's own document when it has one, else the first
+     *  document in its subtree. */
     first: DocRow;
+    /** True when the directory is itself a document — `first` is that
+     *  document, and the one row is both selectable and expandable. */
+    isDoc: boolean;
 } | {
     kind: 'doc';
     key: string;
     row: DocRow;
     label: string;
+    depth: number;
     cost: number;
 };
-export declare function groupKeyOf(name: string): string;
-/** Every group key the rows can produce, so collapse state can drop the keys a
- *  re-plan removed instead of accumulating them. */
+/** Every group key the rows can produce — one per proper name prefix, since a
+ *  prefix exists only because something sits under it — so collapse state can
+ *  drop the keys a re-plan removed instead of accumulating them. The leading
+ *  section is a key only when a name with no `/` owns no directory, which is
+ *  exactly when it is not itself one of those prefixes. */
 export declare function groupKeysOf(rows: readonly DocRow[]): Set<string>;
-/** The lines to draw, in corpus order: the leading section, then each group in
- *  order of first appearance. A live query force-expands every group holding a
- *  match without touching `expanded`, so clearing it restores what the user
- *  collapsed. */
+/** The lines to draw, in corpus order: the leading section, then each directory
+ *  in order of first appearance, each recursing into its own members only when
+ *  it is open. A live query force-expands every directory, which is exactly the
+ *  ancestor chain of every surviving match, without touching `expanded` — so
+ *  clearing the query restores what the user collapsed. */
 export declare function buildListView(rows: readonly DocRow[], filters: Filters, expanded: ReadonlySet<string>, event: SurfaceEvent): ListLine[];
 /** What the whole filtered set costs, split by the rung it arrives at. */
 export declare function costTotals(rows: readonly DocRow[], event: SurfaceEvent): {

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

@@ -4,78 +4,137 @@
 import { fuzzyMatch } from '../../../../core/tui/fuzzy.js';
 import { deliveredCost, rungCostsOf } from './model.js';
 export const NO_FILTERS = { rung: 'any', origin: 'any', kind: 'any', state: 'any', query: '' };
-/** Documents whose canonical name carries no `/` share one leading section
- *  rather than becoming a crowd of one-member groups. */
+/** Documents whose canonical name carries no `/` and owns no directory share
+ *  one leading section rather than becoming a crowd of one-member groups. */
 const LEADING_KEY = '';
 const LEADING_LABEL = 'top level';
-export function groupKeyOf(name) {
-    const cut = name.indexOf('/');
-    return cut < 0 ? LEADING_KEY : name.slice(0, cut);
-}
-/** Every group key the rows can produce, so collapse state can drop the keys a
- *  re-plan removed instead of accumulating them. */
+/** Every group key the rows can produce — one per proper name prefix, since a
+ *  prefix exists only because something sits under it — so collapse state can
+ *  drop the keys a re-plan removed instead of accumulating them. The leading
+ *  section is a key only when a name with no `/` owns no directory, which is
+ *  exactly when it is not itself one of those prefixes. */
 export function groupKeysOf(rows) {
-    return new Set(rows.map((row) => groupKeyOf(row.name)));
+    const keys = new Set();
+    const unslashed = [];
+    for (const row of rows) {
+        if (row.name.includes('/')) {
+            for (let cut = row.name.indexOf('/'); cut >= 0; cut = row.name.indexOf('/', cut + 1)) {
+                keys.add(row.name.slice(0, cut));
+            }
+        }
+        else
+            unslashed.push(row.name);
+    }
+    if (unslashed.some((name) => !keys.has(name)))
+        keys.add(LEADING_KEY);
+    return keys;
 }
-/** The lines to draw, in corpus order: the leading section, then each group in
- *  order of first appearance. A live query force-expands every group holding a
- *  match without touching `expanded`, so clearing it restores what the user
- *  collapsed. */
+/** The lines to draw, in corpus order: the leading section, then each directory
+ *  in order of first appearance, each recursing into its own members only when
+ *  it is open. A live query force-expands every directory, which is exactly the
+ *  ancestor chain of every surviving match, without touching `expanded` — so
+ *  clearing the query restores what the user collapsed. */
 export function buildListView(rows, filters, expanded, event) {
-    const groups = new Map();
-    const order = [];
+    const root = { key: '', segment: '', depth: -1, children: new Map(), selves: [] };
     for (const row of rows) {
         if (!passes(row, row.records.get(event), filters))
             continue;
-        const key = groupKeyOf(row.name);
-        const held = groups.get(key);
-        if (held === undefined) {
-            groups.set(key, [row]);
-            order.push(key);
+        let dir = root;
+        for (const segment of row.name.split('/')) {
+            let child = dir.children.get(segment);
+            if (child === undefined) {
+                child = {
+                    key: dir.depth < 0 ? segment : `${dir.key}/${segment}`,
+                    segment,
+                    depth: dir.depth + 1,
+                    children: new Map(),
+                    selves: [],
+                };
+                dir.children.set(segment, child);
+            }
+            dir = child;
         }
-        else
-            held.push(row);
+        dir.selves.push(row);
     }
-    if (groups.has(LEADING_KEY)) {
-        order.splice(order.indexOf(LEADING_KEY), 1);
-        order.unshift(LEADING_KEY);
+    const leading = [];
+    const dirs = [];
+    for (const child of root.children.values()) {
+        if (child.children.size === 0)
+            leading.push(...child.selves);
+        else
+            dirs.push(child);
     }
     const lines = [];
-    for (const key of order) {
-        const members = groups.get(key);
-        const rungs = { name: 0, preview: 0, content: 0 };
-        let cost = 0;
-        for (const row of members) {
-            const record = row.records.get(event);
-            if (record !== undefined && record.finalRung !== 'none')
-                rungs[record.finalRung] += 1;
-            cost += deliveredCost(record);
-        }
-        const open = filters.query !== '' || expanded.has(key);
+    if (leading.length > 0) {
+        const open = filters.query !== '' || expanded.has(LEADING_KEY);
         lines.push({
             kind: 'group',
-            key,
-            label: key === LEADING_KEY ? LEADING_LABEL : `${key}/`,
-            docs: members.length,
-            rungs,
-            cost,
+            key: LEADING_KEY,
+            label: LEADING_LABEL,
+            depth: 0,
+            ...rollup(leading, event),
             expanded: open,
-            first: members[0],
+            first: leading[0],
+            isDoc: false,
         });
-        if (!open)
-            continue;
-        for (const row of members) {
-            lines.push({
-                kind: 'doc',
-                key: row.key,
-                row,
-                label: key === LEADING_KEY ? row.name : row.name.slice(key.length + 1),
-                cost: deliveredCost(row.records.get(event)),
-            });
-        }
+        if (open)
+            for (const row of leading)
+                lines.push(docLine(row, row.name, 1, event));
     }
+    for (const dir of dirs)
+        emit(dir, filters, expanded, event, lines);
     return lines;
 }
+/** A directory's rows in drawn order: its own document first, then each child
+ *  segment's subtree — so the head of the list is also the document the header
+ *  hands the dossier. */
+function subtree(dir, out = []) {
+    out.push(...dir.selves);
+    for (const child of dir.children.values())
+        subtree(child, out);
+    return out;
+}
+function emit(dir, filters, expanded, event, lines) {
+    if (dir.children.size === 0) {
+        for (const row of dir.selves)
+            lines.push(docLine(row, dir.segment, dir.depth, event));
+        return;
+    }
+    const members = subtree(dir);
+    const open = filters.query !== '' || expanded.has(dir.key);
+    lines.push({
+        kind: 'group',
+        key: dir.key,
+        label: `${dir.segment}/`,
+        depth: dir.depth,
+        ...rollup(members, event),
+        expanded: open,
+        first: members[0],
+        isDoc: dir.selves.length > 0,
+    });
+    if (!open)
+        return;
+    // The header already stands for the first document named exactly this path;
+    // a second store answering the same name still needs its own row.
+    for (const shadowed of dir.selves.slice(1))
+        lines.push(docLine(shadowed, dir.segment, dir.depth + 1, event));
+    for (const child of dir.children.values())
+        emit(child, filters, expanded, event, lines);
+}
+function docLine(row, label, depth, event) {
+    return { kind: 'doc', key: row.key, row, label, depth, cost: deliveredCost(row.records.get(event)) };
+}
+function rollup(members, event) {
+    const rungs = { name: 0, preview: 0, content: 0 };
+    let cost = 0;
+    for (const row of members) {
+        const record = row.records.get(event);
+        if (record !== undefined && record.finalRung !== 'none')
+            rungs[record.finalRung] += 1;
+        cost += deliveredCost(record);
+    }
+    return { docs: members.length, rungs, cost };
+}
 /** What the whole filtered set costs, split by the rung it arrives at. */
 export function costTotals(rows, event) {
     const byRung = { name: 0, preview: 0, content: 0 };

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

@@ -0,0 +1,27 @@
+import { type Rung, type SurfaceEvent } from '../../../../core/substrate/schema.js';
+import type { DeliveryRecord } from '../../../../core/substrate/plan.js';
+/** The profile project entry whose `memory` rung ceilings this document's
+ *  store, or null when no project governs it. */
+export interface CapOwner {
+    path: string;
+    memory: Rung;
+}
+/** What the read face needs beyond the record: the event it is judged against,
+ *  the sibling events' records, and the two facts the shell resolves. */
+export interface DossierContext {
+    event: SurfaceEvent;
+    records: Map<SurfaceEvent, DeliveryRecord>;
+    capOwner: CapOwner | null;
+    readOnly: boolean;
+}
+/** The resting card, and — when `bodyOpen` — the document's own text beneath
+ *  it in place of the affordance line that names it. */
+export declare function renderDossierRead(record: DeliveryRecord, context: DossierContext, width: number, bodyOpen: boolean): string[];
+/** Identity and routing — what the edit face keeps overhead of its field list,
+ *  because they are the context a field is being edited against. */
+export declare function renderDossierHeader(record: DeliveryRecord, context: DossierContext, width: number): string[];
+/** Does it load here, what does it cost, and — only when there is one — what
+ *  interfered. The three questions the old verdict, cost table and event grid
+ *  each answered a piece of. */
+export declare function renderDossierDelivery(record: DeliveryRecord, context: DossierContext, width: number): string[];
+export declare function bodyLineCount(body: string): number;

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

@@ -0,0 +1,152 @@
+// The dossier's read face: one memory document as the thing a person reads to
+// decide whether it should load into this context.
+//
+// Pure rendering. It returns styled lines already wrapped to `width` and never
+// truncates a value — the panel scrolls, so scrolling is the only thing that
+// hides text, and "the routing line never ellipsizes" is structural rather than
+// a rule someone has to remember.
+//
+// One rule decides what appears: a line renders only when it changes what the
+// reader would conclude. A gate that is unset, a cap that lowers nothing, an
+// event that delivers nothing — all absent.
+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 { 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. */
+const READ_ONLY_GLYPH = '\u2298';
+/** Every column but the left margin, which every line of the card carries. */
+const INDENT = ' ';
+/** The resting card, and — when `bodyOpen` — the document's own text beneath
+ *  it in place of the affordance line that names it. */
+export function renderDossierRead(record, context, width, bodyOpen) {
+    const inner = Math.max(1, width - INDENT.length);
+    const out = renderDossierHeader(record, context, width);
+    if (record.doc.shortForm.trim() !== '') {
+        out.push('');
+        out.push(...indent(wrapped(record.doc.shortForm, inner)));
+    }
+    out.push(...renderDossierDelivery(record, context, width));
+    const lines = bodyLineCount(record.doc.body);
+    if (bodyOpen) {
+        out.push('');
+        out.push(...indent(new Markdown(record.doc.body, 0, 0, getMarkdownTheme()).render(inner)));
+    }
+    else if (lines === 0) {
+        out.push('', ...dim('no body — this document is its routing line', width));
+    }
+    else {
+        out.push('', ...dim(`enter  read the body \u2014 ${plural(lines, 'line', 'lines')}`, width));
+    }
+    return out;
+}
+/** A dim line of the card, kept exactly as written while the row can hold it
+ *  and wrapped when it cannot — so a narrow dossier costs a second row rather
+ *  than an ellipsis. */
+function dim(text, width) {
+    const inner = Math.max(1, width - INDENT.length);
+    return visibleWidth(text) <= inner
+        ? [`${INDENT}${theme.fg('dim', text)}`]
+        : indent(wrapped(text, inner)).map((line) => theme.fg('dim', line));
+}
+/** Identity and routing — what the edit face keeps overhead of its field list,
+ *  because they are the context a field is being edited against. */
+export function renderDossierHeader(record, context, width) {
+    const inner = Math.max(1, width - INDENT.length);
+    const out = identityLines(record, context, inner);
+    out.push('', theme.fg('dim', `${INDENT}READ WHEN`));
+    const routing = record.doc.whenAndWhyToRead.trim();
+    out.push(...(routing === ''
+        ? [theme.fg('dim', `${INDENT}Not declared.`)]
+        : indent(wrapped(routing, inner))));
+    return out;
+}
+/** The name, with the metadata cluster pushed to the far right of the same row
+ *  whenever both fit. A name too long to share the row keeps every character
+ *  and the cluster drops to its own row. */
+function identityLines(record, context, inner) {
+    const meta = `${record.kind} \u00b7 ${record.scope}${record.nodeLocal ? ' \u00b7 node-local' : ''}${context.readOnly ? ` ${READ_ONLY_GLYPH}` : ''}`;
+    const names = wrapped(record.name, inner);
+    const out = names.map((line) => `${INDENT}${theme.fg('accent', theme.bold(line))}`);
+    const last = names[names.length - 1] ?? '';
+    const gap = inner - visibleWidth(last) - visibleWidth(meta);
+    if (gap >= 2) {
+        out[out.length - 1] = `${INDENT}${theme.fg('accent', theme.bold(last))}${' '.repeat(gap)}${theme.fg('dim', meta)}`;
+        return out;
+    }
+    // The cluster takes its own row, right-aligned under the name — or its own
+    // rows, when the dossier is too narrow to hold it in one.
+    out.push(...wrapped(meta, inner).map((line) => `${INDENT}${' '.repeat(Math.max(0, inner - visibleWidth(line)))}${theme.fg('dim', line)}`));
+    return out;
+}
+/** Does it load here, what does it cost, and — only when there is one — what
+ *  interfered. The three questions the old verdict, cost table and event grid
+ *  each answered a piece of. */
+export function renderDossierDelivery(record, context, width) {
+    const inner = Math.max(1, width - INDENT.length);
+    const costs = rungCostsOf(record);
+    const delivers = record.finalRung !== 'none';
+    const ceilingLowered = rungRank(record.cappedRung) < rungRank(record.authoredRung);
+    const rung = delivers ? record.finalRung : 'nothing';
+    const cost = delivers ? ` \u00b7 ${formatCost(costs[record.finalRung]) || '~0'} of ${formatCost(costs.content) || '~0'}` : '';
+    const color = !delivers ? 'dim' : ceilingLowered ? 'warning' : 'success';
+    const asked = `${context.event} \u2192 `;
+    const answer = `${rung}${cost}`;
+    const out = [''];
+    if (visibleWidth(asked) + visibleWidth(answer) <= inner) {
+        out.push(`${INDENT}${theme.fg('dim', asked)}${theme.fg(color, rung)}${theme.fg('dim', cost)}`);
+    }
+    else {
+        // Too narrow for one row: the event names itself and its verdict wraps
+        // beneath, rather than the cost ellipsizing off the end.
+        out.push(...indent(wrapped(asked, inner)).map((line) => theme.fg('dim', line)));
+        out.push(...indent(wrapped(answer, inner)).map((line) => theme.fg(color, line)));
+    }
+    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}`);
+    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)));
+    }
+    if (ceilingLowered) {
+        warn(context.capOwner === null
+            ? `capped to ${record.cappedRung} by a profile ceiling on this store`
+            : `capped to ${record.cappedRung} by the ${context.capOwner.memory} ceiling on ${context.capOwner.path}`);
+    }
+    if (record.shadowedBy !== null) {
+        out.push(...indent(wrapped(`shadowed by the ${record.shadowedBy.scope} copy at ${record.shadowedBy.path}`, inner)).map((line) => theme.fg('muted', line)));
+    }
+    const also = SURFACE_EVENTS.filter((event) => event !== context.event)
+        .map((event) => ({ event, held: context.records.get(event) }))
+        .filter((pair) => pair.held !== undefined && pair.held.finalRung !== 'none')
+        .map((pair) => `${pair.event} \u2192 ${pair.held.finalRung}`);
+    if (also.length > 0) {
+        out.push(...indent(wrapped(`also ${also.join(' \u00b7 ')}`, inner)).map((line) => theme.fg('dim', line)));
+    }
+    return out;
+}
+export function bodyLineCount(body) {
+    const trimmed = body.replace(/\n+$/, '');
+    return trimmed === '' ? 0 : trimmed.split('\n').length;
+}
+function indent(lines) {
+    return lines.map((line) => `${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
+ *  instead, so an over-wide token breaks rather than becoming an ellipsis. */
+function wrapped(text, width) {
+    const clean = text.trim();
+    if (clean === '')
+        return [];
+    return clean.split(/\s+/).some((word) => visibleWidth(word) > width)
+        ? wrapTextWithAnsi(clean, width)
+        : wrapText(clean, width);
+}

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

@@ -63,6 +63,18 @@ export declare class ContextAdminShell implements Component, Focusable {
      *  modal over the rows it is selecting. */
     private handleSearch;
     private handleDetail;
+    /** The resting face: reading, and the two gestures that leave it. */
+    private handleRead;
+    /** The field list. Every write gesture is resolved before it is started, so a
+     *  read-only document refuses at the keypress rather than after a modal. */
+    private handleEdit;
+    /** The write one edit-face key starts, or undefined when the key writes
+     *  nothing. `document` marks the writes a read-only document refuses — the
+     *  profile ceiling is not one of them; it lives in the profile manifest. */
+    private writeGesture;
+    /** The refusal a read-only document owes the write just attempted, carried by
+     *  the same footer channel every other write outcome uses. */
+    private refusesWrite;
     /** What the focused dossier row does when opened — the same write its letter
      *  key starts, so a user who never learns the letters can still edit. */
     private activate;
@@ -90,6 +102,9 @@ 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. */
+    private docsGesture;
     render(width: number): string[];
     /** 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

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

@@ -158,7 +158,10 @@ export class ContextAdminShell {
             this.setSnapshot(cycleAxis(this.snapshot, 'event', step));
             return;
         }
-        if (matchesKey(data, 'q') || this.matches('crtr.setup.cancel', data)) {
+        // `crtr.setup.cancel` also claims ctrl+d, so the read face's half-pane
+        // gesture has to outrank it or paging a body would close the page instead.
+        const pagesBody = this.zone === 'detail' && !this.detail.editing && matchesKey(data, 'ctrl+d');
+        if (!pagesBody && (matchesKey(data, 'q') || this.matches('crtr.setup.cancel', data))) {
             this.close();
             return;
         }
@@ -228,7 +231,9 @@ export class ContextAdminShell {
             this.syncDetail();
         }
         else if (this.isDescend(data)) {
-            if (this.docs.onGroup) {
+            // 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) {
                 this.docs.toggleGroup();
                 this.syncDetail();
             }
@@ -266,35 +271,101 @@ export class ContextAdminShell {
         this.tui.requestRender();
     }
     handleDetail(data) {
+        if (this.detail.editing)
+            this.handleEdit(data);
+        else
+            this.handleRead(data);
+    }
+    /** The resting face: reading, and the two gestures that leave it. */
+    handleRead(data) {
         if (this.isDown(data))
             this.detail.move(1);
         else if (this.isUp(data))
             this.detail.move(-1);
-        else if (this.isAscend(data) || matchesKey(data, 'escape'))
-            this.zone = 'docs';
-        else if (matchesKey(data, 'enter') || matchesKey(data, 'space') || this.matches('crtr.setup.toggle', data)) {
-            this.activate();
-        }
-        else if (matchesKey(data, 'b'))
-            this.editBody();
-        else if (matchesKey(data, 'x'))
-            this.removeEntry();
-        else if (matchesKey(data, 'e'))
-            this.composeEntry();
-        else if (matchesKey(data, 'g'))
-            this.editGate();
-        else if (matchesKey(data, 'u'))
-            this.flip('unlisted');
-        else if (matchesKey(data, 's'))
-            this.flip('slash');
-        else if (matchesKey(data, 'm'))
-            this.editCap();
-        else if (matchesKey(data, 'r'))
-            this.editMove();
-        else if (matchesKey(data, 'w'))
-            this.editRouting();
-        else if (matchesKey(data, 'f'))
-            this.editShortForm();
+        else if (matchesKey(data, 'ctrl+d'))
+            this.detail.page(1);
+        else if (matchesKey(data, 'ctrl+u'))
+            this.detail.page(-1);
+        else if (data === 'G' || matchesKey(data, 'shift+g'))
+            this.detail.jump('bottom');
+        else if (data === 'g' || matchesKey(data, 'g'))
+            this.detail.jump('top');
+        else if (data === 'e' || matchesKey(data, 'e'))
+            this.detail.edit();
+        else if (this.isDescend(data))
+            this.detail.openBody();
+        else if (this.isAscend(data) || matchesKey(data, 'escape')) {
+            if (!this.detail.back())
+                this.zone = 'docs';
+        }
+    }
+    /** The field list. Every write gesture is resolved before it is started, so a
+     *  read-only document refuses at the keypress rather than after a modal. */
+    handleEdit(data) {
+        if (this.isDown(data)) {
+            this.detail.move(1);
+            return;
+        }
+        if (this.isUp(data)) {
+            this.detail.move(-1);
+            return;
+        }
+        if (this.isAscend(data) || matchesKey(data, 'escape')) {
+            this.detail.back();
+            return;
+        }
+        const gesture = this.writeGesture(data);
+        if (gesture === undefined)
+            return;
+        if (gesture.document && this.refusesWrite())
+            return;
+        gesture.start();
+    }
+    /** The write one edit-face key starts, or undefined when the key writes
+     *  nothing. `document` marks the writes a read-only document refuses — the
+     *  profile ceiling is not one of them; it lives in the profile manifest. */
+    writeGesture(data) {
+        const doc = (start) => ({ start, document: true });
+        if (matchesKey(data, 'enter') || matchesKey(data, 'space') || this.matches('crtr.setup.toggle', data)) {
+            const row = this.detail.selected;
+            if (row === undefined)
+                return undefined;
+            return row.kind === 'cap' ? { start: () => this.editCap(), document: false } : doc(() => this.activate());
+        }
+        if (matchesKey(data, 'm'))
+            return { start: () => this.editCap(), document: false };
+        if (matchesKey(data, 'b'))
+            return doc(() => this.editBody());
+        if (matchesKey(data, 'x'))
+            return doc(() => this.removeEntry());
+        if (matchesKey(data, 'e'))
+            return doc(() => this.composeEntry());
+        if (matchesKey(data, 'g'))
+            return doc(() => this.editGate());
+        if (matchesKey(data, 'u'))
+            return doc(() => this.flip('unlisted'));
+        if (matchesKey(data, 's'))
+            return doc(() => this.flip('slash'));
+        if (matchesKey(data, 'r'))
+            return doc(() => this.editMove());
+        if (matchesKey(data, 'w'))
+            return doc(() => this.editRouting());
+        if (matchesKey(data, 'f'))
+            return doc(() => this.editShortForm());
+        return undefined;
+    }
+    /** The refusal a read-only document owes the write just attempted, carried by
+     *  the same footer channel every other write outcome uses. */
+    refusesWrite() {
+        const record = this.record;
+        if (record === undefined)
+            return false;
+        const refusal = readOnlyReason(record, this.snapshot.profileId);
+        if (refusal === null)
+            return false;
+        this.notice = { text: refusal, ok: false };
+        this.tui.requestRender();
+        return true;
     }
     /** What the focused dossier row does when opened — the same write its letter
      *  key starts, so a user who never learns the letters can still edit. */
@@ -470,13 +541,6 @@ export class ContextAdminShell {
         const record = this.record;
         if (record === undefined)
             return;
-        // Checked before the terminal leaves for $EDITOR, so a read-only record
-        // refuses in place rather than after a whole editing session.
-        const refusal = readOnlyReason(record, this.snapshot.profileId);
-        if (refusal !== null) {
-            this.notice = { text: refusal, ok: false };
-            return;
-        }
         let before;
         try {
             before = readBody(record);
@@ -648,14 +712,25 @@ export class ContextAdminShell {
         const left = this.zone === 'rail'
             ? `${move} row · space change · enter documents`
             : this.zone === 'docs'
-                ? `${move} row · space ${this.docs.onGroup ? 'open group' : 'group'} · / search · enter dossier`
-                : `${move} field · enter edit · e add · x remove · g gate · b body · u unlisted · s slash · m cap · r rename`;
+                ? `${move} row · ${this.docsGesture()} · / search`
+                : this.detail.editing
+                    ? `${move} field · enter edit · e add · x remove · g gate · b body · u unlisted · s slash · m cap · r rename · esc read`
+                    : this.detail.bodyOpen
+                        ? `${move} scroll · ctrl-d/u page · g/G ends · esc collapse`
+                        : `${move} scroll · enter body · e edit · esc list`;
         const right = `${this.label('crtr.setup.tab-next', 'tab')} event · ${this.label('crtr.setup.cancel', 'q')} close`;
         const gap = width - visibleWidth(left) - visibleWidth(right);
         return gap >= 2
             ? `${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. */
+    docsGesture() {
+        if (!this.docs.onGroup)
+            return 'enter dossier';
+        return this.docs.onDocument ? 'space open · enter dossier' : 'space/enter open';
+    }
     render(width) {
         const height = this.terminalRows();
         const bodyHeight = Math.max(1, height - PAGE_CHROME_ROWS);