@zenera/cli 1.1.18 → 1.1.19

package/dist/tui/theme.d.ts

@@ -1,10 +1,17 @@
-export type Appearance = 'dark' | 'light';
-/** The roles a line can play in the transcript. */
-export type Kind = 'you' | 'agent' | 'tool' | 'note' | 'error';
+import { type Appearance } from '../term.ts';
+export type { Appearance };
+/**
+ * The roles a line can play in the transcript.
+ *
+ * `text` is what the agent said on its way somewhere — prose between one batch
+ * of calls and the next — and `agent` is the answer it finished on, which is
+ * the only one that gets a box. Reasoning is not among them: it is progress,
+ * and progress that has finished is worth no rows at all.
+ */
+export type Kind = 'you' | 'text' | 'agent' | 'tool' | 'note' | 'error';
 export interface LineStyle {
     /** `undefined` means the terminal's own foreground. */
     readonly color?: string;
-    readonly dim?: boolean;
 }
 export interface Theme {
     readonly appearance: Appearance;
@@ -13,13 +20,25 @@ export interface Theme {
     readonly accent: string;
     /** Read-only badge, busy label. */
     readonly warn: string;
+    /**
+     * Box rules, clocks, the footer's numbers, the call rows. One step quieter
+     * than the prose and never two — stated as a grey because `dim` is a
+     * request the terminal is free to over-honour, and some do.
+     */
+    readonly chrome: LineStyle;
     /**
      * Reasoning. It is not a tool call and it is not the answer, and drawn in
-     * the same dim foreground as the rows around it there was nothing to say
-     * which — a wall of one weight reads as one thing. Its own hue is what
-     * separates the model's thinking from the work it went on to do.
+     * the same grey as the rows around it there was nothing to say which — a
+     * wall of one weight reads as one thing. Its own hue is what separates the
+     * model's thinking from the work it went on to do.
      */
     readonly thinking: LineStyle;
+    /**
+     * The three things a turn spends time on. One word in the footer says which,
+     * and it is read at a glance from across a desk — so the word changing is
+     * backed by the colour changing, not left to be spelled out.
+     */
+    readonly phase: Record<'reasoning' | 'waiting' | 'working', string>;
     /**
      * Branch colours, cycled in order of first sight. A fan-out is the one
      * place where colour carries information rather than decoration: eight

package/dist/tui/theme.js

@@ -13,47 +13,71 @@
 // unreadable on dark and invisible on paper. What is left is the handful of
 // accents that ANSI *does* let a light theme get wrong, so those swap.
 //
-// Dim is spent on *chrome* — box rules, clocks, the footer's numbers — and no
-// longer on content. Tool rows are most of what is on screen, and dimming them
-// put the bulk of the transcript one step from unreadable: the whole thing read
-// as too dark. They are content, so they get the foreground like content does.
+// A second weight is spent on *chrome* and on the machinery: box rules,
+// clocks, the footer's numbers, and the call rows that say how an answer was
+// arrived at. What the agent actually said is drawn at full weight in the
+// terminal's own foreground, so a transcript read top to bottom reads as prose
+// with the work annotated beside it — not as one undifferentiated wall.
 //
-// Note what is *not* here: no hex, no 256-colour ramps, no attempt at a brand.
-// A palette that ignores the user's scheme is worse on both schemes than one
-// that mostly defers to it.
+// That weight used to be SGR 2 (`dim`), and it was the third version of the
+// same bug. `dim` is not a colour, it is an instruction, and how far it is
+// obeyed is the terminal's business: iTerm2 takes a step, Apple Terminal
+// blends most of the way to the background. On Terminal.app the entire margin
+// — every rule, every call row, every number — went out with it.
+//
+// So there is exactly one ramp here, `chrome`, and it is a stated grey rather
+// than an attribute. It is the only number in the file, and it buys the one
+// thing deference cannot: a floor under the quiet half of the screen.
+// Everything else is still named by role and still defers to the user's own
+// scheme — no brand, no second hue, no 256-colour palette.
 // ---------------------------------------------------------------------------
+import { appearance, CHROME } from "../term.js";
+// The two greys, shared with every one-shot command so a `zen check` table and
+// a TUI call row are the same weight. Chalk steps them down for a 16-colour
+// terminal, which is the only place the old `gray` problem is still reachable.
+const DARK_CHROME = { color: `ansi256(${CHROME.dark})` };
+const LIGHT_CHROME = { color: `ansi256(${CHROME.light})` };
 const DARK = {
     appearance: 'dark',
     line: {
         you: { color: 'cyan' },
+        text: {},
         agent: {},
-        // Never dim, and never `gray`: bright black is already the faintest
-        // colour a terminal has, and either one puts the bulk of the
-        // transcript a step from unreadable.
-        tool: {},
+        // A call is the machinery, not the work: the transcript is read for
+        // what the agent said, and the rows saying how it found out are a
+        // margin note beside that.
+        tool: DARK_CHROME,
         note: { color: 'cyan' },
         error: { color: 'red' },
     },
     accent: 'cyan',
     warn: 'yellow',
-    thinking: { color: 'magenta' },
+    chrome: DARK_CHROME,
+    // Bright: the gist is one line among many and plain `magenta` on black is
+    // the darkest of the six.
+    thinking: { color: 'magentaBright' },
+    phase: { reasoning: 'magenta', waiting: 'yellow', working: 'cyan' },
     lanes: ['cyan', 'green', 'yellow', 'blue', 'red', 'magenta'],
 };
 // On a light background `cyan` and `yellow` are barely darker than the paper.
-// Dimmed default foreground and `blue`/`magenta` are the same information,
-// still legible.
+// Grey and `blue`/`magenta` are the same information, still legible.
 const LIGHT = {
     appearance: 'light',
     line: {
         you: { color: 'blue' },
+        text: {},
         agent: {},
-        tool: {},
+        tool: LIGHT_CHROME,
         note: { color: 'blue' },
         error: { color: 'red' },
     },
     accent: 'blue',
     warn: 'magenta',
+    chrome: LIGHT_CHROME,
     thinking: { color: 'magenta' },
+    // No yellow: `waiting` takes blue and `working` green, which are the two
+    // that survive paper.
+    phase: { reasoning: 'magenta', waiting: 'blue', working: 'green' },
     // No cyan or yellow: on paper they are barely darker than the paper.
     lanes: ['blue', 'green', 'red', 'magenta'],
 };
@@ -67,23 +91,17 @@ export async function resolveTheme(choice) {
     if (asked !== 'auto') {
         return THEMES[asked];
     }
-    return THEMES[(await queryBackground()) ?? fromColorFgBg() ?? 'dark'];
-}
-/**
- * `COLORFGBG` is `fg;bg` or `fg;<something>;bg`; the background is the last
- * field. Anything non-numeric (notably `default`) tells us nothing.
- */
-function fromColorFgBg() {
-    const parts = process.env['COLORFGBG']?.split(';');
-    const bg = parts?.[parts.length - 1];
-    if (bg === undefined || !/^\d+$/.test(bg)) {
-        return undefined;
-    }
-    const n = Number(bg);
-    return n === 7 || n >= 9 ? 'light' : 'dark';
+    return THEMES[(await queryBackground()) ?? appearance()];
 }
-const QUERY = '\u001b]11;?\u0007';
+// The DA1 behind the colour query is what makes the answer conclusive. Every
+// terminal replies to DA1, and none replies to it ahead of an OSC 11 it
+// supports — so a DA1 arriving alone means "I do not do that", known in one
+// round trip instead of guessed at the end of a timeout. What is left for the
+// timeout is the terminal that answers neither, which is the only case worth
+// waiting on and now the only one that does.
+const QUERY = '\u001b]11;?\u0007\u001b[c';
 const REPLY = /\u001b\]11;rgb:([\da-f]{1,4})\/([\da-f]{1,4})\/([\da-f]{1,4})/i;
+const DA1 = /\u001b\[\?[\d;]*c/;
 /**
  * Ask the terminal for its background colour and read the answer off stdin.
  *
@@ -93,7 +111,7 @@ const REPLY = /\u001b\]11;rgb:([\da-f]{1,4})\/([\da-f]{1,4})\/([\da-f]{1,4})/i;
  * and nothing else. Anything the user typed in that window is put back, so
  * the first keystroke of a fast start is not eaten by the handshake.
  */
-async function queryBackground(timeoutMs = 120) {
+async function queryBackground(timeoutMs = 300) {
     const { stdin, stdout } = process;
     if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== 'function') {
         return undefined;
@@ -102,6 +120,7 @@ async function queryBackground(timeoutMs = 120) {
     let timer;
     let settled = false;
     let seen = '';
+    let found;
     return await new Promise((resolve) => {
         const finish = (result) => {
             if (settled) {
@@ -114,26 +133,33 @@ async function queryBackground(timeoutMs = 120) {
             if (!wasRaw) {
                 stdin.pause();
             }
-            const typed = seen.replace(REPLY, '').replace(/\u001b\\|\u0007/g, '');
+            const typed = seen
+                .replace(REPLY, '')
+                .replace(DA1, '')
+                .replace(/\u001b\\|\u0007/g, '');
             if (typed) {
                 stdin.unshift(Buffer.from(typed, 'latin1'));
             }
             resolve(result);
         };
+        // The DA1 is sent second and answered second, so it is the end of the
+        // conversation whether or not the colour came back. Settling on the
+        // colour alone leaves the DA1 in the pipe, and it surfaces a moment
+        // later as `[?64;1;2;...c` typed into the prompt.
         const onData = (chunk) => {
             seen += chunk.toString('latin1');
             const m = REPLY.exec(seen);
             if (m) {
-                finish(appearanceOf(m[1], m[2], m[3]));
+                found = appearanceOf(m[1], m[2], m[3]);
             }
-            else if (seen.length > 256) {
-                finish(undefined);
+            if (DA1.test(seen) || seen.length > 256) {
+                finish(found);
             }
         };
         stdin.setRawMode(true);
         stdin.resume();
         stdin.on('data', onData);
-        timer = setTimeout(() => finish(undefined), timeoutMs);
+        timer = setTimeout(() => finish(found), timeoutMs);
         timer.unref?.();
         stdout.write(QUERY);
     });

package/dist/tui/wrap.d.ts

@@ -17,26 +17,33 @@ export declare function clip(text: string, width: number): string;
 export declare function wrap(text: string, width: number): string[];
 /** The three footer rows, its margin, the prompt, and a row in hand. */
 export declare const CHROME_ROWS = 7;
-/** How much of the reasoning stream is worth showing. It is a progress bar. */
-export declare const THINKING_ROWS = 6;
+/**
+ * How much of the reasoning stream is worth showing.
+ *
+ * One row. A reasoning summary is not a document to be read while it arrives —
+ * it is the model saying what it is about to do, and the sentence that says so
+ * is the heading it writes for itself. Six rows of it pushed the answer and the
+ * work down the screen to make room for a paragraph nobody finishes reading,
+ * and the whole chain is in the trajectory either way.
+ */
+export declare const THINKING_ROWS = 1;
 /** How much of the frame the work in flight may take. A branch is a box now,
  *  not a row, so a fan-out of two costs fourteen of these. */
 export declare const ACTIVITY_ROWS = 16;
-/** The rule that opens a reasoning block and the one that closes it. */
-export declare const THINKING_CHROME = 2;
+/** The width of the elapsed-time column every call row is drawn behind. */
+export declare const TIME_COL = 5;
 export interface Budget {
     /** rows for the list of what is in flight */
     activity: number;
-    /** rows for the tail of the reasoning stream */
+    /** rows for the gist of what the model is reasoning about */
     thinking: number;
     /** rows for the answer as it arrives */
     live: number;
     /**
-     * What the three of them occupy together, rules included — a constant for
-     * a given terminal, whatever is happening inside it. The region grows to
-     * this and stops, and never shrinks back while the turn runs, which is what
-     * keeps the footer on one row instead of riding up and down on the
-     * reasoning block.
+     * What the three of them occupy together — a constant for a given terminal,
+     * whatever is happening inside it. The region grows to this and stops, and
+     * never shrinks back while the turn runs, which is what keeps the footer on
+     * one row instead of riding up and down on the work.
      */
     total: number;
 }
@@ -47,11 +54,8 @@ export interface Budget {
  * arrives matters more than the machinery producing it. Reasoning yields to it
  * in turn, because it is a progress indicator and the answer is the point.
  *
- * `thinking` is how many rows of reasoning are wanted, counting text only: none
- * when there is no reasoning, fewer than `THINKING_ROWS` once the stream has
- * settled and its tail is history rather than progress. The two rules are
- * charged on top, so a block too cramped to be worth boxing is not drawn at all
- * rather than drawn as a border with a line in it.
+ * `thinking` is how many rows of reasoning are wanted — one while the model is
+ * reasoning, none otherwise — and it never takes the answer's last row.
  */
 export declare function budgetOf(rows: number, activity: number, thinking: number): Budget;
 /** The rows a branch box may spend on its own calls and its reasoning. */
@@ -87,6 +91,27 @@ export declare function answerWidth(columns: number): number;
  * that got cut.
  */
 export declare function readable(preview: string): string;
+/** Every field of a preview, first mention winning. */
+export declare function fieldsOf(preview: string): Map<string, string>;
+/** What a call is doing, and what it is doing it to. */
+export interface CallView {
+    /** The verb, drawn first: what kind of thing this is. */
+    verb: string;
+    /** What identifies this call: a path, a command, a query. May be empty. */
+    subject: string;
+}
+export declare function describeCall(name: string, preview: string): CallView;
+export declare function summarise(name: string, preview: string): string;
+/**
+ * One line saying where the model has got to.
+ *
+ * Reasoning summaries arrive as markdown and are structured by their own bold
+ * headings — Gemini emits one every few sentences, and they are the shortest
+ * true account of the step. The last one is where the model is now. Failing
+ * that the raw text is clipped, which is a fragment, but a moving fragment is
+ * still proof that something is happening.
+ */
+export declare function gistOf(text: string, width: number): string;
 /** A run of lines from an answer, and whether it was fenced as code. */
 export interface Segment {
     code: boolean;

package/dist/tui/wrap.js

@@ -82,13 +82,21 @@ export function wrap(text, width) {
 // ---------------------------------------------------------------------------
 /** The three footer rows, its margin, the prompt, and a row in hand. */
 export const CHROME_ROWS = 7;
-/** How much of the reasoning stream is worth showing. It is a progress bar. */
-export const THINKING_ROWS = 6;
+/**
+ * How much of the reasoning stream is worth showing.
+ *
+ * One row. A reasoning summary is not a document to be read while it arrives —
+ * it is the model saying what it is about to do, and the sentence that says so
+ * is the heading it writes for itself. Six rows of it pushed the answer and the
+ * work down the screen to make room for a paragraph nobody finishes reading,
+ * and the whole chain is in the trajectory either way.
+ */
+export const THINKING_ROWS = 1;
 /** How much of the frame the work in flight may take. A branch is a box now,
  *  not a row, so a fan-out of two costs fourteen of these. */
 export const ACTIVITY_ROWS = 16;
-/** The rule that opens a reasoning block and the one that closes it. */
-export const THINKING_CHROME = 2;
+/** The width of the elapsed-time column every call row is drawn behind. */
+export const TIME_COL = 5;
 /**
  * How many rows each repainting block may draw in a terminal `rows` tall.
  *
@@ -96,24 +104,15 @@ export const THINKING_CHROME = 2;
  * arrives matters more than the machinery producing it. Reasoning yields to it
  * in turn, because it is a progress indicator and the answer is the point.
  *
- * `thinking` is how many rows of reasoning are wanted, counting text only: none
- * when there is no reasoning, fewer than `THINKING_ROWS` once the stream has
- * settled and its tail is history rather than progress. The two rules are
- * charged on top, so a block too cramped to be worth boxing is not drawn at all
- * rather than drawn as a border with a line in it.
+ * `thinking` is how many rows of reasoning are wanted — one while the model is
+ * reasoning, none otherwise — and it never takes the answer's last row.
  */
 export function budgetOf(rows, activity, thinking) {
     const total = Math.max(2, rows - CHROME_ROWS);
     const shown = Math.min(Math.max(0, activity), ACTIVITY_ROWS, Math.max(0, total - 2));
     const rest = total - shown;
-    const room = rest - 1 - THINKING_CHROME;
-    const tail = room >= 1 ? Math.min(Math.max(0, thinking), THINKING_ROWS, room) : 0;
-    return {
-        activity: shown,
-        thinking: tail,
-        live: rest - tail - (tail ? THINKING_CHROME : 0),
-        total,
-    };
+    const tail = Math.min(Math.max(0, thinking), THINKING_ROWS, Math.max(0, rest - 1));
+    return { activity: shown, thinking: tail, live: rest - tail, total };
 }
 /** The rows a branch box may spend on its own calls and its reasoning. */
 export const BRANCH_ROWS = 5;
@@ -176,6 +175,180 @@ function unquote(raw) {
     const body = raw.length > 1 && raw.endsWith('"') ? raw.slice(1, -1) : raw.slice(1);
     return body.replace(/\\[nrt]/g, ' ').replace(/\\(["\\/])/g, '$1');
 }
+/** Every field of a preview, first mention winning. */
+export function fieldsOf(preview) {
+    const out = new Map();
+    for (const m of preview.matchAll(FIELD)) {
+        const key = m[1];
+        if (!out.has(key)) {
+            out.set(key, unquote(m[2]));
+        }
+    }
+    return out;
+}
+/** The text between `"key":[` and the first `]`, or nothing if there is no such array. */
+function arrayBody(preview, key) {
+    const at = preview.indexOf(`"${key}"`);
+    if (at < 0) {
+        return undefined;
+    }
+    const open = preview.indexOf('[', at);
+    if (open < 0) {
+        return undefined;
+    }
+    const close = preview.indexOf(']', open);
+    return preview.slice(open + 1, close < 0 ? undefined : close);
+}
+/**
+ * An array argument, as the two things worth knowing about it: what is in it,
+ * when its items say their own names, and how many there are either way.
+ */
+function itemsOf(preview, key) {
+    const body = arrayBody(preview, key);
+    if (body === undefined || !body.trim()) {
+        return { names: [], total: 0 };
+    }
+    if (/^\s*\{/.test(body)) {
+        const names = [...body.matchAll(/"name"\s*:\s*"([^"]*)"/g)].map((m) => m[1]);
+        return { names, total: Math.max(names.length, (body.match(/\{/g) ?? []).length) };
+    }
+    const names = [...body.matchAll(/"([^"]*)"/g)].map((m) => m[1]).filter(Boolean);
+    return { names, total: names.length };
+}
+/** A few things are worth naming; more than a few are worth counting. */
+function named(items, unit) {
+    if (!items.total) {
+        return '';
+    }
+    if (items.names.length && items.names.length <= 2) {
+        return items.names.join(', ');
+    }
+    return `${items.total} ${items.total === 1 ? unit : `${unit}s`}`;
+}
+const CALLS = {
+    read_file: { verb: 'read', of: ['path'] },
+    list_dir: { verb: 'list', of: ['path'] },
+    find_files: { verb: 'find', of: ['pattern'] },
+    write_file: { verb: 'write', of: ['path'] },
+    apply_patch: { verb: 'patch' },
+    move_file: { verb: 'move', pair: ['from', 'to'] },
+    delete_file: { verb: 'delete', of: ['path'] },
+    run_command: { verb: 'run', of: ['command'] },
+    run_command_background: { verb: 'start', of: ['command'] },
+    read_command_output: { verb: 'output', of: ['job_id'] },
+    stop_command: { verb: 'stop', of: ['job_id'] },
+    memory_search: { verb: 'recall', of: ['query'] },
+    memory_load: { verb: 'read memory', count: ['ids', 'node'] },
+    memory_commit: { verb: 'remember', count: ['nodes', 'node'] },
+    memory_forget: { verb: 'forget', count: ['ids', 'node'] },
+    skill_search: { verb: 'find skill', of: ['query'] },
+    skill_load: { verb: 'load skill', count: ['names', 'skill'] },
+    fork: { verb: 'fork', count: ['branches', 'branch'] },
+    final_output: { verb: 'answer' },
+    search_api: { verb: 'search api', of: ['query'] },
+    list_api: { verb: 'list api', of: ['name', 'kind'] },
+    grep_api: { verb: 'grep api', of: ['pattern'] },
+    trace_api: { verb: 'trace api', of: ['pattern'] },
+};
+/** The handoff tools are minted per agent, so they are matched by prefix. */
+const TRANSFER = 'transfer_to_';
+/** A patch names its own files, and that is the only part of it worth a row. */
+const PATCHED = /\*\*\* (?:Add|Update|Delete) File:\s*(.*?)(?:\\[nr]|"|$)/g;
+export function describeCall(name, preview) {
+    if (name.startsWith(TRANSFER)) {
+        return { verb: 'hand off to', subject: name.slice(TRANSFER.length) };
+    }
+    const shape = CALLS[name];
+    if (!shape) {
+        return { verb: name, subject: readable(preview) };
+    }
+    if (name === 'apply_patch') {
+        const files = [...preview.matchAll(PATCHED)].map((m) => m[1].trim());
+        return { verb: shape.verb, subject: named({ names: files, total: files.length }, 'file') };
+    }
+    if (shape.pair) {
+        const fields = fieldsOf(preview);
+        const [from, to] = shape.pair;
+        return { verb: shape.verb, subject: `${fields.get(from) ?? ''} → ${fields.get(to) ?? ''}` };
+    }
+    if (shape.count) {
+        const [key, unit] = shape.count;
+        return { verb: shape.verb, subject: named(itemsOf(preview, key), unit) };
+    }
+    const fields = fieldsOf(preview);
+    for (const key of shape.of ?? []) {
+        const value = fields.get(key);
+        if (value) {
+            return { verb: shape.verb, subject: value };
+        }
+    }
+    return { verb: shape.verb, subject: '' };
+}
+/**
+ * What a finished call has to say for itself, in the few words a row has left.
+ *
+ * A `[]` suffix means "count it": the interesting thing about a listing is how
+ * much came back, and printing the first two of forty entries says less than
+ * the number does.
+ */
+const RESULTS = {
+    read_file: ['lines'],
+    list_dir: ['entries[]'],
+    find_files: ['matches[]'],
+    write_file: ['bytes'],
+    apply_patch: ['files[]'],
+    move_file: ['to'],
+    delete_file: ['path'],
+    run_command: ['exit_code'],
+    run_command_background: ['job_id'],
+};
+export function summarise(name, preview) {
+    const fields = fieldsOf(preview);
+    // An error is the whole of what happened, and it is what the next turn
+    // will be about. Nothing else on the row competes with it.
+    const failed = fields.get('error');
+    if (failed) {
+        return failed;
+    }
+    const parts = [];
+    for (const key of RESULTS[name] ?? []) {
+        if (key.endsWith('[]')) {
+            const of = key.slice(0, -2);
+            const { total } = itemsOf(preview, of);
+            if (total) {
+                parts.push(`${total} ${of}`);
+            }
+            continue;
+        }
+        const value = fields.get(key);
+        if (value !== undefined && value !== '') {
+            parts.push(`${key.replace(/_/g, ' ')} ${value}`);
+        }
+    }
+    return parts.length ? parts.join(' · ') : readable(preview);
+}
+// ---------------------------------------------------------------------------
+// The gist of a reasoning stream
+// ---------------------------------------------------------------------------
+/** How much of a stream is looked at for a heading. Its end is where it got to. */
+const GIST_TAIL = 4000;
+/** A reasoning summary writes its own headings, in bold. */
+const BOLD = /\*\*([^*\n]{2,}?)\*\*/g;
+/**
+ * One line saying where the model has got to.
+ *
+ * Reasoning summaries arrive as markdown and are structured by their own bold
+ * headings — Gemini emits one every few sentences, and they are the shortest
+ * true account of the step. The last one is where the model is now. Failing
+ * that the raw text is clipped, which is a fragment, but a moving fragment is
+ * still proof that something is happening.
+ */
+export function gistOf(text, width) {
+    const tail = text.slice(-GIST_TAIL);
+    const heads = [...tail.matchAll(BOLD)];
+    const last = heads.at(-1)?.[1];
+    return clip(last ?? tail, width);
+}
 /**
  * Splits an answer on ``` fences. Prose is left exactly as it was — the common
  * answer has no fence in it and comes back in one piece — but a fenced block is

package/dist/validate.js

@@ -14,7 +14,6 @@ const CONFIG_NAMES = ['agents.yaml', 'agents.yml', 'agents/agents.yaml', 'agents
 const AGENTS_DIR = 'agents';
 const HOUSE_RULES = 'agents/instructions.md';
 const INSTRUCTIONS_SUFFIX = '-instructions.md';
-const LEGACY_HOUSE_RULES = 'INSTRUCTIONS.md';
 const PROMPTS_DIR = 'agents/prompts';
 const SKILLS_DIR = 'agents/skills';
 const SKILL_FILE = 'SKILL.md';
@@ -22,9 +21,9 @@ const ASSETS_DIR = 'assets';
 /** What `allow:` and `preload:` accept, so a skill outside it cannot be named. */
 const REFERABLE = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
 /**
- * Mirrors `readHouseRules` in the loader, in the same order: the legacy file
- * first, then `agents/instructions.md`, then every
- * `agents/<topic>-instructions.md` by filename.
+ * Mirrors `readHouseRules` in the loader, in the same order:
+ * `agents/instructions.md`, then every `agents/<topic>-instructions.md` by
+ * filename.
  */
 function houseRules(root) {
     const found = [];
@@ -33,7 +32,6 @@ function houseRules(root) {
             found.push(rel);
         }
     };
-    take(LEGACY_HOUSE_RULES);
     take(HOUSE_RULES);
     const dir = join(root, AGENTS_DIR);
     if (!existsSync(dir) || !statSync(dir).isDirectory()) {
@@ -193,17 +191,6 @@ export async function validateProject(opts) {
                 'prompt alone, with nothing shared between them',
         });
     }
-    if (rules.includes(LEGACY_HOUSE_RULES)) {
-        add({
-            severity: 'warning',
-            code: 'house-rules.legacy',
-            where: LEGACY_HOUSE_RULES,
-            message: `${LEGACY_HOUSE_RULES} is where the house rules used to live. It is still ` +
-                `read, and still first, but the layout now keeps them under ${AGENTS_DIR}/ ` +
-                'so a project can have more than one of them',
-            fix: `move it to ${HOUSE_RULES}, or fold it into the ${AGENTS_DIR}/*${INSTRUCTIONS_SUFFIX} files already there`,
-        });
-    }
     // -----------------------------------------------------------------------
     // Agents
     // -----------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.18",
+    "version": "1.1.19",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -51,7 +51,7 @@
         "@inkjs/ui": "^2.0.0",
         "ink": "^7.1.1",
         "react": "^19.2.8",
-        "@zenera/neo": "^1.1.18",
+        "@zenera/neo": "^1.1.19",
         "@anthropic-ai/sdk": "^0.120.0",
         "@google/genai": "^2.18.0",
         "@openrouter/sdk": "^1.2.80",

package/templates/editor/.github/copilot-instructions.md

@@ -223,6 +223,7 @@ my-project/
 ├── agents/
 │   ├── instructions.md            house rules, prepended to every agent
 │   ├── memory-instructions.md     more of them - any `<topic>-instructions.md`
+│   ├── tools-instructions.md      and more - how tools are called
 │   ├── prompts/
 │   │   ├── intake.md             one agent's own brief
 │   │   └── adjuster.md
@@ -247,8 +248,7 @@ The config is found by name, in order: `agents.yaml`, `agents.yml`,
 
 The house rules are `agents/instructions.md` plus every
 `agents/<topic>-instructions.md`, read in filename order and prepended to every
-agent (§3.2). A project written before the move keeps its `INSTRUCTIONS.md` in
-the root; that still loads, and `zen check` says to move it.
+agent (§3.2).
 
 ### 2.2 Variants
 

package/templates/editor/.github/skills/zen-cli/references/check.md

@@ -33,8 +33,6 @@ checked too. A word that is neither is a usage error (exit 2), not a report.
   rather than ignored.
 - Every file the configuration names is on disk and non-empty: the house rules
   under `agents/`, each agent's prompt, each skill's `SKILL.md`, each asset glob.
-  A root `INSTRUCTIONS.md` is still read, and reported as something to move to
-  `agents/instructions.md`.
 - Hand-offs and forks name agents that exist, and no agent hands off to itself.
 - Tool selectors resolve against the real tool set, including a skill's own
   `tools:` frontmatter.

package/templates/editor/.github/skills/zen-cli/references/projects.md

@@ -22,6 +22,7 @@ zenera.json                     { version, name }
 agents.yaml                     the configuration
 agents/instructions.md          house rules, prepended to every agent
 agents/memory-instructions.md   more of them, about the memory store
+agents/tools-instructions.md    more of them, about how tools are called
 agents/prompts/default.md       the default agent's prompt
 agents/skills/                  empty, for skills
 assets/README.md