First-Run Validation

Use this checklist with someone who has not worked on Zaxy before. The goal is to verify that a normal local developer can install, initialize, inspect memory, and run one example in less than five minutes.

The validation should happen in a clean directory, not in a repo where Zaxy has already been initialized. Do not pre-create .eventloom, .env.local, MCP config files, or graph projection artifacts. The point is to learn whether the public instructions are enough for a new user to reach a useful first checkout without private project knowledge.

Commands

pipx install zaxy-memory
zaxy init
zaxy memory bootstrap --eventloom-path .eventloom
zaxy memory checkout "current project memory and next useful action" --eventloom-path .eventloom
zaxy doctor --eventloom-path .eventloom
python examples/single_agent_memory.py

Success means the user can explain where local memory lives, can see bootstrap guidance, can run checkout without starting a sidecar graph service, and can run one example that prints structured output. If zaxy doctor reports a warning, record the exact text and whether the remediation was understandable. If a command requires Docker, Neo4j, Postgres, a graph password, or a hosted service for the local path, mark the validation as failed.

Report

Operating system:
Shell:
Python version:
Install method:
Time to successful zaxy doctor:
Time to first successful example:
Did any command require Docker, Neo4j, Postgres, or a graph password?
Where did you get stuck?
Which error message was least useful?
What should the quick start say differently?

For release readiness, copy the measured timings into docs/examples/first-run-timing-report.json. zaxy doctor --beta-readiness checks that time_to_successful_doctor_seconds and time_to_first_successful_example_seconds are each at or below 300 seconds and that the clean local path does not require a sidecar service.

Follow-Up

Turn every repeated failure into one of three changes: clearer docs, a doctor check with a specific remediation, or a safer default in zaxy init. Avoid adding new setup options as the first response; the v0.5 release gate is about a boring local path that works without users understanding the full architecture.

Related references: README.md, Getting Started, MCP Quickstart, and site/index.html.