@zenera/cli 1.1.11 → 1.1.14

package/README.md

@@ -134,17 +134,27 @@ Credentials live in `$HOME`, so the project never contains a secret.
 
 ```
 my-project/
+    SPECIFICATION.md             what this is for — the intent
     INSTRUCTIONS.md              house rules, prepended to every agent
     agents.yaml                  who exists, what they may reach for
     agents/
         prompts/<name>.md        each agent's own brief
         skills/<name>/           knowledge loaded on demand, not always-on
+    assets/                      reference material, read-only at /assets
+    sandbox/Dockerfile           the container commands run in
+    scripts/_setup.sh            the one command that initialises the project
     sessions/                    one workspace, memory and trajectory each
         <id>/
             workspace/           what the agents can read and write
             runs/<id>/           input, output, state, report.html, meta
 ```
 
+`SPECIFICATION.md` comes first because the rest implements it. The one `zen init`
+writes is a true specification of the project it just scaffolded; replace it with
+what you are building, then run `/sync-with-spec` in your editor to make the
+files match. See
+[docs/specification.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/specification.md).
+
 `zen init` also writes `.github/copilot-instructions.md` — a standing brief that
 explains this runtime to whatever coding agent you have open in that folder, so
 you are not expected to hand-author `agents.yaml`.
@@ -160,6 +170,7 @@ you are not expected to hand-author `agents.yaml`.
 | `models`  | What this machine can use — list, search, test, pick.                |
 | `run`     | Runs the project — the TUI on a terminal, a single answer otherwise. |
 | `inspect` | Opens or rebuilds a run's `report.html`.                             |
+| `memory`  | What the agents remember — size, listing, one node, or a whole page. |
 | `check`   | Validates the project and every file it names, and asks the models.  |
 | `sandbox` | Checks and prepares the container that command-line tools run in.    |
 | `cache`   | What work has been kept, and getting rid of it.                      |
@@ -459,11 +470,20 @@ terminal:
 
 ## Documentation
 
+[docs/specification.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/specification.md)
+— writing the specification the project implements ·
 [docs/projects.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/projects.md)
 — the folder a project is ·
 [docs/agents-yaml.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/agents-yaml.md)
 — every key in the configuration file.
 
+[docs/knowledge.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/knowledge.md)
+— a searchable document index ·
+[docs/integrations.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/integrations.md)
+— an API description, searchable and mockable ·
+[docs/memory.md](https://github.com/andreyryabov/ZeneraNeo/blob/main/docs/memory.md)
+— what agents keep between sessions.
+
 ## License
 
 Early days and moving fast — issues, questions and pull requests are welcome.

package/dist/banner.js

@@ -8,64 +8,80 @@ import { dim, note } from "./term.js";
 // terminal — a pipeline asking for the answer gets the answer, and a CI log is
 // not decorated with block letters.
 //
-// The font is here rather than pulled in as a dependency because it is a
-// kilobyte of constant and the whole CLI is otherwise Node's own. Two things
-// about its shape are deliberate: the stroke is **two cells wide**, because a
-// one-cell stem in a dotted fill reads as noise rather than as a letter, and
-// the ink is the dotted block (U+2592) rather than a solid one, which makes a
-// thick stroke a screen-print instead of a slab.
+// The font is here rather than pulled in as a dependency because it is a couple
+// of kilobytes of constant and the whole CLI is otherwise Node's own. It is the
+// shadowed block face: a solid stroke lit from the top left with a box-drawing
+// bevel down its right side and along its foot, so the letters read as raised
+// rather than as a texture. Glyphs are variable width and carry their own
+// spacing, so they abut directly — the gap belongs to the letter, not the join.
 //
 // A terminal too narrow for the art gets the wordmark on one line. A banner
 // that wraps is worse than no banner.
 // ---------------------------------------------------------------------------
-const HEIGHT = 5;
-const WIDTH = 6;
+const HEIGHT = 6;
+/** Between the two words. Wide enough that they read as two, not as one. */
+const GAP = 3;
+/** A left margin, so the art does not start against the edge of the screen. */
+const INDENT = 2;
 const FONT = {
-    A: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
-    B: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ '],
-    C: [' ▒▒▒▒▒', '▒▒    ', '▒▒    ', '▒▒    ', ' ▒▒▒▒▒'],
-    D: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒ '],
-    E: ['▒▒▒▒▒▒', '▒▒    ', '▒▒▒▒▒ ', '▒▒    ', '▒▒▒▒▒▒'],
-    F: ['▒▒▒▒▒▒', '▒▒    ', '▒▒▒▒▒ ', '▒▒    ', '▒▒    '],
-    G: [' ▒▒▒▒▒', '▒▒    ', '▒▒ ▒▒▒', '▒▒  ▒▒', ' ▒▒▒▒▒'],
-    H: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
-    I: ['▒▒▒▒▒▒', '  ▒▒  ', '  ▒▒  ', '  ▒▒  ', '▒▒▒▒▒▒'],
-    J: ['▒▒▒▒▒▒', '   ▒▒ ', '   ▒▒ ', '▒▒ ▒▒ ', ' ▒▒▒  '],
-    K: ['▒▒  ▒▒', '▒▒ ▒▒ ', '▒▒▒▒  ', '▒▒ ▒▒ ', '▒▒  ▒▒'],
-    L: ['▒▒    ', '▒▒    ', '▒▒    ', '▒▒    ', '▒▒▒▒▒▒'],
-    M: ['▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒', '▒▒  ▒▒'],
-    N: ['▒▒  ▒▒', '▒▒▒ ▒▒', '▒▒▒▒▒▒', '▒▒ ▒▒▒', '▒▒  ▒▒'],
-    O: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ '],
-    P: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒    ', '▒▒    '],
-    Q: [' ▒▒▒▒ ', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒ ▒▒ ', ' ▒▒ ▒▒'],
-    R: ['▒▒▒▒▒ ', '▒▒  ▒▒', '▒▒▒▒▒ ', '▒▒ ▒▒ ', '▒▒  ▒▒'],
-    S: [' ▒▒▒▒▒', '▒▒    ', ' ▒▒▒▒ ', '    ▒▒', '▒▒▒▒▒ '],
-    T: ['▒▒▒▒▒▒', '  ▒▒  ', '  ▒▒  ', '  ▒▒  ', '  ▒▒  '],
-    U: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ '],
-    V: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  '],
-    W: ['▒▒  ▒▒', '▒▒  ▒▒', '▒▒▒▒▒▒', '▒▒▒▒▒▒', '▒▒  ▒▒'],
-    X: ['▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  ', ' ▒▒▒▒ ', '▒▒  ▒▒'],
-    Y: ['▒▒  ▒▒', ' ▒▒▒▒ ', '  ▒▒  ', '  ▒▒  ', '  ▒▒  '],
-    Z: ['▒▒▒▒▒▒', '   ▒▒ ', '  ▒▒  ', ' ▒▒   ', '▒▒▒▒▒▒'],
+    A: [' █████╗ ', '██╔══██╗', '███████║', '██╔══██║', '██║  ██║', '╚═╝  ╚═╝'],
+    B: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██████╔╝', '╚═════╝ '],
+    C: [' ██████╗', '██╔════╝', '██║     ', '██║     ', '╚██████╗', ' ╚═════╝'],
+    D: ['██████╗ ', '██╔══██╗', '██║  ██║', '██║  ██║', '██████╔╝', '╚═════╝ '],
+    E: ['███████╗', '██╔════╝', '█████╗  ', '██╔══╝  ', '███████╗', '╚══════╝'],
+    F: ['███████╗', '██╔════╝', '█████╗  ', '██╔══╝  ', '██║     ', '╚═╝     '],
+    G: [' ██████╗ ', '██╔════╝ ', '██║  ███╗', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+    H: ['██╗  ██╗', '██║  ██║', '███████║', '██╔══██║', '██║  ██║', '╚═╝  ╚═╝'],
+    I: ['██╗', '██║', '██║', '██║', '██║', '╚═╝'],
+    J: ['     ██╗', '     ██║', '     ██║', '██   ██║', '╚█████╔╝', ' ╚════╝ '],
+    K: ['██╗  ██╗', '██║ ██╔╝', '█████╔╝ ', '██╔═██╗ ', '██║  ██╗', '╚═╝  ╚═╝'],
+    L: ['██╗     ', '██║     ', '██║     ', '██║     ', '███████╗', '╚══════╝'],
+    M: ['███╗   ███╗', '████╗ ████║', '██╔████╔██║', '██║╚██╔╝██║', '██║ ╚═╝ ██║', '╚═╝     ╚═╝'],
+    N: ['███╗   ██╗', '████╗  ██║', '██╔██╗ ██║', '██║╚██╗██║', '██║ ╚████║', '╚═╝  ╚═══╝'],
+    O: [' ██████╗ ', '██╔═══██╗', '██║   ██║', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+    P: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔═══╝ ', '██║     ', '╚═╝     '],
+    Q: [' ██████╗ ', '██╔═══██╗', '██║   ██║', '██║▄▄ ██║', '╚██████╔╝', ' ╚══▀▀═╝ '],
+    R: ['██████╗ ', '██╔══██╗', '██████╔╝', '██╔══██╗', '██║  ██║', '╚═╝  ╚═╝'],
+    S: ['███████╗', '██╔════╝', '███████╗', '╚════██║', '███████║', '╚══════╝'],
+    T: ['████████╗', '╚══██╔══╝', '   ██║   ', '   ██║   ', '   ██║   ', '   ╚═╝   '],
+    U: ['██╗   ██╗', '██║   ██║', '██║   ██║', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+    V: ['██╗   ██╗', '██║   ██║', '██║   ██║', '╚██╗ ██╔╝', ' ╚████╔╝ ', '  ╚═══╝  '],
+    W: ['██╗    ██╗', '██║    ██║', '██║ █╗ ██║', '██║███╗██║', '╚███╔███╔╝', ' ╚══╝╚══╝ '],
+    X: ['██╗  ██╗', '╚██╗██╔╝', ' ╚███╔╝ ', ' ██╔██╗ ', '██╔╝ ██╗', '╚═╝  ╚═╝'],
+    Y: ['██╗   ██╗', '╚██╗ ██╔╝', ' ╚████╔╝ ', '  ╚██╔╝  ', '   ██║   ', '   ╚═╝   '],
+    Z: ['███████╗', '╚══███╔╝', '  ███╔╝ ', ' ███╔╝  ', '███████╗', '╚══════╝'],
 };
-const BLANK = ' '.repeat(WIDTH);
-/** One word as five rows of equal length — so two words line up when joined. */
+const BLANK = ['    ', '    ', '    ', '    ', '    ', '    '];
+/** One word as six rows of equal length — so two words line up when joined. */
 function big(word) {
     const rows = new Array(HEIGHT).fill('');
     for (const ch of word.toUpperCase()) {
-        const glyph = FONT[ch];
+        const glyph = FONT[ch] ?? BLANK;
         for (let r = 0; r < HEIGHT; r++) {
-            rows[r] += `${glyph?.[r] ?? BLANK} `;
+            rows[r] += glyph[r];
         }
     }
     return rows;
 }
 /** A wordmark rather than a sentence, so the letters are set apart. */
 const spaced = (s) => [...s.toUpperCase()].join(' ');
-/** The name, in the brightest thing the terminal has. */
-const bright = (s) => styleText(['bold', 'whiteBright'], s);
-/** The half that carries the colour. */
-const neon = (s) => styleText(['bold', 'magentaBright'], s);
+/** Whether anything should be coloured at all — `styleText`'s own answer. */
+const styling = () => styleText('dim', '.') !== '.';
+const RESET = '\u001b[0m';
+const HEAD = { face: '\u001b[1;38;5;231m', shade: '\u001b[0;38;5;244m' };
+const ACCENT = { face: '\u001b[1;38;5;208m', shade: '\u001b[0;38;5;130m' };
+/** Runs of stroke and runs of bevel, alternating; spaces stay unstyled. */
+const RUNS = /[█▀▄]+|[^█▀▄ ]+/g;
+const isStroke = (run) => /[█▀▄]/.test(run);
+/**
+ * Two tones per word — without the darker bevel the letter is a flat outline
+ * and the shadow reads as part of the stroke.
+ */
+const paint = (text, tone) => styling()
+    ? text.replace(RUNS, (run) => `${isStroke(run) ? tone.face : tone.shade}${run}${RESET}`)
+    : text;
+/** The wordmark has no bevel to shade, so it is all face. */
+const flat = (text, tone) => styling() ? `${tone.face}${text}${RESET}` : text;
 export const NEO_BANNER = {
     head: 'Zenera',
     accent: 'Neo',
@@ -76,17 +92,23 @@ export function bannerLines(text, columns = process.stderr.columns || 80) {
     // Trimmed: the widest accent row is the banner's right edge, and a pad left
     // inside a styled string cannot be trimmed away later.
     const accent = big(text.accent).map((row) => row.trimEnd());
-    const width = 2 + head[0].length + Math.max(...accent.map((row) => row.length));
-    const foot = `  ${dim(spaced(text.subtitle))}`;
+    const margin = ' '.repeat(INDENT);
+    const width = INDENT + head[0].length + GAP + Math.max(...accent.map((row) => row.length));
     if (width > columns) {
-        return [` ${bright(text.head.toUpperCase())} ${neon(text.accent.toUpperCase())}`, foot];
+        return [
+            `${margin}${flat(text.head.toUpperCase(), HEAD)} ${flat(text.accent.toUpperCase(), ACCENT)}`,
+            `${margin}${dim(spaced(text.subtitle))}`,
+        ];
     }
     const lines = [];
     for (let r = 0; r < HEIGHT; r++) {
-        lines.push(` ${bright(head[r])} ${neon(accent[r])}`);
+        lines.push(`${margin}${paint(head[r], HEAD)}${' '.repeat(GAP)}${paint(accent[r], ACCENT)}`);
     }
+    // Rules on both sides, centred under the art: the subtitle is a caption,
+    // and without them a short line of spaced capitals floats.
+    const caption = `───  ${spaced(text.subtitle)}  ───`;
     lines.push('');
-    lines.push(foot);
+    lines.push(`${' '.repeat(Math.max(INDENT, Math.round((width - caption.length) / 2)))}${dim(caption)}`);
     return lines;
 }
 /** Narration, and only for someone watching. */

package/dist/commands/index.js

@@ -4,6 +4,7 @@ import { init } from "./init.js";
 import { inspect } from "./inspect.js";
 import { key } from "./key.js";
 import { list } from "./list.js";
+import { memory } from "./memory.js";
 import { models } from "./models.js";
 import { open } from "./open.js";
 import { run } from "./run.js";
@@ -23,6 +24,7 @@ export const COMMANDS = {
     models,
     check,
     inspect,
+    memory,
     sandbox,
     cache,
     version,
@@ -36,6 +38,7 @@ export const ALIASES = {
     validate: 'check',
     doctor: 'check',
     report: 'inspect',
+    mem: 'memory',
     edit: 'open',
     code: 'open',
     mock: 'faker',

package/dist/commands/init.js

@@ -96,10 +96,14 @@ export const init = {
     summary: 'Create a project here, or in <dir>, and register it.',
     usage: USAGE,
     details: [
-        'Writes INSTRUCTIONS.md, agents.yaml and agents/, then records the',
-        'directory so `zen list` and `zen open` can find it by name. Editor files',
-        '(.vscode/settings.json and the .github/ tree) are written',
-        'alongside, replacing any already there.',
+        'Writes SPECIFICATION.md, INSTRUCTIONS.md, agents.yaml, agents/ and',
+        'scripts/, then records the directory so `zen list` and `zen open` can',
+        'find it by name. Editor files (.vscode/settings.json and the .github/',
+        'tree) are written alongside, replacing any already there.',
+        '',
+        'SPECIFICATION.md states what the project is for and what it may do,',
+        'and describes the one that was just written. Say what you are building',
+        'there, then run /sync-with-spec in your editor to make the rest match.',
         '',
         'The default agent gets the file tools and a sandboxed shell, plus',
         '`exa:*` when the keyring holds an Exa key. Without --model, the',

package/dist/commands/inspect.js

@@ -1,9 +1,9 @@
+import { assertState, buildRunReport, FilePayloadStore, memoryDir, MemoryStore, PayloadResolver, readProjectConfig, renderReportHtml, } from '@zenera/neo';
 import { spawn } from 'node:child_process';
 import { createReadStream, existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { extname, normalize, resolve, sep } from 'node:path';
-import { assertState, buildRunReport, FilePayloadStore, PayloadResolver, renderReportHtml, } from '@zenera/neo';
+import { extname, join, normalize, resolve, sep } from 'node:path';
 import { parse } from "../args.js";
 import { project as resolveProject } from "../resolve.js";
 import { display, newestRun, newestSession, requireSession, runPaths, sessionPaths, } from "../session.js";
@@ -29,7 +29,7 @@ export const inspect = {
         const session = pickSession(dir, values.session);
         const run = pickRun(session, positionals[0]);
         if (values.rebuild || !existsSync(run.report)) {
-            await rebuild(session, run);
+            await rebuild(session, run, await memory(dir));
         }
         if (ctx.json) {
             json({ session: session.id, run: run.id, report: run.report });
@@ -78,7 +78,7 @@ function pickRun(session, asked) {
  * state — which is what makes `--rebuild` safe and what makes an old run
  * readable by a newer renderer.
  */
-async function rebuild(session, run) {
+async function rebuild(session, run, store) {
     if (!existsSync(run.state)) {
         throw invalidError(`run ${run.id} has no state to rebuild from`);
     }
@@ -90,9 +90,27 @@ async function rebuild(session, run) {
         throw invalidError(`${run.state}: ${err instanceof Error ? err.message : String(err)}`);
     }
     const payloads = new PayloadResolver(new FilePayloadStore({ dir: session.blobs, id: 'file' }));
-    const report = await buildRunReport(state, payloads, { title: run.id });
+    const report = await buildRunReport(state, payloads, { title: run.id, memory: store });
     await writeFile(run.report, renderReportHtml(report), 'utf8');
 }
+/**
+ * The project's memory, unlocked, when it has one. Without it the memory view
+ * has the shape of what the run recalled but not a word of it; a run that
+ * never touched memory pays nothing, because the report asks for no node.
+ */
+async function memory(dir) {
+    const { config } = readProjectConfig(dir);
+    const at = memoryDir(dir, config);
+    if (!at || !existsSync(join(at, 'manifest.json'))) {
+        return undefined;
+    }
+    try {
+        return await MemoryStore.open(at, { lock: false });
+    }
+    catch {
+        return undefined;
+    }
+}
 // ---------------------------------------------------------------------------
 // Serving
 //

package/dist/commands/memory.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from '../command.ts';
+export declare const memory: Command;
+//# sourceMappingURL=memory.d.ts.map