# Zaxy v0.5 Public Positioning and First-Run Trust Implementation Plan

> For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

Goal: Ship v0.5 as a repo-grounded public-positioning and first-run trust release.

Architecture: Keep Eventloom, embedded Kuzu, Memory Checkout, MCP, and Coordinate as the existing architecture. This release aligns public messaging, validates first-run onboarding, polishes examples, and hardens MCP discovery without broad feature expansion.

Tech Stack: Python 3.11+, Typer CLI, MCP Python SDK, pytest, ruff, mypy, Markdown docs, static site builder.

---

## Current Constraints

- The working tree may already contain unrelated coordination benchmark changes. Do not include unrelated changes in this work.
- The roadmap is committed in `docs/v1-roadmap.md`.
- `scripts/build-site-docs.py` is not executable in this checkout; run it with `python scripts/build-site-docs.py`.
- Preserve embedded Kuzu as the default local projection backend.
- Keep core install small. Do not add dependencies for this release unless a task explicitly calls for it.

## File Structure

- Modify `pyproject.toml`: package description and keywords.
- Modify `README.md`: public positioning, quick start, v0.5 docs links, current release facts.
- Modify `docs/why-zaxy.md`: one-sentence thesis and differentiation.
- Modify `docs/getting-started.md`: measured first-run path and validation commands.
- Modify `docs/mcp.md`: clearer model-facing tool descriptions and MCP quickstart.
- Modify `docs/integrations.md`: LangGraph v0.5 path and example link.
- Modify `docs/coordinate-roadmap.md`: v0.5 Coordinate quickstart entry point.
- Create `docs/coordinate-quickstart.md`: concise Coordinate workflow guide.
- Create `docs/mcp-quickstart.md`: concise MCP setup guide.
- Create `docs/first-run-validation.md`: external validation checklist and reporting template.
- Create `examples/single_agent_memory.py`: single-agent durable memory example.
- Modify `examples/langgraph_memory.py`: make the example runnable and smoke-testable.
- Modify `examples/coordinate_three_worker_project.py`: ensure command output demonstrates conflict review, promotion, checkout, and handoff.
- Create `tests/test_v05_positioning.py`: positioning and docs contract tests.
- Create `tests/test_examples_v05.py`: examples smoke tests.
- Modify `tests/test_mcp.py`: stronger tool description assertions.
- Modify `tests/test_packaging.py`: package metadata positioning assertions.
- Modify `tests/test_docs_site.py`: include v0.5 docs in required docs and site expectations.
- Modify `scripts/validate-docs.sh`: no change expected unless validation exposes missing link handling.
- Run `python scripts/build-site-docs.py`: refresh rendered docs.
- Modify generated `site/**/*.html`: generated by the site builder only.
- Modify `CHANGELOG.md`: add unreleased v0.5 section.

## Task 1: Package Metadata and Public Positioning

Files:

- Modify: `pyproject.toml`
- Modify: `README.md`
- Modify: `docs/why-zaxy.md`
- Modify: `tests/test_packaging.py`
- Create: `tests/test_v05_positioning.py`

- [ ] Step 1: Write failing package metadata tests

Add this test to `tests/test_packaging.py`:

    def test_package_metadata_centers_coordinator_memory() -> None:
        """Package discovery metadata should match the v0.5 public positioning."""
        pyproject = tomllib.loads(Path("pyproject.toml").read_text(encoding="utf-8"))

        assert pyproject["project"]["description"] == (
            "Coordinator memory for auditable multi-agent projects"
        )
        keywords = pyproject["project"]["keywords"]
        assert "coordinator-memory" in keywords
        assert "multi-agent" in keywords
        assert "auditable-memory" in keywords

Create `tests/test_v05_positioning.py`:

    """Tests for v0.5 public positioning and release-gate docs."""

    from __future__ import annotations

    from pathlib import Path

    def test_readme_leads_with_coordinator_memory_positioning() -> None:
        """README should lead with the v0.5 ownable product thesis."""
        text = Path("README.md").read_text(encoding="utf-8")

        assert text.startswith("# Zaxy\n\n**Coordinator Memory for Agent Teams.**")
        assert "auditable, replayable, and coordinated memory" in text
        assert "Eventloom append-only source of truth" in text
        assert "embedded Kuzu graph projection" in text
        assert "temporal knowledge graph fabric" not in text.splitlines()[3]

    def test_why_zaxy_states_coordinator_memory_thesis() -> None:
        """Why Zaxy should explain the product thesis before architecture."""
        text = Path("docs/why-zaxy.md").read_text(encoding="utf-8")

        assert "Coordinator Memory for Agent Teams" in text
        assert "worker-local findings" in text
        assert "accepted parent mission state" in text
        assert "vector search alone cannot audit" in text

- [ ] Step 2: Run tests to verify they fail

Run:

    pytest tests/test_packaging.py::test_package_metadata_centers_coordinator_memory \
      tests/test_v05_positioning.py::test_readme_leads_with_coordinator_memory_positioning \
      tests/test_v05_positioning.py::test_why_zaxy_states_coordinator_memory_thesis -q

Expected: fail because the package description, README headline, and Why Zaxy thesis still use older wording.

- [ ] Step 3: Update metadata and README headline

In `pyproject.toml`, change:

    description = "Event-sourced temporal knowledge graph fabric for AI agent memory"

to:

    description = "Coordinator memory for auditable multi-agent projects"

Add these keywords to the existing list without removing embedded/runtime terms:

    "auditable-memory",
    "coordinator-memory",
    "multi-agent",

In `README.md`, change the headline and opening paragraph to:

    # Zaxy

    **Coordinator Memory for Agent Teams.**

    Zaxy gives agent teams auditable, replayable, and coordinated memory: parent
    missions, isolated worker sessions, cited findings, conflict review, approval
    packets, and accepted merge-back into one durable project history. Under the
    hood, it uses an Eventloom append-only source of truth and an embedded Kuzu graph
    projection instead of flattening project memory into markdown files and vector
    chunks.

In `docs/why-zaxy.md`, add or replace the opening thesis with:

    Zaxy is **Coordinator Memory for Agent Teams**. It keeps worker-local findings
    separate from accepted parent mission state, preserves citations and replayable
    history, and makes conflicts reviewable before they contaminate shared project
    memory. Vector search alone cannot audit who claimed what, when it was accepted,
    or which evidence supported the decision.

- [ ] Step 4: Run tests to verify pass

Run:

    pytest tests/test_packaging.py::test_package_metadata_centers_coordinator_memory \
      tests/test_v05_positioning.py::test_readme_leads_with_coordinator_memory_positioning \
      tests/test_v05_positioning.py::test_why_zaxy_states_coordinator_memory_thesis -q

Expected: pass.

- [ ] Step 5: Commit

    git add pyproject.toml README.md docs/why-zaxy.md tests/test_packaging.py tests/test_v05_positioning.py
    git commit -m "docs: center v0.5 coordinator memory positioning"

## Task 2: First-Run Documentation and Validation Checklist

Files:

- Modify: `docs/getting-started.md`
- Create: `docs/first-run-validation.md`
- Modify: `README.md`
- Modify: `tests/test_v05_positioning.py`

- [ ] Step 1: Add failing docs tests

Append to `tests/test_v05_positioning.py`:

    def test_getting_started_documents_five_minute_first_run() -> None:
        """Getting started should provide the measured v0.5 first-run path."""
        text = Path("docs/getting-started.md").read_text(encoding="utf-8")

        assert "Five-minute first run" in text
        assert "pipx install zaxy-memory" in text
        assert "zaxy init" in text
        assert "zaxy memory bootstrap --eventloom-path .eventloom" in text
        assert "zaxy memory checkout" in text
        assert "zaxy doctor --eventloom-path .eventloom" in text
        assert "No Neo4j, Postgres, Docker, or graph password is required" in text

    def test_first_run_validation_template_exists() -> None:
        """External validation should have a concrete reporting template."""
        text = Path("docs/first-run-validation.md").read_text(encoding="utf-8")

        assert "# First-Run Validation" in text
        assert "Time to successful `zaxy doctor`" in text
        assert "Where did you get stuck?" in text
        assert "Operating system" in text
        assert "Python version" in text

- [ ] Step 2: Run tests to verify they fail

Run:

    pytest tests/test_v05_positioning.py::test_getting_started_documents_five_minute_first_run \
      tests/test_v05_positioning.py::test_first_run_validation_template_exists -q

Expected: fail because `docs/first-run-validation.md` does not exist and getting-started lacks the exact v0.5 path.

- [ ] Step 3: Update `docs/getting-started.md`

Add a section near the top:

    ## Five-minute first run

    The default local path is embedded and repo-local. No Neo4j, Postgres, Docker,
    or graph password is required for the first run.

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

    Success means:

    - `.eventloom/` exists;
    - `zaxy memory bootstrap` returns model-facing guidance;
    - `zaxy memory checkout` returns a prompt-ready checkout with diagnostics;
    - `zaxy doctor` reports no blocking local setup errors.

- [ ] Step 4: Create `docs/first-run-validation.md`

Use this content:

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

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

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

- [ ] Step 5: Link validation docs from README

In the README docs list, add:

    - First-run validation: `docs/first-run-validation.md`

- [ ] Step 6: Run tests

Run:

    pytest tests/test_v05_positioning.py -q

Expected: pass.

- [ ] Step 7: Commit

    git add README.md docs/getting-started.md docs/first-run-validation.md tests/test_v05_positioning.py
    git commit -m "docs: add v0.5 first-run validation path"

## Task 3: MCP and Coordinate Quickstarts

Files:

- Create: `docs/mcp-quickstart.md`
- Create: `docs/coordinate-quickstart.md`
- Modify: `docs/mcp.md`
- Modify: `docs/coordinate-roadmap.md`
- Modify: `README.md`
- Modify: `tests/test_v05_positioning.py`

- [ ] Step 1: Add failing quickstart tests

Append to `tests/test_v05_positioning.py`:

    def test_mcp_quickstart_names_recommended_local_clients() -> None:
        """MCP quickstart should route users through one clear local path per client."""
        text = Path("docs/mcp-quickstart.md").read_text(encoding="utf-8")

        assert "# MCP Quickstart" in text
        assert "zaxy init" in text
        assert "codex mcp add" in text
        assert "Claude Desktop" in text
        assert "Cursor" in text
        assert "memory_bootstrap" in text
        assert "memory_checkout" in text

    def test_coordinate_quickstart_has_full_review_workflow() -> None:
        """Coordinate quickstart should show the whole accepted-state workflow."""
        text = Path("docs/coordinate-quickstart.md").read_text(encoding="utf-8")

        for command in (
            "zaxy coordinate start",
            "zaxy coordinate worker create",
            "zaxy coordinate assign",
            "zaxy coordinate report",
            "zaxy coordinate brief",
            "zaxy coordinate decide",
            "zaxy coordinate promote",
            "zaxy coordinate checkout",
            "zaxy coordinate handoff",
        ):
            assert command in text
        assert "worker-local findings are not trusted parent state" in text

- [ ] Step 2: Run tests to verify they fail

Run:

    pytest tests/test_v05_positioning.py::test_mcp_quickstart_names_recommended_local_clients \
      tests/test_v05_positioning.py::test_coordinate_quickstart_has_full_review_workflow -q

Expected: fail because the quickstart docs do not exist.

- [ ] Step 3: Create `docs/mcp-quickstart.md`

Use concise content:

    # MCP Quickstart

    MCP is Zaxy's primary framework-neutral interface. Start with the default local
    path:

zaxy init zaxy memory bootstrap --eventloom-path .eventloom

    For Codex, copy or run the `codex mcp add` command printed by `zaxy init`.

    For Claude Desktop:

zaxy ide-config claude-desktop --eventloom-path .eventloom

    For Cursor:

zaxy ide-config cursor --eventloom-path .eventloom

    At session start, call `memory_bootstrap`. Before substantial work, call
    `memory_checkout` with the current task. After using projected context, call
    `memory_feedback` so Zaxy can reinforce useful memory.

- [ ] Step 4: Create `docs/coordinate-quickstart.md`

Use concise content:

    # Coordinate Quickstart

    Coordinate keeps worker-local exploration separate from trusted parent mission
    state. Worker-local findings are not trusted parent state until the coordinator
    reviews and promotes them.

zaxy coordinate start "Ship auth refactor" --mission auth-main zaxy coordinate worker create --mission auth-main --worker auth-api zaxy coordinate assign --mission auth-main --worker auth-api "Trace API auth failures" zaxy coordinate report --mission auth-main --worker auth-api \ --summary "API failures trace to expired JWKS cache handling" \ --evidence "src/auth/jwks.py:42" \ --claim-key auth.failure.cause \ --claim-value expired-jwks-cache zaxy coordinate brief --mission auth-main FINDING_ID="$(python - <<'PY' from pathlib import Path from zaxy.coordination import CoordinationManager brief = CoordinationManager(eventloom_path=Path('.eventloom')).brief('auth-main') print(brief.findings[0].finding_id) PY )" zaxy coordinate decide --mission auth-main --finding "$FINDING_ID" --status accepted zaxy coordinate promote --mission auth-main --finding "$FINDING_ID" zaxy coordinate checkout --mission auth-main zaxy coordinate handoff --mission auth-main --summary "Accepted auth finding promoted."

    Use `zaxy coordinate approval-packet` when a remote reviewer needs to inspect
    pending or conflicted findings before promotion.

- [ ] Step 5: Link quickstarts from existing docs

In `docs/mcp.md`, add near the top:

    For a concise local setup path, see MCP Quickstart (`mcp-quickstart.md`).

In `docs/coordinate-roadmap.md`, add near the top:

    For the shortest working workflow, see Coordinate Quickstart (`coordinate-quickstart.md`).

In `README.md`, add the docs links:

    - MCP quickstart: `docs/mcp-quickstart.md`
    - Coordinate quickstart: `docs/coordinate-quickstart.md`

- [ ] Step 6: Run tests

Run:

    pytest tests/test_v05_positioning.py -q

Expected: pass.

- [ ] Step 7: Commit

    git add README.md docs/mcp.md docs/mcp-quickstart.md docs/coordinate-roadmap.md docs/coordinate-quickstart.md tests/test_v05_positioning.py
    git commit -m "docs: add v0.5 MCP and Coordinate quickstarts"

## Task 4: Single-Agent Example

Files:

- Create: `examples/single_agent_memory.py`
- Create: `tests/test_examples_v05.py`
- Modify: `README.md`

- [ ] Step 1: Write failing example smoke test

Create `tests/test_examples_v05.py`:

    """Smoke tests for v0.5 public examples."""

    from __future__ import annotations

    import json
    import subprocess
    import sys
    from pathlib import Path

    def test_single_agent_memory_example_runs() -> None:
        """Single-agent example should run without sidecars and print JSON evidence."""
        result = subprocess.run(
            [sys.executable, "examples/single_agent_memory.py"],
            check=False,
            capture_output=True,
            text=True,
        )

        assert result.returncode == 0, result.stderr
        payload = json.loads(result.stdout)
        assert payload["session_id"] == "single-agent-demo"
        assert payload["bootstrap"]["session_id"] == "single-agent-demo"
        assert payload["checkout"]["session_id"] == "single-agent-demo"
        assert payload["event_count"] >= 2

- [ ] Step 2: Run test to verify it fails

Run:

    pytest tests/test_examples_v05.py::test_single_agent_memory_example_runs -q

Expected: fail because `examples/single_agent_memory.py` does not exist.

- [ ] Step 3: Create `examples/single_agent_memory.py`

Use this script:

    """Single-agent durable memory example.

    Run:
        python examples/single_agent_memory.py
    """

    from __future__ import annotations

    import asyncio
    import json
    import tempfile
    from pathlib import Path

    from zaxy import MemoryFabric
    from zaxy.capabilities import build_memory_bootstrap

    async def run_example(eventloom_path: Path) -> dict[str, object]:
        session_id = "single-agent-demo"
        fabric = MemoryFabric(eventloom_path)
        try:
            await fabric.append(
                "decision.recorded",
                actor="user",
                payload={
                    "decision": "Use Memory Checkout before major project work.",
                    "topic": "memory activation",
                },
                session_id=session_id,
            )
            await fabric.after_turn(
                role="assistant",
                content="I will call Memory Checkout before roadmap and implementation work.",
                session_id=session_id,
                query="memory activation policy",
                source="example",
            )
            checkout = await fabric.checkout_memory(
                "What should the agent do before major project work?",
                session_id=session_id,
                limit=5,
                max_recent_events=10,
            )
        finally:
            await fabric.close()

        bootstrap = build_memory_bootstrap(
            session_id=session_id,
            current_task="single-agent durable memory demo",
            eventloom_path=eventloom_path,
            workspace_root=Path("."),
            activity="bootstrap",
        )
        event_count = len(list(eventloom_path.glob("*.jsonl")))
        return {
            "session_id": session_id,
            "bootstrap": {
                "session_id": bootstrap["session_id"],
                "recommended_tool": bootstrap["recommended_tool"],
            },
            "checkout": {
                "session_id": checkout.session_id,
                "query": checkout.query,
                "quality": checkout.quality,
                "warning_count": len(checkout.warnings),
            },
            "event_count": event_count,
        }

    def main() -> None:
        with tempfile.TemporaryDirectory(prefix="zaxy-single-agent-") as tmp:
            payload = asyncio.run(run_example(Path(tmp) / ".eventloom"))
        print(json.dumps(payload, indent=2, sort_keys=True))

    if __name__ == "__main__":
        main()

- [ ] Step 4: Link the example from README

Add under quick start or examples:

    Run the single-agent memory example:

python examples/single_agent_memory.py

- [ ] Step 5: Run test

Run:

    pytest tests/test_examples_v05.py::test_single_agent_memory_example_runs -q

Expected: pass.

- [ ] Step 6: Commit

    git add README.md examples/single_agent_memory.py tests/test_examples_v05.py
    git commit -m "docs: add single-agent memory example"

## Task 5: LangGraph and Coordinate Example Smoke Coverage

Files:

- Modify: `examples/langgraph_memory.py`
- Modify: `examples/coordinate_three_worker_project.py`
- Modify: `tests/test_examples_v05.py`
- Modify: `docs/integrations.md`

- [ ] Step 1: Add failing smoke tests

Append to `tests/test_examples_v05.py`:

    def test_coordinate_three_worker_example_runs() -> None:
        """Coordinate example should produce a complete mission summary."""
        result = subprocess.run(
            [sys.executable, "examples/coordinate_three_worker_project.py"],
            check=False,
            capture_output=True,
            text=True,
        )

        assert result.returncode == 0, result.stderr
        payload = json.loads(result.stdout)
        assert payload["mission_id"] == "auth-main"
        assert payload["worker_count"] == 3
        assert payload["accepted_count"] >= 1
        assert payload["handoff_id"]

    def test_langgraph_example_runs_without_langgraph_dependency() -> None:
        """LangGraph example should smoke-test the dependency-light adapter."""
        result = subprocess.run(
            [sys.executable, "examples/langgraph_memory.py"],
            check=False,
            capture_output=True,
            text=True,
        )

        assert result.returncode == 0, result.stderr
        payload = json.loads(result.stdout)
        assert payload["session_id"] == "langgraph-demo"
        assert payload["has_zaxy_context"] is True
        assert payload["kind"] in {"memory_checkout", "context_assembly"}

- [ ] Step 2: Run tests to verify current behavior

Run:

    pytest tests/test_examples_v05.py::test_coordinate_three_worker_example_runs \
      tests/test_examples_v05.py::test_langgraph_example_runs_without_langgraph_dependency -q

Expected: one or both may fail if output is not JSON or keys differ.

- [ ] Step 3: Make examples emit stable JSON summaries

For `examples/coordinate_three_worker_project.py`, ensure `main()` prints only JSON to stdout:

    print(json.dumps(run_demo(), indent=2, sort_keys=True))

Ensure the returned payload includes:

    {
        "mission_id": brief.mission_id,
        "worker_count": len(brief.workers),
        "accepted_count": len(checkout.accepted_findings),
        "conflict_count": len(brief.conflicts),
        "handoff_id": handoff.handoff_id,
    }

For `examples/langgraph_memory.py`, add or update `main()` so it runs the dependency-light node and prints:

    {
        "session_id": "langgraph-demo",
        "has_zaxy_context": bool(state.get("zaxy_context")),
        "kind": state.get("zaxy", {}).get("kind", "context_assembly"),
    }

- [ ] Step 4: Update integrations docs

In `docs/integrations.md`, add a short v0.5 runnable example note:

    Smoke the dependency-light LangGraph path without installing LangGraph:

python examples/langgraph_memory.py

- [ ] Step 5: Run tests

Run:

    pytest tests/test_examples_v05.py -q

Expected: pass.

- [ ] Step 6: Commit

    git add docs/integrations.md examples/langgraph_memory.py examples/coordinate_three_worker_project.py tests/test_examples_v05.py
    git commit -m "test: smoke v0.5 public examples"

## Task 6: MCP Tool Description Polish

Files:

- Modify: `src/zaxy/mcp_server.py`
- Modify: `tests/test_mcp.py`
- Modify: `docs/mcp.md`

- [ ] Step 1: Add failing MCP description tests

Add to `tests/test_mcp.py` inside `TestToolSchema`:

        def test_v05_tool_descriptions_are_model_actionable(self) -> None:
            """Core MCP tools should describe when a model should call them."""
            descriptions = {tool.name: tool.description for tool in TOOLS}

            assert "session start" in descriptions["memory_bootstrap"].lower()
            assert "before substantial work" in descriptions["memory_checkout"].lower()
            assert "after using retrieved context" in descriptions["memory_feedback"].lower()
            assert "worker-local" in descriptions["coordination_report_finding"].lower()
            assert "accepted coordination state" in descriptions["coordination_checkout"].lower()
            assert "remote reviewer" in descriptions["coordination_approval_packet"].lower()

- [ ] Step 2: Run test to verify it fails

Run:

    pytest tests/test_mcp.py::TestToolSchema::test_v05_tool_descriptions_are_model_actionable -q

Expected: fail because current descriptions are terse.

- [ ] Step 3: Update tool descriptions

In `src/zaxy/mcp_server.py`, update these `Tool(description=...)` strings:

    description="At session start, return compact Zaxy memory guidance and the recommended first checkout call.",

for `memory_bootstrap`.

    description="Before substantial work, checkout current, cited, prompt-ready memory state for a session.",

for `memory_checkout`.

    description="After using retrieved context, record whether a memory item was useful, stale, corrected, or reinforced.",

for `memory_feedback`.

    description="Record a worker-local coordination finding with evidence; it is not trusted parent state until reviewed and promoted.",

for `coordination_report_finding`.

    description="Return accepted coordination state for prompt injection, with optional diagnostics for pending or conflicted findings.",

for `coordination_checkout`.

    description="Return a portable pending/conflicted finding packet for a remote reviewer.",

for `coordination_approval_packet`.

- [ ] Step 4: Update MCP docs

In `docs/mcp.md`, add a "Model call rhythm" section:

    ## Model Call Rhythm

    Use Zaxy tools in this order:

    1. At session start, call `memory_bootstrap`.
    2. Before substantial work, call `memory_checkout`.
    3. For multi-agent missions, use Coordinate tools to record worker-local findings and promote only accepted state.
    4. After using retrieved context, call `memory_feedback`.

- [ ] Step 5: Run tests

Run:

    pytest tests/test_mcp.py::TestToolSchema::test_v05_tool_descriptions_are_model_actionable -q

Expected: pass.

- [ ] Step 6: Commit

    git add src/zaxy/mcp_server.py tests/test_mcp.py docs/mcp.md
    git commit -m "docs: make MCP tools model-actionable"

## Task 7: Docs Site Coverage and Rendered Pages

Files:

- Modify: `tests/test_docs_site.py`
- Generated: `site/README.html`
- Generated: `site/docs/*.html`

- [ ] Step 1: Add failing docs coverage tests

Modify `REQUIRED_DOCS` in `tests/test_docs_site.py` to include:

        "docs/v1-roadmap.md",
        "docs/mcp-quickstart.md",
        "docs/coordinate-quickstart.md",
        "docs/first-run-validation.md",

Add a test:

    def test_v05_docs_render_to_static_site() -> None:
        """v0.5 roadmap and quickstarts should be published to the static site."""
        for path in (
            "site/docs/v1-roadmap.html",
            "site/docs/mcp-quickstart.html",
            "site/docs/coordinate-quickstart.html",
            "site/docs/first-run-validation.html",
        ):
            assert Path(path).exists()

- [ ] Step 2: Run test to verify it fails before rendering

Run:

    pytest tests/test_docs_site.py::test_v05_docs_render_to_static_site -q

Expected: fail until generated pages exist.

- [ ] Step 3: Render docs

Run:

    python scripts/build-site-docs.py

Expected: renders documentation pages under `site/`.

- [ ] Step 4: Run docs tests and validation

Run:

    pytest tests/test_docs_site.py::test_v05_docs_render_to_static_site -q
    scripts/validate-docs.sh --root .

Expected: pass.

- [ ] Step 5: Commit

    git add tests/test_docs_site.py site/README.html site/docs
    git commit -m "docs: publish v0.5 roadmap quickstarts"

## Task 8: Changelog and Release Gate Notes

Files:

- Modify: `CHANGELOG.md`
- Modify: `README.md`
- Modify: `docs/v1-roadmap.md`
- Modify: `tests/test_v05_positioning.py`

- [ ] Step 1: Add failing changelog test

Append to `tests/test_v05_positioning.py`:

    def test_changelog_has_unreleased_v05_section() -> None:
        """v0.5 planning work should have a changelog section before release."""
        text = Path("CHANGELOG.md").read_text(encoding="utf-8")

        assert "## 0.5.0 - Unreleased" in text
        assert "Coordinator Memory for Agent Teams" in text
        assert "first-run validation" in text
        assert "MCP Quickstart" in text

- [ ] Step 2: Run test to verify it fails

Run:

    pytest tests/test_v05_positioning.py::test_changelog_has_unreleased_v05_section -q

Expected: fail until changelog is updated.

- [ ] Step 3: Update `CHANGELOG.md`

Add this section above `0.4.0`:

    ## 0.5.0 - Unreleased

    - Repositioned Zaxy around **Coordinator Memory for Agent Teams** across package metadata, README, docs, and the static site.
    - Added first-run validation docs so new users can report install, init, bootstrap, checkout, doctor, and example timing.
    - Added MCP Quickstart and Coordinate Quickstart docs for the v0.5 public path.
    - Added single-agent, LangGraph, and Coordinate example smoke coverage.
    - Improved MCP tool descriptions so model-facing clients know when to call bootstrap, checkout, feedback, and coordination tools.

- [ ] Step 4: Update roadmap status

In `docs/v1-roadmap.md`, under v0.5, add a brief status note:

    **Implementation status:** planned in
    `docs/superpowers/plans/2026-05-30-v0-5-public-positioning-first-run-trust.md`.

- [ ] Step 5: Run tests

Run:

    pytest tests/test_v05_positioning.py -q

Expected: pass.

- [ ] Step 6: Commit

    git add CHANGELOG.md README.md docs/v1-roadmap.md tests/test_v05_positioning.py
    git commit -m "docs: record v0.5 release gate notes"

## Task 9: Full Verification

Files:

- No code changes unless verification exposes an issue.

- [ ] Step 1: Run focused test set

Run:

    pytest tests/test_v05_positioning.py tests/test_examples_v05.py tests/test_mcp.py::TestToolSchema tests/test_packaging.py tests/test_docs_site.py -q

Expected: all pass.

- [ ] Step 2: Run lint and types

Run:

    ruff check src tests examples
    mypy src

Expected: both pass.

- [ ] Step 3: Run docs validation

Run:

    python scripts/build-site-docs.py --check
    scripts/validate-docs.sh --root .

Expected: both pass.

- [ ] Step 4: Run full tests if time permits

Run:

    pytest

Expected: pass with coverage at or above 92%.

- [ ] Step 5: Run release smoke

Run:

    zaxy doctor --release-smoke

Expected: pass or report only known release-version issues if `0.5.0` has not been cut yet. If it fails because `CHANGELOG.md` has an unreleased section rather than a released version, record that as expected pre-release state in the handoff.

- [ ] Step 6: Final commit if verification required fixes

    git add CHANGELOG.md README.md pyproject.toml docs examples tests src/zaxy/mcp_server.py site
    git commit -m "test: verify v0.5 release gate docs"

## Implementation Notes

- Keep each task in a separate commit.
- Do not commit unrelated existing changes in coordination benchmark files.
- If generated site output changes many existing pages, inspect the diff before committing and confirm changes are caused by docs links or site builder output.
- If coverage dips below 92%, add targeted tests for the changed behavior instead of lowering the ratchet.
- If `zaxy doctor --release-smoke` expects an exact released version, do not force it during planning work. Capture the result and leave final version bump for the release task.

## Success Checklist

- `pyproject.toml` and README agree on Coordinator Memory positioning.
- First-run docs show the no-sidecar embedded path.
- MCP and Coordinate quickstarts exist and render to the site.
- Public examples run as smoke tests.
- MCP tool descriptions are model-actionable.
- Changelog has a v0.5 unreleased section.
- Docs validation passes.
- Focused tests pass.
- Full verification status is recorded in the final handoff.