The golden path
Install, connect, admit a scope, recall, hand off. Each stage below shows the artifact it actually produces — an evidence card you can select and copy, not a picture of one — and says plainly what is shipped and what is still moving.
One command is the designed entry point. It is not on the public registry yet, so the build-from-source path is shown next to it — the commands underneath are the same either way.
npx zephr connectThe one-liner is the designed entry point and is not published to the public registry yet. The build-from-source path beside it is the one that works today.
git clone https://github.com/DigitalSoftDistribution/zephr.git
cd zephr
pnpm install --frozen-lockfile
pnpm --filter @zephr/protocol build && pnpm --filter @zephr/core build
pnpm --filter @zephr/mcp-server build && pnpm --filter @zephr/mcp buildThis is the install path the maintainers use. Once the package publishes, the one-liner replaces these five lines and nothing else about the journey changes.
Illustrative example — not live data
Continuous integration runs on Linux x64 only. Binaries are packaged upstream for macOS and Windows, and they stay unclaimed until a runner proves them here.
A device flow puts a code on the terminal and the approval in the browser. Once it returns, an organization and a project exist — the two containers everything else is scoped by.
The terminal prints a short user code and a verification URL. You approve it in a browser session that already knows who you are, and the terminal picks up the grant.
A project is the outermost container for memory. It gets an immutable identifier, and every belief, admission, and handoff that follows names it.
Illustrative example — not live data
No password is ever typed into a terminal prompt. Credentials land locally with an expiry and refresh on their own; re-running the connect command with a force flag re-authenticates from scratch.
Admission happens before the first tool call, never on it. The connection is bound to one project, one repository, one worktree — immutably, for its whole life. Code indexing is a second, separate yes.
Admitting a scope does not give Zephr permission to read the code in it. Code intelligence is a distinct consent with its own record, and declining it leaves memory and handoff fully working.
A second worktree on the same machine is not covered by this binding. The connection cannot read from it or write to it, and asking does not silently widen the scope.
Illustrative example — not live data
Changing scope is not an edit — it requires a newly admitted connection with a new binding epoch. That is what makes a stale or over-broad binding impossible to inherit by accident.
The run does not stop at “configuration written”. It records a decision, then asks where authentication is enforced — and the answer arrives with its sources, or it abstains and says why.
The first thing written is a decision, not a summary of the session. It is captured explicitly, and it enters the ledger as unreviewed because no human has confirmed it yet.
The answer names the files it came from, at the revision it read them, with the review state of each supporting claim. The provenance is the answer as much as the sentence is.
Nothing in this scope supports a number, and the one document that mentions one changed after it was cited. Recall returns an explicit unavailable with that reason rather than guessing.
Illustrative example — not live data
Abstention is the part worth watching. When the evidence is thin, recall returns an explicit unavailable with the reason attached rather than a confident sentence with nothing behind it.
A handoff is a signed, one-time envelope. The receiving tool verifies the signature and the scope binding before it parses a single claim, and a consumed envelope cannot be replayed.
The claims, their citations, the scope binding, and the review states are serialized into one envelope and signed. A destination-bound one-time code rides along with it.
The receiving client checks the signature, then the one-time destination code, then recomputes the manifest — all before any content is read. Same claims, same review states, same scope, same rules.
Illustrative example — not live data
Authenticate before parse, not parse then check. The signature covers the citations as well as the claims, so a receiving agent can tell whether the supporting files were swapped in transit.
The install documentation carries the build-from-source path that works today. The trust page explains what the review states and abstentions above actually mean.