Zephr Docs

Troubleshooting

Documentation that hides its gaps is not documentation. These are the constraints that apply to Zephr today.

Known constraints

ConstraintStatusDetail
npm distributionnot shippedNo published package, no npx one-liner, no global install — build from a clone.
Platform supportLinux x64Linux x64 is the only CI-proven platform. Windows and macOS are not claimed supported yet.
Managed cloudplannedHosted sync across machines is planned; today the working path is the local, single-file store.
Cursor integrationlibrary@zephr-ai/adapter-cursor is a first-party mapper library, not bundled into the editor; the operator wires it in.

Common failure modes

Node version mismatch

The workspace pins Node 24 (engines.node: >=24 <25). A mismatched runtime fails at build rather than at first tool call. Confirm node --version before installing.

Scope violation on tool call

scope_violation means a worktreeId was passed outside the admitted scope. Re-run the launcher flow (project approve → path bind → launch) and confirm the binding points at the worktree you are working in.

Data discarded after exit

If ZEPHR_DB_PATH is unset, the server runs on an in-memory store and discards everything on exit. Set an absolute ZEPHR_DB_PATH for any work you want to keep.

Each constraint is a present-tense fact, not a roadmap apology. When one changes, it lands in the changelog with a real date and SHA.