Troubleshooting
Documentation that hides its gaps is not documentation. These are the constraints that apply to Zephr today.
Known constraints
| Constraint | Status | Detail |
|---|---|---|
| npm distribution | not shipped | No published package, no npx one-liner, no global install — build from a clone. |
| Platform support | Linux x64 | Linux x64 is the only CI-proven platform. Windows and macOS are not claimed supported yet. |
| Managed cloud | planned | Hosted sync across machines is planned; today the working path is the local, single-file store. |
| Cursor integration | library | @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.