# 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.