skills-and-scripts.md

← Zanmai Documentation

Skills and scripts

The pages below use Zanmai's own vocabulary. If a word is new, how the vault is organised defines them: theme and bundle, the note that carries a theme, the fields at the top of a note, links between notes, and slugs.

What

Zanmai's operational layer is split into two kinds of artefact.

• Skills under zanmai/system/skills/<name>/SKILL.md: markdown files with frontmatter (name, description), workflow steps, "Sounds sensible, is wrong", "Red flags". Loaded into context when triggered.
• Scripts under zanmai/system/scripts/: Python files that perform deterministic state changes (folder creation, file copy, validation).

Skills are the operational interface. Scripts are the mechanic the skills call.

Why this split

Recurring discipline lives in skills because the skill file is in context at invocation. Critical mechanics live in scripts because scripts do not require AI discipline at all.

Putting discipline in general instruction files leads to it being forgotten across sessions. The fix is structural. Anything that needs to happen reliably becomes a skill or a script, not prose in a central document.

How to use

When the user describes a recurring operation:

1. If a skill exists, invoke it. The skill carries its workflow plus the discipline.
2. If no skill exists and the operation is recurring, propose adding a skill rather than improvising prose.
3. If the operation must be deterministic (no AI judgement allowed), the right home is a script, not a skill. Snapshot is a script for this reason.

When writing a skill, the shape is:

• Frontmatter with name and a description that captures trigger phrasing.
• An iron-rule section with the non-negotiables.
• "When to use" and "When not to use".
• "The workflow", numbered steps.
• "Sounds sensible, is wrong", a table of plausible-sounding shortcuts and why they are wrong.
• "Stop and look again", signs that the skill is being misapplied.
• "Files", which other artefacts the skill touches.

When not to use

• One-off operations (renaming a single file, answering a single question) do not become skills. They live in conversation.
• Implementation details (how to parse YAML frontmatter) live in scripts, not skills.
• User preferences are not skills, they live in zanmai/user.md.

The current set

The distribution ships the skills, scripts, hooks and subagents listed below. What is actually installed in a vault is what its folders hold, which is also what zanmai.py setup validate reads.

Skills under zanmai/system/skills/<name>/SKILL.md:

• setup: first-time install, invoked by Steve when zanmai/user.md is missing. No slash command (too risky to trigger by accident, invoked by reading the SKILL.md and following the workflow). A freshly copied vault ships no .claude/: it holds only zanmai/, CLAUDE.md and README.md. init creates user.md, the folder skeleton and .claude/settings.json at the end of the guided dialogue, with the hook script path rooted at $CLAUDE_PROJECT_DIR so it survives the vault being moved. The safety hooks become live when the user reopens the vault after setup, so the one setup dialogue before init runs with no hook active and relies on the canonical, em-dash-free text for its voice.
• snapshot: slash command /zanmai-snapshot.
• close-session: slash command /zanmai-close-session.
• greeting: internal, read by Steve before the first user-facing sentence of a session. Carries the mandatory reads, the three shapes a greet can take and what one must never contain. No slash command: it runs at the start of every session, and a command for it would be a way to run it twice.
• import-bundle: slash command /zanmai-import (short user-facing name, the folder keeps the longer descriptive name internally).
• classify-note: internal helper invoked by import-bundle. No slash command (too abstract for direct user trigger).
• research: slash command /zanmai-research. Explicit Reed-trigger that removes the natural-language guesswork. Steve runs the pre-dispatch brief mandatorily per CLAUDE.md Hard Rule 9, then dispatches Reed via the Agent tool.
• journal: slash command /zanmai-journal <text>. Captures the text after the command verbatim into today's journal entry (or this week's, this month's or this year's when named). Steve runs the skill inline, capture is lightweight, no subagent, no confirmation gate. Also writes the automatic period rollups, each from the layer one step below.
• media: internal, run by Loki. His method for image and video generation, backend routing, the swappable model registry, prompt craft, the quality axes, cost control and lawful marking. The judgment layer; the runnable generate and labeling clients are provisioned when a backend is wired. No slash command.
• image-edit: internal, run by Loki. The local pixel workbench through image-edit.py, convert (incl. WebP), resize, rotate, crop, grayscale, composite, optimize and batch a folder on Pillow alone, plus colour grading (a .cube LUT or a reference match), a reference image's dominant colours with WCAG contrast against a given colour (palette, so a brand read off a raster mockup is a measurement rather than an eyeballed estimate), and RAW develop where the host has the libraries. Deterministic, no model, no cost; preferred over regenerating when the pixels already exist. No slash command.
• video: internal, run by Luis. The pipeline from footage to a finished cut: transcription with word timing, the rough cut decided by reading, hiding the seams a cut leaves, editing through the text, reframing, captions in two classes, sound, and one file per purpose. Opens with the question what the video is for, because most jobs are a plain cut and restraint is the default. No slash command.
• video-review: internal, run by Luis in sub-agents. Reading a video by pulling its frames: the two-pass review of a render (technical as a checklist, composition as its own step), picking usable moments out of existing footage, and reading an editing style off a reference video. No slash command.
• motion: internal, shared. Motion graphics built as code and rendered headless: whether a beat earns a graphic at all, the timeline contract that makes a seeked render deterministic, the design rules, and the composite traps that only appear on assembly. Read by anyone producing timed visuals, not only video. No slash command.
• voice: slash command /zanmai-voice. Spoken notes dropped in import/. Steve dispatches Reed in the background to transcribe locally (no key, nothing uploaded) and to read the transcript against the vault, which is where a garbled word and the spelling of a name are settled: a recogniser applies its own casing and cannot be talked out of it. Where a name will not come out, the vault's own names go to the recogniser and the recording is read a second time. Then each note goes where it belongs. Corrections go into the run's log rather than the report, a correction that changes the meaning is a question, and the recording is kept in the day it was spoken on. Runs on a schedule with nobody present as well, deciding rather than asking and closing its own session. Needs ffmpeg, whisper-cli and a model file, which is the one-time first-use step.
• update: slash command /zanmai-update. Explicit Pepper-trigger for a distribution update. Steve dispatches Pepper, who checks for a newer version with zanmai.py setup upgrade --check, reads the remote CHANGELOG unapplied with --changelog (fetched from the origin, since the local file still holds the old version before Apply runs), returns a TL;DR preview of the changes, snapshots before apply on user yes, applies with zanmai.py setup upgrade (git fast-forward for a cloned vault, HTTPS file fetch for any other, host config refreshed in the same run), verifies via zanmai.py setup validate, rolls back from the pre-update snapshot on failure.
• manage-connections: slash command /zanmai-connection. Wong's manual for host sources outside the vault. Wong drives it as a conversation: vault-first, and if the host exposes the source it reads it directly, the host configuration is the opt-in, so no activation gate. No credentials, no read-write, no sync (use-not-own). Recording a connection is optional curation for the user's overview. Steve dispatches Wong, which runs the connection subcommand group (scan, activate, deactivate, list) under the hood, the user never types them.
• brief: slash command /zanmai-grill-me <topic> for the standalone case, otherwise internal. How a job is handed to a specialist. The handover is two labelled blocks, what the user said and what Steve concluded from it, and the second may settle form and destination but never adds subject matter, so an expert can always tell which is which and a missing fact shows up as missing instead of being invented. Where the first block does not cover what that expert's contract asks for, the skill replaces the plausible default with question rounds in the chat: the whole set of currently-answerable questions at once, numbered, each with a recommended answer, and anything findable in the vault or on disk looked up rather than asked. It exists because a screenshot attached for context was once written into a brief as content, and the resulting document was then defended to the user as their own instruction. Run without a dispatch target via /zanmai-grill-me, the same round mechanism questions a raw idea instead of a handover, with the frontier read off the idea itself rather than an expert's input list.
• write: slash command /zanmai-write, and pulled by every expert who produces text, Ben, Reed, Carol and Steve. Anything longer than a line that gets written for the user runs through it. First it settles what the document is for, as the situation it gets used in rather than its topic, and that one thing is asked where the ask, the material and the vault do not answer it; everything else is proposed in one line the user can veto rather than asked as a form. Source, readers and format follow, and a comparable document in the vault (or the brand's voice, where the piece carries the brand outward) sets structure and voice rather than a style invented on the spot. It names the shapes that ruin a document, in two groups: what damages the reader, worst of which is an instruction aimed at them, and what marks a text as machine-made, taken from a catalogue of tells human editors collected across thousands of machine-written texts. They are described as shapes rather than words, so they hold in whatever language the piece is written in. Nothing checks the document afterwards, and that is deliberate: a text judged by the same kind of thing that wrote it gets the same blind spots twice, so the quality has to be in the writing. It is registered with the host rather than only read as a file, so it is available as a command and not just as a file on disk.
• content-brief: internal, run by Carol (or Steve inline) before any document production. Turns a solution's raw source material into a neutral, source-grounded content substrate persisted as reusable product knowledge. No slash command.
• designer: internal, Carol's design method, settle the mode (clone / compose), shape the piece from the content (structure and block count follow the content, split before cramming), decompose the templates into a concrete building-block kit (values not adjectives; stored per brand × format), compose from it, and a fresh-eyes check against a hard checklist (a separate pass seeing only render + templates + kit, briefed to find fault; any single hard fail, dead space, orphaned element, run-on heading, claim/structure mismatch, hollowed slot, fails the piece) as the delivery gate the builder cannot self-certify. No slash command.
• affinity: internal, run by Carol. Field notes for building natively in Affinity fast, the pre-flight ladder (start the app, repair a wedged session), Desktop-only staging, verified fill/compose idioms and stumble warnings, export presets. Accelerators, not the boundary of what is allowed. No slash command.
• powerpoint: internal, run by Carol. Native, headless PowerPoint handling through python-pptx and direct OOXML where that does not reach: fill a template copy, or create slides from its layouts. The deck is checked by reading the file, not by photographing it, since only PowerPoint renders a deck the way PowerPoint shows it and driving the running application would be taking over your screen. How it looks is your call, in your own PowerPoint. No slash command.
• typst: internal, run by Carol. Field notes for setting a document, the medium for anything paged from a card to a manual. Real flow across pages, a full-width element deferred instead of leaving half a page white, column balancing, hyphenation dictionaries, folios with totals, colour to the page edge. Verified idioms plus the trap that bites, a brand font that is silently replaced unless the font folder is passed and the output checked. No slash command.
• html: internal, run by Carol. Turning a design into a handoff-ready file through HTML, for a deliverable that is itself a web page, or a single surface where nothing flows past its own edge. Format from context via CSS @page, fonts embedded (verified with pdffonts), a cheap PNG seeing-loop, delivery to doing/; the RGB/native-tool boundaries for true press are named, not improvised. Not the medium for a paged document, a browser has no page floats. No slash command.
• create-launcher: slash command /zanmai-create-launcher, and offered once as an optional step after setup. Builds a double-clickable starter for this vault, so opening it does not mean typing a path. Driven by zanmai.py launcher.
• create-expert: internal, run by Stan. The procedure for adding a new expert without drift, research the role first so the spec is not generic, draft a role-specific contract, place it update-safe under zanmai/extensions/, and wire every registration point (adapter, memory, and for a core expert the roster lists, manifest, routing, docs) in lockstep, then validate. No slash command.

Scripts under zanmai/system/scripts/: zanmai.py (the vault CLI with all subcommands, setup, snapshot, import, bundle, asset, contact, journal, file, task, work, plan, review, update, index, memory, connection, media, video, voice, prose, brand, tools, fact, survey, records, routing, retention, gaps, housekeeping, launcher, hook) image-edit.py (a standalone pixel-editing tool Loki's image-edit skill drives, convert, resize, rotate, crop, grayscale, composite, optimize, batch, grade, raw, palette; kept separate from zanmai.py because it is a workbench, not vault mechanics) and design-check.py (Carol's counting judge: forms per component against the kit's ceiling, colours and sizes outside brand and kit, every font embedded, missing break-inside guards in a multi-column layout, and how much of each page a render actually covers; a native deck is checked by reading the file instead, layout used, placeholders filled, no run overriding its layout) and slide-library.py (a brand's own approved slides as a library: it reads an existing deck and writes down what each slide is, which slots it has and how much text each slot measurably holds, so a new piece takes the slide that already carries this shape of content and only the text changes; it also carries the correction tools, nudge to move one shape by a distance without redrawing it, overlap-check and align-check to find text sitting on other text or two text frames that share a box edge but not where their ink actually starts, both measured against the real ink, the real font file where one can be found, not the saved box; layout-check for what no reading of the text can see, a shape past the page edge, under the margin, or set in type too small to read, with the floors taken from the page: A4 or A5 is measured as something held in the hand, anything else as something read across a room; media-check for a picture the file points at that is empty or is not the format its name claims, the one fault that used to surface only when PowerPoint offered to repair the file; fill-check for the opposite question to overflow-check, a filled card using far less of its height than it has, which is either missing content or deliberate breathing room and has to be said out loud; furniture-check for what only shows with two pages side by side, an element that repeats across pages sitting somewhere else on one of them, which every single-page check passes as clean; schema-check for a shape PowerPoint will not draw at all, its properties out of schema order, which every render shows correctly because LibreOffice is tolerant where PowerPoint is not; render for a picture of every slide, headless and on any platform, because a deck that was only described was never looked at; migrate to put one slide into another deck so it adopts that deck's master, theme, layouts and logo instead of bringing its own, reporting what a theme swap cannot carry across). A neutral wireframe library of 57 patterns ships in zanmai/system/templates/wireframes/: greyscale slides on theme roles only, each saying what content it fits and what may vary, so migrate turns one into a branded slide in minutes rather than an hour of composing.

External-tool register: zanmai/system/tool-register.json is a static, distribution-shipped, user-immune catalogue of every external tool Zanmai invokes, per-OS invocation, tier, which agent needs it, how to detect and provision it. zanmai.py tools (doctor / check / ensure / preflight) reads it. Maintenance rule (§3): introducing a new external tool REQUIRES an entry here in lockstep, like manifest.yaml. Presence is detected live per machine, never stored in this static file; detection results are cached machine-locally in zanmai/runtime/tool-cache.json (writable, update-immune) so a check is a quick look, not a rescan, and a change re-registers there.

Hooks are subcommands of zanmai.py hook, wired into Claude Code via .claude/settings.json: kind-required (PreToolUse Write|Edit), permission-guard (PreToolUse Write|Edit), dispatch-guard (PreToolUse Agent, refuses a specialist dispatch that would block the conversation for the length of the job; a specialist pulling in another specialist passes, since that one needs the answer inside its own turn), index-consistency (PostToolUse Write|Edit), session-start (SessionStart). There is no gate on external (MCP) tool calls, the host configuration is the opt-in (LD6).

Subagents under zanmai/system/experts/<name>/<name>.md, registered via a thin .claude/agents/<name>.md adapter stub (the contract's frontmatter plus a pointer to it, a real file, not a symlink):

• hank: filing expert. Steve dispatches via the Agent tool for any operation that puts material where it belongs in the vault. Hank runs the import-bundle skill, classifies per topic, stubs entities, calls zanmai.py for state changes. Writing a document is not his: that used to be bolted on because a long one would block the conversation, which is a fact about wall time and not about who should write.
• ben: writing expert. Dispatched via the Agent tool for a document whose material has to be read first, a transcript, a bundle nobody has been through, a source to go through. He settles what the document is for as a situation rather than a topic, finds the voice himself (brand first where the piece carries it outward, then a comparable document, then the user's own templates, and only what none of those answer is asked), writes to that purpose, and reads the finished file back against it. He writes text and files nothing. Runs the write skill.
• reed: research expert with WebFetch and WebSearch tools. Steve dispatches via the Agent tool. Output is a markdown file with citations, confidence levels, methodology and limitations.
• wong: gateway to host sources outside the vault. Steve dispatches via the Agent tool when a request touches an outside source, an MCP server or a local CLI the host already exposes. Wong's first reflex is vault-first. When an outside source is needed and the host exposes it, Wong reads it and returns prose; if the host does not expose it, Wong says so plainly and offers to help set it up at the host. A host-exposed source is available for use, the host configuration is the opt-in, so no activation gate. Wong uses the host's already-authenticated interfaces, holds no credentials, and cannot write vault files or the source, reads that become notes go to Hank.
• marcus: curator of records/, what is kept because it has to be. Steve dispatches via the Agent tool to file a document that must stay, to say whether a contract still runs, to assemble a matter out of what is already filed, or to propose what may finally go. He reads a pile by machine before opening anything (records index, records survey), files it in one call rather than document by document, and hangs each piece on the matter it belongs to in both directions. Discarding is never his decision to take quietly: every piece carries a keeping term, and letting one go is a decision with a date on it.
• pepper: house-keeper for distribution updates, snapshot delete and restore, structure checks across the vault, and bulk repairs. Steve dispatches via the Agent tool for any operation that can lose state if mishandled, updates, restores, multi-file edits, structure audits. Pepper holds the discipline for pre-snapshot, TL;DR preview before apply, post-apply verification, automatic rollback on failure. Other agents do not perform these operations.
• shuri: brand strategist. Dispatched via the Agent tool to establish a brand from the user's own material, extend it, judge a finished piece against it, or report what it is still missing. She owns trusted/brands/<brand>/design.md and is the only writer of it; Carol, Loki and Luis read it and never change it, which is what stops four producers from settling four slightly different brands. A value she cannot read out of something stays empty rather than being defaulted, and a value estimated from a render or a PDF is marked as an estimate until a binding source appears. She produces nothing herself.
• carol: marketing document designer. Steve dispatches via the Agent tool when the user wants a marketing artifact (flyer, one-pager, deck) from a solution's material, after gathering her required inputs in conversation (audience, purpose, format, all CI templates, image and logo sources). Carol learns the design language from all templates, composes the piece on a copy of the best structural base, judges every render like a critic (designer skill), runs a final per-slot sweep, and writes the finished bundle to doing/; she checks the measurable points on every render herself, and the taste call goes to the user's fresh eyes on the render rather than a self sign-off. Runs the content-brief, designer, html, affinity and powerpoint skills; her contract grants the Affinity MCP tools.
• loki: image and video generation expert. Steve, or another expert whose piece needs generated visuals, dispatches him via the Agent tool to turn a brief into a still, a short clip, or an upscale. Loki directs the model: a refined prompt, service and model choice with a reason from a swappable registry, reference and identity handling, cost-aware video, a judgment of the render against explicit axes (regenerate vs. fix in place), and lawful marking (machine-readable credential always, a visible label on the deep-fake trigger). He reads the active style profile for on-brand prompts and renders through a configured backend Wong set up, never wiring one himself. The mechanics live in the media skill.
• luis: video editing expert. Dispatched via the Agent tool to turn footage into a finished cut. He transcribes once with word-level timing, decides the rough cut by reading rather than watching, hides the seams a cut leaves, sets the target format before captions and graphics, places footage that already exists before asking Loki for generated material, and watches his own render in two named passes before anyone else sees it. One file per purpose at the end, the master never overwritten. The mechanics live in the video, video-review and motion skills.
• stan: expert builder. Steve dispatches him (via the Agent tool) when the user needs a capability no current expert covers, after settling the one-sentence need and a Reed role-research pass. Stan drafts a role-specific contract from the research (never from model knowledge), places it update-safe under zanmai/extensions/experts/, wires every registration point consistently, validates, and returns the draft for approval. Runs the create-expert skill.

Slash commands and dispatchable experts are wired the same way, by a thin adapter stub setup update writes at install time: .claude/skills/<command>/SKILL.md for a command, .claude/agents/<name>.md for an expert, each holding its source's frontmatter plus one line pointing at the real file under zanmai/system/. Which ones exist is not listed here a second time: the skills are the ones marked above with a slash command, and the experts are the ones above with an adapter, both derived from _SKILL_SYMLINK_MAP and _ROSTER in zanmai.py. zanmai.py setup validate reads what is actually installed.

A stub is a command, and a command is for the user. A specialist's working method gets none: it is named by its full path in the contract of the expert who runs it, and reaching it is that expert's job, not the menu's. Registering all of them once buried the ones a person actually asks for and put every method's description into context at every session start.

The adapter's folder name is the user-visible slash command, and the adapter's name: field is set to match it when the stub is written. That is not cosmetic: the host reads the name, so a stub carrying the source skill's own name in a differently-named folder registers a command nobody can type. The stub points at the source procedure under zanmai/system/, so distribution updates touch only the source file and the stub stays valid. Real files, not symlinks, portable and copy/sync-safe; the canonical procedure stays in the AI-neutral zanmai/system/ tree, so another host only needs its own thin adapter, not a rewrite.

zanmai.py subcommands

zanmai.py is the executor for all bundle state changes. Skills call it, the AI does not write into a bundle directly. Subcommands:

• index inspect: user-visible plain-text scan of an import scope. Lists subfolders, file counts per extension, folder-name token candidates, embed reference counts. Run before index find so the user sees what was looked at and folder-tokens enter the token query.- bundle create: new bundle folder, truth file, INDEX.md, master-INDEX refresh. Refuses contact kinds (use contact create instead). The slug may contain / for sub-bundles. Only called after the user approves the plan. --tags sets the tags at creation time.

• bundle add-file: copy a markdown file into a bundle. Body verbatim, and frontmatter the file already carries stays as it is: only the theme and the name follow from where it lands, and only genuinely missing fields are filled. Non-schema frontmatter fields go to a body section. Honours --overwrite, default behaviour appends -imported to avoid clobber. --tags beats what the file says about itself, which is what a source without frontmatter needs.

• asset add: copy a non-markdown file into the bundle it belongs to, flat beside that bundle's own markdown. There is no shared attachment folder: a folder that sorts by file type cuts apart the matter the bundle exists to hold together. --target-name lets the caller rename to avoid basename collisions and may name a sub-folder, which is created on the way; a name pointing outside the bundle is refused. Renames are recorded in zanmai/memory/.embed-rename-map.json so update embeds can resolve plan-driven renames automatically.

• update master-index: regenerate the vault-root INDEX.md from existing bundles plus the contacts folders.

• update wikilinks: rename [[old-slug]] to [[new-slug]] across markdown bodies. Honours |display variants. Scope defaults to the whole vault; pass --scope <path> to narrow it. System paths (zanmai/system/, zanmai/history/, zanmai/logs/, zanmai/memory/activity-log.md, import/, trash/, archive/) are hard-excluded regardless of scope so historical and immutable content stays verbatim.

• bundle rename: atomic slug rename. Renames the markdown file, updates the frontmatter slug: field, rewrites vault-wide wikilinks (with the update wikilinks scope and hard-exclude rules), refreshes the master INDEX.md, and writes one activity-log line. Replaces the multi-step manual workaround that risked source_detail corruption.- bundle add-truth: write a truth file for an existing sub-bundle, with a "Part of [[parent]]" wikilink derived from the folder path. bundle create deliberately omits a truth file for sub-bundles; this command adds one when the sub-bundle is meant as a thematic node with body and parent-link. Takes --tags like bundle create.- plan clear-section: remove the ## Plan section from a bundle's truth file after filing has executed. Idempotent.

• bundle index-entry: rewrite a member's one-line description in its bundle INDEX.md. The description set at filing time was final until now.

• bundle remove-file: discard a member in one call, to trash/, out of the bundle index, into the activity log. file trash alone left the index entry behind.

• contact create: create a contact/person or contact/organization file under contacts/<sub>/. Single file, no bundle. Schema-strict frontmatter: every optional field the schema defines for the kind is accepted as a flag, including --address and --birthday.

• contact update: fill in an existing contact. Sets or removes frontmatter fields, appends body lines, never rewrites what is there. The path a stub takes from auto-created to useful.

• bundle set-body: write the body of a file in a bundle, frontmatter untouched. Refuses a body that already has content unless --replace is passed, because that is where the user's own writing lives.

• bundle edit-file: correct frontmatter fields of an existing file in place, body untouched. A field outside the schema for that kind is refused rather than written, since the hook would refuse the file afterwards.

• index search: search the vault's own text and report how many files were searched. The reason it exists rather than a plain recursive grep: the shipped .gitignore excludes every user folder so a clone cannot commit private material, both common search tools honour that by default, and the result is an empty list that reads exactly like "does not exist". A count of files searched makes a zero a measurement.

• memory log: append one line to the activity log in the canonical format, so hand-written appends stop drifting out of the shape the log is parsed by.

• brand check, brand list: is there a brand to build against, and what is still undecided in it. check exits non-zero when there is none, which is what lets Steve gate a dispatch before render time or generation credits are spent. An undecided field is one that still carries the template's angle-bracket placeholder, which is why the template ships empty rather than pre-filled: an empty field says "not decided", a plausible default silently decides. Beyond the empty fields it reports what the brand cannot answer as a system: no primary colour, a type scale of two levels where a build needs nine to fifteen, a spacing scale with no gutter or margin, no corner radii at all, a section omitted without a reason on the record, and any component whose text and background resolve to colours below the 4.5:1 contrast ordinary text needs. The token block is read without a YAML library, two nesting levels, which is all the format uses.

• task add, task done, task list: the one route to a task line on one of the user's lists. add writes what they asked for, into today's journal entry unless a file is named, with --due YYYY-MM-DD where there is a real deadline; done ticks one off, matched on a fragment of its wording and refusing anything that hits more than one; list shows what is open across the whole vault, --due-within <days> narrows it to what is falling due. Every write leaves a line in the activity log. It exists because the rule was cut wrong before: writing a task was banned outright, which stopped "put that on my list" as well, while what actually did the damage was the system inventing tasks of its own and putting them on the user's list. hook checkbox-guard keeps every other route shut.

• file trash and file archive: move via zn if installed, mv fallback otherwise.

• reindex, patterns, index find: pattern engine (per-file metadata layer, aggregated themes layer, query interface).

• memory report: operation report at zanmai/logs/<YYYY>/<MM>/<date-op-slug>.md. Captures the activity-log window of the operation plus a skill-provided summary. Gives future Steve sessions a per-operation memory beyond the one-liner activity log. Triggers an automatic briefing rebuild after writing the report.

• briefing: atomic rebuild of zanmai/memory/briefing.md. Four sections (what is due, current state, open items, gaps and hints) synthesised from active focus bundles, the latest operation report, open - [ ] lines in Daily, Weekly and focus files, and broken wikilinks via the vault index. The due section is the one that is not folder-scoped: every dated task in the vault counts, archive/ included, because a deadline does not stop being one because the bundle around it was filed away, and work objects with a date join it there. Atomic full rebuild on every call, no incremental drift. Triggered by /zanmai-close-session Step 6, by memory report automatically, and on demand via this subcommand. The session-start.py hook reads the file and inlines it into Steve's context, so the greet needs no extra tool-reads.

• setup upgrade: fetches the newest published version and replaces the distribution files. A cloned vault is fast-forwarded through git so it stays a clean clone and a manual git pull keeps working; any other vault has the new files fetched over HTTPS. Only the manifest's distribution paths are written, user-immune paths never, and files a new version withdraws are removed. The file swap is the last thing it does itself: everything after it runs in the new script via setup post-upgrade, because a step performed by the version that was just replaced writes the old shape and reports success. --check reports without applying, and a vault ahead of the source is never downgraded.

• setup post-upgrade: the tail of an upgrade, run by the newly installed script on its own installation and not by hand. Refreshes the host config, checks what actually arrived (every shipped hook wired in .claude/settings.json, an adapter present for every expert and skill), and records the installed version only if that check passes. On a failure the recorded version stays where it was, so the session-start repair still fires; the marker means the host config was verified at this version, never that an upgrade to it was attempted.

• tools: reads tool-register.json and works the external-tool layer. doctor detects every registered tool on this machine (per-OS invocation, presence, version, identity, never assumed); check <id> reports one; ensure <id> provisions an on-demand tool at first use, Python libraries install into a managed runtime venv at zanmai/runtime/venv (built with uv if present, else stdlib venv, so the externally-managed system Python is never touched), standalone binaries are reported with their recipe (auto-fetch is a later step), the self-managed C2PA signer is established on demand (media signer ensure, cryptography into the same venv), prerequisites return the user-facing install hint. ensure-all reports what is still missing in three groups (already here, fetchable by Zanmai, yours to install) and, with --yes, fetches the first group; setup offers it once so a prerequisite is not met mid-job. preflight <expert> (optionally --capability <path>) resolves everything that expert needs, cache-backed, and returns ready plus, for each gap, the why (what the tool does for the job) and the install hint, so Steve gates a dispatch before it starts: auto-provision a small library, ask for a heavy one, or stop with a clear message. No expert meets a missing tool mid-run (a subagent cannot ask the user, operating-principles §10).

The skills compose these subcommands. The discipline lives in the skill, the mechanics live in the script.

---

← Back to the documentation index