Operations

Repository checks

When working on Zimster itself, the repository's normal validation entry point is:

npm run check

The suite covers tests, repository validation, package structure, generated mirrors, documentation hygiene, and other deterministic contracts. Version-specific release work also uses npm run version:check, package generation, and checksum generation.

Diagnostics

For an installed copy or a checkout, the machine-readable diagnostic report is:

npm run doctor -- --json

The report distinguishes installed-package checks, structural validation, live host behavior, authentication blockers, unavailable hosts, and unsupported capabilities. Use the host-specific guide when the problem is limited to one coding agent.

Package checks

Source-tree tests are not enough for a plugin release. Zimster also checks the archives users actually install.

npm run packagenpm run checksumsnpm run sync:codex:checknpm run validate:codex

Exact-package smoke tests verify archive layout, skill discovery, helper resolution, and installation behavior where the host is available.

Git-local run records

Zimster keeps run state under the Git administrative path instead of committing workflow bookkeeping to the project. It stores the current slice, decisions, routing and review records, checkpoints, and execution limits there.

For a target repository, project-commands.mjs can inventory package scripts, language tooling, Make/Just/Task entries, repository instructions, and simple CI commands so the agent starts from the project's own tooling.

Migrating 0.7.0 run state

If a repository already has Zimster 0.7.0 Git-local state, 0.7.2 can migrate it.

npm run state:migrate

The migration carries forward the records it can read without inventing missing history. Running it again against unchanged input should produce the same result. It does not rewrite project source.

Change snapshots and review integrity

change-snapshot.mjs captures the committed range plus staged, unstaged, and untracked work without changing the index. Text files can be included directly; large or binary files are represented by size and SHA-256.

review-integrity.mjs records the checkout before a shell-capable review and checks it again afterward. If the tree changed, the review stops. The integrity check only answers whether the reviewer changed the checkout; it is not a review verdict.

Keeping Zimster current

Update or reinstall the package using the host's normal package or marketplace command, then start a fresh session. Confirm the loaded version and skill inventory after the update, especially for hosts that cache plugins.

For a Codex repository marketplace install:

codex plugin marketplace upgrade zimstercodex plugin add zimster@zimster --jsoncodex plugin list

Use the installation page for the other host-specific commands.

Privacy

Zimster keeps run records, verification receipts, snapshots, and routing records on the local machine. It has no built-in upload or telemetry mechanism for those files.

Receipt recording can be disabled with --no-receipt or ZIMSTER_RECEIPTS=off when a workflow does not need durable local records.