Zen setup

Create a workspace whose records, repository and capabilities can be identified reliably. Reuse an existing setup before creating anything.

Offer a brief, skippable personalization and guided setup. Ask how the person prefers to communicate and how much help they want; do not infer their background or force an account. Local Markdown, SQLite and a local dashboard are the target for a fully offline setup. Verify the installed dashboard's actual first-run behavior and report missing setup or an account requirement honestly. A public repository is a future distribution channel until it exists; never invent a clone URL or install result.

1. Read repository instructions and discover the host's Zen tools. If zen_state exists, inspect its registry and match the canonical repository, including worktrees. A worktree does not get another history.
2. Establish single-project or global operation. Ask only if context does not settle it. Project-local records live under an ignored .zen directory; global storage uses an owner-selected directory and unique 2–3-letter codes. Use global mode for several repositories sharing a companion; do not promise duplicate unprefixed references in a shared journal.
3. Inspect existing records, schema versions, conflicts and backups before adoption. Preserve IDs, evidence tags and history. Invalid files stay available for repair. See records.md.
4. For an installed companion, use its documented init command or owner Settings. The current MCP cannot create workspaces. Discover again after setup, confirm the returned UUID/code, and create a labelled DOC welcome record only after the writer is ready.
5. Without a companion, read standalone operation and initialize the bundled file writer. It refuses companion-managed SQLite data. If the router/runtime is missing, deliver setup decisions as an unsaved draft rather than fabricating a workspace ID.
6. Keep the private profile external. Load only relevant preferences; never export its identity, accounts or private references. Private cloud eligibility, local-only and never-copy are different choices.
7. Report detected CLIs/models/efforts separately from verified execution. Leave missing model selection to the owner; setup does not run a coding task. Pairing, publishing and Git delivery are separate actions.
8. Explain the value of a local Git history and independent backups in the person's chosen level of detail. Detect Git and any remote connection rather than assuming an account is set up. Offer optional remote hosting; a GitHub account is not required to work locally. Creating a checkpoint, pushing or connecting an account requires the applicable owner decision. Suggest a librarian role only from discovered options and do not assume a paid fallback.

Setup questions (wizard)

When setup needs an answer from the owner, ask one question at a time through zen_ask_question, or the host's native ask tool if that is missing. Follow the grill format: a plain question, two or three concrete options, one marked recommended with its reason, a short context, and free text always allowed. Ask only what the repository and the existing setup cannot answer. A typical setup needs at most three or four questions:

1. How the owner wants to be helped: plain, step by step, or detailed. Recommend plain.
2. One project folder, or several projects sharing one companion. Recommend one project unless several repositories are already present.
3. Where records live: inside the project in a hidden folder, or in a chosen data folder. Recommend the project folder.
4. Whether to add a Git remote now. Recommend skipping it; a local history works without one.

Skip any question the setup has already answered, and say which ones you skipped.

Verify and hand off

Read a test record back through the selected writer, confirm its Markdown and reference, and identify the next usable mode. Report storage, workspace/code, writer, capabilities and unresolved steps. A healthy login alone is not a verified task run. Use the setup checklist.

Example: two worktrees of one repository resolve to the same workspace. A new unrelated repository gets a unique global code, not another conflicting TSK-0001 history.