@zenera/cli 1.1.2 → 1.1.4

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

@@ -0,0 +1,104 @@
+# Running — `zen run`
+
+```
+zen run [project] [prompt] [options]
+```
+
+On a terminal with no prompt it opens the TUI. With a prompt, or with no tty, it
+answers once on stdout and exits.
+
+## Options
+
+| Flag                    | What it does                                           |
+| ----------------------- | ------------------------------------------------------ |
+| `--project <name\|dir>` | Which project. Inferred from the directory otherwise   |
+| `--session <id>`        | Continue a particular session                          |
+| `--new`                 | Start a fresh one                                      |
+| `--workspace <dir>`     | What the agent may read and write                      |
+| `--model <ref>`         | Override the default model for this run                |
+| `--image <ref>`         | Override the container image commands run in           |
+| `--read-only`           | Withhold every tool that can write                     |
+| `--quiet`               | The answer only; no narration                          |
+| `--plain`               | One shot, even on a terminal                           |
+| `--theme <dark\|light>` | Force the palette. Detected otherwise; `$ZENERA_THEME` |
+| `--out <file>`          | Write the answer to a file as well as to stdout        |
+| `--yes`                 | Accept the questions it would otherwise ask            |
+
+Flags always beat the file: the repository states intent, the invocation
+overrides it.
+
+## Which word is the project
+
+The first positional is read as a project when it names one, and as the first
+word of the prompt when it does not:
+
+```
+zen run acme                     the acme project, TUI
+zen run acme "what changed?"     the acme project, one answer
+zen run "what changed?"          this directory's project, one answer
+zen run --project why "why?"     when the project is called "why"
+```
+
+The prompt comes from the argument, or from stdin, or from the TUI:
+
+```
+git diff | zen run --quiet "summarise this diff"
+```
+
+## What a prompt on the command line implies
+
+A prompt is a request for an answer, not a conversation to pick up, so it
+answers the three questions itself: **a fresh session**, **the directory you are
+in** as the workspace, and **no confirmation**. Every flag still wins —
+`--session`, `--workspace` and `--read-only` override it — and the TUI, where
+there is someone to ask, still asks.
+
+There is no `resume`. A session continues itself, because its state is what it
+is; `--session <id>` picks which one.
+
+## The TUI
+
+Drawn only when there is a terminal on both stdin and stdout, no prompt,
+no `--plain`, no `--quiet` and no `--json`. It streams the answer, shows
+reasoning as it arrives, and reports per-turn and per-session token usage in the
+footer.
+
+Reasoning only _arrives_ if the model was asked for it: OpenAI needs
+`reasoningSummary` on the responses API, Anthropic needs `thinkingBudgetTokens`,
+Gemini has `includeThoughts` on by default. An OpenAI project shows nothing
+until `agents.yaml` asks.
+
+Palette selection: `--theme` > `$ZENERA_THEME` > a query to the terminal >
+`COLORFGBG` > dark.
+
+## Sessions
+
+One session is one continuing conversation, with its own workspace, memory and
+run history. Ids look like `20260825-143012-a7f3`.
+
+```
+<project>/sessions/<id>/
+    workspace/          what the agent sees, unless --workspace said otherwise
+    runs/<run-id>/      input.md, output.md, state.json, report.html, meta.json
+    .data/
+        state.json      the live, resumable state, rewritten after every run
+        session.json    when it was made, and the workspace it is rooted at
+        memory/
+        blobs/
+        sandbox/home/   /home/agent inside the container
+    .lock               held while a run is in flight
+```
+
+The recorded workspace is what makes resuming safe: a session that quietly
+changed what "the workspace" meant between turns would be unexplainable, so it
+is written once and reused.
+
+None of `sessions/` is source and none of it is committed.
+
+A session is locked while it runs, and a lock whose process is gone is stale by
+definition and is taken over.
+
+## Afterwards
+
+Each run writes a `report.html` next to its state; the run prints a
+`file://` link to it. See [inspect.md](inspect.md).

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

@@ -0,0 +1,91 @@
+# The sandbox — `zen sandbox`
+
+```
+zen sandbox [status|up|pull|clean|disk] [options]
+```
+
+Shell commands run in a container over the session workspace, never on the
+host. None of this is required: a run does all of it on its own, the first time
+an agent that can reach a shell is about to start one. These subcommands are for
+doing it deliberately — before a demo, in CI, or when diagnosing.
+
+| Subcommand | What it does                                                   |
+| ---------- | -------------------------------------------------------------- |
+| `status`   | What is installed, running and pulled. Changes nothing         |
+| `up`       | Install if asked, start the machine, pull or build the image   |
+| `pull`     | Just the image: pulled, or built from the project's Dockerfile |
+| `clean`    | Remove every container this CLI created                        |
+| `disk`     | What the engine and every known project occupy                 |
+
+| Flag                    | Meaning                                 |
+| ----------------------- | --------------------------------------- |
+| `--project <name\|dir>` | Which project the image comes from      |
+| `--image <ref>`         | Use this image instead of the project's |
+
+The engine is Podman. On macOS a machine has to exist and be running; `up`
+offers to install and start one, and its size follows the project's `cpus` and
+`memory`.
+
+## Configuring it — `sandbox:` in `agents.yaml`
+
+Top level, and again per agent, where an agent's block is merged over the base.
+
+| Key       | Meaning                                                          |
+| --------- | ---------------------------------------------------------------- |
+| `image`   | The image to run. Mutually exclusive with `build`                |
+| `build`   | `{ dockerfile, context? }` — build one instead. Excludes `image` |
+| `cpus`    | CPU limit                                                        |
+| `memory`  | Memory limit, in MiB                                             |
+| `network` | Whether the container has one                                    |
+| `workdir` | Where the workspace is mounted. `/workspace` by default          |
+| `timeout` | Seconds one command may take                                     |
+| `user`    | Who commands run as                                              |
+| `persist` | Keep the container between runs                                  |
+| `env`     | A name-only allow-list of variables to pass in                   |
+
+`env` refuses names matching `KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `PASSWD` or
+`CREDENTIAL`: the keyring has already materialised real credentials into the
+process environment, and a sandbox is the last place they should be forwarded to.
+
+## `persist: true` is usually what you want
+
+Only `/workspace` and `/home/agent` survive an ephemeral container. A
+`pip install` as root, or an `apt-get install`, lands in the image's system
+paths and is gone by the next run — so the agent silently reinstalls its
+toolchain every single time. `zen init` scaffolds `persist: true` for that
+reason.
+
+The caveat: the container's name is a function of its configuration, so any
+change to the sandbox block names a _new_ container and abandons the installed
+rootfs. If runs keep beginning with an install, either persist, or bake the
+toolchain into the image.
+
+## Building an image instead of naming one
+
+```yaml
+sandbox:
+    build:
+        dockerfile: sandbox/Dockerfile
+    persist: true
+```
+
+The tag is content-addressed — a hash of the Dockerfile and every file in its
+context — so a changed Dockerfile is a different image and a `persist: true`
+container can never be left sitting on a stale rootfs. It is built only when
+that tag is absent, which is safe precisely because the tag follows the content.
+`zen sandbox pull` forces a rebuild.
+
+## Hardening
+
+`no-new-privileges`, an init process, a pid limit, no restart policy. Not
+`--cap-drop=ALL` (it breaks `apt` and `pip`) and never `--privileged`.
+
+## When it goes wrong
+
+Exit code `5` means the container engine is missing or the image could not be
+prepared, and the message names the command to run for this platform. `zen check`
+distinguishes the two cases: a broken Dockerfile is an error, a laptop with no
+Podman is a warning.
+
+`zen sandbox clean` removes every container this CLI created — the way out of a
+container left on a bad rootfs.

package/templates/editor/.vscode/settings.json

@@ -0,0 +1,6 @@
+{
+    "chat.useNestedAgentsMdFiles": false,
+    "chat.tools.terminal.autoApprove": {
+        "zen": true
+    }
+}

package/templates/parts/exa.yaml.tmpl

@@ -0,0 +1,5 @@
+# exa:* is web search and page reading, here because this
+# machine has an Exa key. The key is read from the environment
+# when a tool is called, so a clone of this project without one
+# still loads and only the call fails.
+- exa:*

package/templates/parts/model.yaml.tmpl

@@ -0,0 +1,4 @@
+# The model an agent uses when it does not pin its own. Change it here and the
+# whole project moves. The prefix is the *provider* name, not the vendor — drop
+# it and the id goes to the default provider, whatever the id looks like.
+model: {{ref}}

package/templates/parts/models.yaml.tmpl

@@ -0,0 +1,10 @@
+# The model an agent uses when it does not pin its own. Change it here and the
+# whole project moves. A named configuration is what gives the knobs below
+# somewhere to live; a bare `model: <provider>:<id>` works when there are none.
+models:
+    main:
+        provider: {{provider}}
+        model: {{id}}
+        {{options}}
+
+model: main

package/templates/project/INSTRUCTIONS.md

@@ -0,0 +1,7 @@
+# House rules
+
+Everything in this file is prepended to every agent's prompt, so it is the
+place for the things that are true regardless of who is answering: tone,
+constraints, what to do when the answer is not knowable.
+
+Replace this with yours.

package/templates/project/SPECIFICATION.md

@@ -0,0 +1,6 @@
+# Specification
+
+What the project is meant to produce, the constraints it has to hold to, and
+how to tell a finished job from an unfinished one.
+
+Anything written here is the specification; while it is empty there is none.

package/templates/project/agents/prompts/default.md

@@ -0,0 +1,15 @@
+You are a helpful assistant working inside a project workspace.
+
+You have tools to read, search and edit files. The workspace is the only
+place you can see; paths are relative to its root.
+
+You can also run shell commands. They run in a container over the same
+workspace, not on the user's machine, so a command that fails there has cost
+them nothing — but it is still their work in the directory, so read before you
+overwrite and say what you ran.
+
+Read a file before you change it: `apply_patch` matches the surrounding text
+exactly, so a patch written from memory will not apply. Use `apply_patch` to
+change part of a file and `write_file` only for a new one.
+
+Say what you changed.

package/templates/project/agents.yaml.tmpl

@@ -0,0 +1,44 @@
+# Who exists, and what they may reach for.
+#
+version: 1
+
+{{model}}
+
+# Anything in assets/ is mounted read-only at /assets for every agent: they can
+# read, list and search it, and no tool can change it. It is a convention, so
+# the folder is enough — set `assets: <path>` only to keep the material
+# somewhere else in this project.
+
+# The container `sandbox:*` commands run in. `build:` names a Dockerfile to
+# build instead of an image to pull, so anything this project always needs is
+# in the image rather than installed by an agent on every run — put it in
+# sandbox/Dockerfile. Swap the whole block for `image: <ref>` to pull a
+# published one instead; the two cannot both be set.
+#
+# `persist: true` keeps the container between runs rather than throwing it
+# away, so what an agent installs for itself is still there next time —
+# otherwise only /workspace and its home directory survive. `zen sandbox
+# clean` removes the ones left behind. Everything else has a default; see the
+# sandbox: block in docs/agents-yaml.md to size it.
+sandbox:
+    persist: true
+    build:
+        dockerfile: sandbox/Dockerfile
+
+agents:
+    - name: default
+      description: The entry point.
+      # Instructions live in agents/prompts/<name>.md and are picked up by
+      # convention — no need to name the file here.
+      #
+      # workspace:* is every file tool at once, sandbox:* is the shell. Name
+      # them one by one to be narrower, or subtract: [workspace:*, -delete_file]
+      #
+      # sandbox:* runs commands in a container, not on this machine, so it
+      # needs podman — `zen run` installs and starts what it can on its own,
+      # and `zen sandbox status` says where that got to. Drop the line if you
+      # would rather this agent never reached a shell.
+      tools:
+          - workspace:*
+          - sandbox:*
+          {{exa}}

package/templates/project/assets/README.md

@@ -0,0 +1,12 @@
+# assets
+
+Everything in this folder is mounted at /assets when an agent runs. Every agent
+in this project can read, list and search it, and no tool of theirs can change
+it — so this is where reference material goes: handbooks, specifications,
+schemas, worked examples, the style guide the output is supposed to follow.
+
+It is the project's own files that agents get without being asked. The
+workspace they are pointed at is the work; this is what they consult while
+doing it.
+
+Delete this file once there is something here to read.

package/templates/project/gitignore

@@ -0,0 +1,9 @@
+# Sessions hold run state, memory, blobs and whatever the agent wrote.
+# None of it is source.
+sessions/
+
+# Scratch, inside the workspace so the sandbox can reach it.
+.tmp/
+
+# Credentials.
+.env

package/templates/{sandbox → project/sandbox}/Dockerfile

@@ -17,3 +17,5 @@ COPY --from=node /usr/local/lib/node_modules /usr/local/lib/node_modules
 # Symlink npm and npx executables
 RUN ln -s /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm \
     && ln -s /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+
+RUN npm install -g @zenera/cli @zenera/rag

package/templates/.github/skills/zen-cli/SKILL.md

@@ -1,110 +0,0 @@
----
-name: zen-cli
-description: How to drive this project from the terminal with `zen` — running it, validating it, credentials, the sandbox and run reports.
----
-
-# The `zen` command line
-
-Everything here operates on a project directory. The project is resolved from
-the working directory, or by name from the registry `zen init` wrote to, or
-explicitly with `--project <name|dir>`. Every command takes `--json` and prints
-a machine-readable answer instead of a rendered one.
-
-## Running
-
-```
-zen run [project] [prompt] [options]
-```
-
-On a terminal with no prompt it opens the TUI; with a prompt, or without a tty,
-it answers once on stdout. The first word is the project when it names one, and
-the first word of the prompt when it does not — `--project` settles it.
-
-| Flag                    | What it does                                 |
-| ----------------------- | -------------------------------------------- |
-| `--project <name\|dir>` | Which project. Inferred from the directory   |
-| `--session <id>`        | Continue a particular session                |
-| `--new`                 | Start a fresh one                            |
-| `--workspace <dir>`     | What the agent may read and write            |
-| `--model <ref>`         | Override the default model for this run      |
-| `--image <ref>`         | Override the container commands run in       |
-| `--read-only`           | Withhold every tool that can write           |
-| `--quiet`               | The answer only; no narration                |
-| `--plain`               | One shot, even on a terminal                 |
-| `--out <file>`          | Write the answer to a file as well as stdout |
-| `--yes`                 | Accept the questions it would otherwise ask  |
-
-Flags always win over the file: the repository states intent, the invocation
-overrides it. There is no `resume` — a session continues itself, because its
-state is what it is.
-
-With a prompt on the command line nothing is asked: a fresh session, the current
-directory as the workspace, writable.
-
-## Validating
-
-```
-zen check [dir] [--strict] [--quiet]     everything agents.yaml names
-zen models [--project <name|dir>]         providers, models and embeddings resolved
-```
-
-`zen check` reads the project the way `zen run` does and reports in full without
-calling a model — a missing prompt file, an unknown tool, a handoff to nobody, a
-model alias on an undeclared provider. `zen models` answers the narrower
-question of what each agent would actually talk to, and which credential it
-needs. Run `zen check` after any edit to `agents.yaml`, a prompt or a skill; it
-is the cheapest possible test.
-
-## Credentials
-
-```
-zen key ls [--check]              what is on the keyring, and whether it works
-zen key add <provider>[/name]     add one — never on the command line
-zen key use <provider>/<name>     choose the active key for a provider
-zen key check [provider[/name]]   a round trip per key
-zen key show <provider>[/name]    masked, or --reveal for the secret itself
-zen key rm <provider>/<name>      forget it
-zen key env [provider …]          `eval "$(zen key env)"` for other tools
-```
-
-The secret never comes from argv — a command line lands in `ps`, in shell
-history and in CI logs. `zen key add` takes it from piped stdin or an echo-off
-prompt, and nowhere else. Real environment variables win over the keyring, so
-`.env` still decides inside a run.
-
-## The sandbox
-
-```
-zen sandbox status    is a container runtime there, is the image pulled
-zen sandbox up        start it
-zen sandbox pull      fetch the image ahead of the first run
-zen sandbox clean     throw away persisted containers
-```
-
-Shell commands run in a container over the session workspace, not on the host.
-If runs begin by installing a toolchain, set `sandbox.image` to one that already
-has it, or `sandbox.persist: true`, rather than paying for it every run.
-
-## Reports and sessions
-
-```
-zen list [--sessions] [--prune]                       every known project
-zen inspect [run] [--session <id>] [--open] [--serve]  a run's report.html
-zen open [project] [--editor <cmd>] [--wait]           open it in an editor
-zen version                                            CLI, library and Node
-```
-
-`zen inspect` renders the trajectory of a run — every message, tool call, skill
-activation and handoff, in order, with what each one cost. It is the first place
-to look when behaviour is wrong and the prompt looks right: it shows what the
-model was actually given, which is rarely what you assumed.
-
-Sessions live under `sessions/` and hold run state, memory, blobs and whatever
-the agent wrote. None of it is source and none of it is committed.
-
-## Exit codes
-
-Non-zero on failure, with the offending key or file named in the message. A load
-error names the exact path — `agents.yaml: agents[1].skills.discovery — …` — so
-read it rather than guessing; the loader is strict on purpose and an unknown key
-is an error, not a value quietly ignored.