jshph/enzyme/enzyme-workspace-setup

Enzyme Workspace Setup

Read references/knowledge-practice-review.md completely before interpreting the notes or composing the handoff. It owns the shared judgment about the user's practice; this skill owns Enzyme commands, permissions, changes, and recovery. When delivered through MCP, that reference is appended inline.

The job

Help the user answer something they care about using the notes they already have. You write the settings: compile --packet gives you the evidence Enzyme's selection would use, and the user's AGENTS.md, CLAUDE.md, or router notes say what matters and where it lives. Review the draft with the user, prepare search, demonstrate one answer, and fix a problem only if the evidence warrants it. A working setup with no note changes is a complete success. Tidiness is not a retrieval goal.

Keep the sequence explicit:

1. Check the workspace and provider.
2. Run compile --packet, read the user's own map, write the settings, and review them with the user.
3. With setup and generation authorized, run init, check doctor, and prove an answer.
4. Offer an optional repair only for a demonstrated problem; finish with what the user can do next.

These permissions cover different effects. Reuse explicit authorization already in the conversation; ask only for an effect or choice it has not covered. A plain request to set up Enzyme does not authorize sending excerpts, downloading a model, or editing notes. Never let an approval reviewer choose a provider for the user.

Talk about the user's work

Use actual note names, subjects, and questions. Until retrieval proves an answer, say “we can try asking,” not “this now answers.” Call the program settings. Explain the mechanism once: Enzyme prepares questions from the notes to help find related passages. Describe selected folders/tags by the questions they may help answer, not as “anchors,” “surfaces,” “tiers,” “profiles,” or “dedicated questions.” Do not make the user learn a glossary or another unexplained metaphor. For a date repair, say “I'll add date: 2026-08-26 above your writing. This edits the file's date information; your writing stays unchanged.” Explain the backup as restoring the file and its original date, not as frontmatter, byte identity, or checksums.

Keep routine messages small: roughly 80 words for generation consent, 150 for the settings preview (not counting the settings themselves), and a two-to-four-sentence answer with a short receipt. Repairs may need more detail for exact scope. Link technical evidence instead of narrating its contents. Numbers earn a place only when they affect a choice.

The user should be able to explain what happens next and what they are agreeing to. Enzyme's service has a no-retention policy. Keep the normal setup conversation focused on its purpose and changes; do not add a privacy disclaimer, speculative retention warnings, upload-volume caveats, or an irreversible-transfer warning. If the user asks about privacy, answer directly using that policy. Do not extend Enzyme's policy to a separately chosen provider or the user's assistant.

A clear refusal ends that branch without another menu asking the user to reconsider. An explicit request to undo this run's settings already authorizes that undo; do not ask again. A simulation must label actions as planned, but missing permission to execute real commands is not missing permission inside the fictional dialogue.

Check the starting point

Use the supplied workspace path, or the current workspace if none was supplied. Verify that Markdown notes live there. If it is empty, scratch, or points somewhere else, ask for the notes folder before creating state. For SQLite sources, hand off to enzyme-sqlite-source; this workflow supports one Markdown folder and writes a workspace program with a Markdown source. Existing vault programs remain readable.

ENZYME_BIN="${ENZYME_BIN:-enzyme}"
"$ENZYME_BIN" --version
"$ENZYME_BIN" -p "<vault path>" model status

If the CLI is missing and installation/setup was requested, inspect and use the official CLI installer. Check chained scripts too: CLI installation must not silently install runtime instructions, change settings, or download weights. For diagnosis-only requests, report the missing prerequisite or request a working ENZYME_BIN; do not hunt for unrelated binaries.

CLI installation, runtime instruction installation, and workspace setup are separate operations. If this skill is loaded, runtime installation has already succeeded; do not run enzyme install <runtime> unless the user explicitly asks to install or update those instructions. Existing .enzyme/, AGENTS.md, CLAUDE.md, or installed skills are evidence to inspect, not proof of health.

Record configured mode, effective mode, selected model, and network requirement from model status. Use hosted generation unless the user asks for local: it prepares much better questions than the local model. auto uses an installed local model, so do not assume it means hosted.

• Hosted generation sends selected excerpts to Enzyme's service; the index,

embeddings, and search remain local. If the effective mode is not hosted and the user has not asked for local, run "$ENZYME_BIN" model disable once generation is authorized. It writes configs/settings.enzyme in Enzyme home, or the legacy config.toml there when one exists; include the file it changed in the recovery record.

• Use local generation only when the user asks for it, for example to keep notes

off the network. It needs no network once its model is installed. Use model list to show the current download size if offering installation. Downloading a model requires explicit consent. Do not download or switch to local as a fallback after a hosted failure; report the failure.

• Use --use-env-llm on init and refresh only when the user explicitly requests

their own configured provider and its required environment is present. Inspect variable names only for that request, never secret values. Never print keys or change the user's shell environment/settings to make a command succeed.

For an already initialized workspace, start diagnosis with doctor and current settings. Do not redraft merely to check health. If new selection is needed, explain the proposed replacement and follow the drafting step below.

Draft the settings

compile --packet is local and read-only: no index, login, model call, or saved file. It prints what Enzyme's own selection would be asked, so you can answer it yourself with more context than that selection ever has.

PACKET="$(mktemp -d)/packet.json"
"$ENZYME_BIN" -p "<vault path>" compile --packet > "$PACKET"

The packet is large; query it with jq rather than reading it whole. It holds:

• writing: how answers become a program. Follow it.
• guidance and questions: the selection, profile, and temporal questions

asked of every candidate, and the definitions they refer to.

• candidates: each with samples (excerpts with dates), counts, recent activity, related tags,

and the exact statement that reads it.

• skeleton: a valid program with the source and default leave-outs.
• save_to and save_to_exists: where the settings belong.
• evidence: the vault-wide inventory.

Before answering, read the user's own map: AGENTS.md, CLAUDE.md, and any note they import or link as the place to start. A router note is one the user wrote to describe where things live or what matters; generated guides and Enzyme's own output are not. If none exists, the packet alone decides. It says what is current and what is archive, where each kind of note lives, and which pages are running logs; candidate counts only say what is numerous. Where they disagree, the user's map wins for what matters and the packet wins for what exists. Open notes when two excerpts cannot settle a question. Check evidence.folders for everything that will be indexed and leave out archives, imports, demos, or generated material the map treats as inactive. A candidate you skip is not an exclusion.

A legacy config.toml in Enzyme home is evidence too. Find this vault's [vaults."..."] section by real path; the key may go through a symlink or ~. The packet already carries its exclusions, targets, and limits, but not its entities list or their profiles. Those entities are what the user or an earlier setup once chose to read: keep the ones the map and packet still support, and say which you dropped and why. Leave config.toml in place; the saved program takes priority for this vault, and other settings still live there.

Aim for roughly 8 to 15 readings, up to about 20 when the user's map names more folders or tags that matter. Prefer broad folders and the tags the map names over many narrow tags; a narrow tag earns its own reading only when the map calls it out. A log reading is for a page the user keeps appending to, not a single dated note.

When the map treats material as something to search through the user's lens rather than learn from, such as reading highlights or imports, leave it out and add project questions into "<absolute path>"; catalyze --target <absolute path> then searches it with the vault's questions.

Before writing, keep a bounded recovery record in a unique mktemp directory: the original file at save_to if it exists, any legacy config.toml, and existing .enzyme/ state, with their mtimes. Default Enzyme home is ~/.enzyme; respect an explicit ENZYME_HOME in test environments.

Write the program to save_to as writing describes. If the file exists, replace only this vault's workspace and keep every other declaration. Check it:

"$ENZYME_BIN" spec compile "<save_to>"

Fix any error and check again. Notes, index, models, and auth must remain unchanged; investigate anything else that changed.

Review with the user

Show the complete settings in a fenced enzyme code block, exactly as saved, with the settings link: they are written to be read, and seeing them lets the user correct or reuse them. Then describe two or three readings in terms of the questions they may help answer, any consequential leave-out, where the user's map and the packet disagreed, and one realistic question to test. Invite a specific correction. Do not enumerate every candidate or force a four-tier report.

Keep three facts distinct:

• Readings supply questions Enzyme uses to find related passages.
• An unread candidate has no reading of its own; its notes may still be

searchable or contribute through another reading. It is not an exclusion or a defect merely because it was not read.

• Folder exclusions remove material from discovery/search; tag/link exclusions

affect entity selection, not whole-note discovery. The packet covers Markdown candidates, not every non-Markdown file.

When no user is present to review, treat the checked draft as accepted, and record the choices you would have raised in the final receipt.

Describe pre-init search coverage as planned, not already available. If nothing needs reorganizing, say “You can keep your notes where they are.”

If the user declines, restore the file at save_to from the recovery record or remove it if this run created it; check for later edits first and stop on a conflict. Never delete ~/.enzyme/auth.json or run logout without explicit confirmation.

Confirm the settings and the effective generation path before init. Explain that this builds a local search database from the notes. For hosted generation, say excerpts will be sent to prepare questions for search. For a local download, name its size. Do not ask again if the conversation already authorized it. Apply accepted corrections to the file at save_to and check it again.

Prepare and demonstrate