# File-only operation without a dashboard or companion

Node 24+ and the installed `zen` router are sufficient. The bundled script has no external dependencies, network calls, model execution, Git delivery or credential access. Use the absolute path to your installed router, not a presumed global path. An individual mode without the router can still deliver its workflow output as a labelled draft; install/copy the router if actual persistence is required.

## Initialize

Choose project-local or global mode with the owner. Prepare a JSON file:

```json
{"name":"Example","code":"EX","repository":"<absolute-repository-path>","mode":"project"}
```

Run `node <installed-zen>/scripts/records.mjs --root <canonical-repository>/.zen init --input init.json`. Project mode requires that exact .zen root, appends its private ignore rule and maps Git worktrees to the canonical repository. Global mode uses an owner-chosen root and unique codes for each repository. Re-running init for the same canonical repository returns its existing UUID.

Use returned workspace UUIDs for record inputs. Keep request JSON files in a private/ignored location; `--input -` reads JSON from stdin when the host supports it. Never put credential values or never-copy data into an agent-visible request.

## Read and write

Commands are init, state/list, get, search, history, create, update, transition, select, snapshot, verify and recover. Every command accepts `--root <data-directory>` and `--input <JSON-file-or->`. Create input follows record.create payload fields plus a stable idempotencyKey. Update uses id, expectedRevision, patch and key. Transition uses id, expectedRevision, status and key. Select uses ART id, SRT variantId, expectedRevision and key. State/list accepts workspaceId/type; search adds query; get accepts id/ref, offset and limit. History with id lists revision metadata; add revision to read that bounded historical body.

For runnable artifact sources, snapshot takes SRT id, current expectedRevision, an explicit files array, optional sourceRoot and idempotencyKey. Paths are relative to the canonical repository or a mapped worktree root, never an arbitrary private directory. It copies 1–100 explicitly named regular files into an immutable per-operation directory, bounds file/total size, rejects protected/escaping paths and stores SHA-256 hashes. Snapshotting increments the SRT revision; select that returned revision afterward. Verify takes the SRT id/ref, resolves the selected historical revision and reports changed source, changed record or damaged snapshot. Stop on drift; the immutable snapshot is the content selected, not the newly edited working file. Managed workspaces still require host file IO plus MCP record updates, not this standalone command.

Example create request:

```json
{"workspaceId":"<returned-workspace-uuid>","type":"IDE","title":"Searchable build notes","body":"## Outcome\nFind an earlier decision without reading every transcript.","idempotencyKey":"capture-search-idea-01"}
```

Run the script's create command, then get using its returned id/ref. A successful result says writer=standalone and synced=false. Default visibility is local. Private/public values only express future eligibility; they do not synchronize or publish. FDK/MEM remain proposed. Tasks can be Backlog or Review; the script never launches a run or marks Done.

## Authority, conflict and recovery

The script refuses any root containing zen.sqlite, even if the companion is stopped. Use companion/MCP for adopted data; do not delete the journal to bypass this check. A shared PID/nonce writer lock prevents concurrent companion/standalone writes. Unknown/live locks are preserved; a known exited process's lock can be reclaimed.

Identifiers are reserved durably before writing, so crash gaps are possible and IDs are never reused. Each keyed mutation journals the intended record, writes Markdown atomically, preserves immutable history, updates its rebuildable index and acknowledges. Retry the same request/key after uncertainty. Changed input under the same key is rejected. Recover completes prepared writes only when current content matches the expected old or intended new content; otherwise it preserves the journal and original file as a conflict. Manual edits that do not match the known hash are never silently overwritten. Repair/merge explicitly; do not repeatedly submit the stale patch.

Frontmatter is JSON-form YAML, compatible with the companion schema and deliberately dependency-free. This writer does not parse arbitrary hand-written YAML; retain such files for companion repair. It excludes never-copy records from agent reads/history and does not automatically apply learning.

## Adoption

Back up the file-only root, run recover until prepared writes are applied or explicitly resolved, stop its writer, and initialize/start the installed companion against that same registry/data root. Companion adoption refuses a pending standalone journal before creating SQLite and imports reserved counters, including gaps. Rebuild records/history and compare UUIDs, refs, links, variant selection and counters. Do not initialize a replacement workspace or renumber records. Once zen.sqlite exists the file-only writer refuses access. Artifact snapshots under workspace .zen/artifacts or the configured global workspace artifact directory are included in companion backups; preserve their original paths on restore. Cloud selection/pairing and model runs remain separate owner choices. Standalone operation is local persistence, not proof of the website, relay, schedules or provider execution.