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

```python
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`:

```python
"""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:

```bash
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:

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

to:

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

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

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

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

```markdown
# 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:

```markdown
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:

```bash
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**

```bash
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`:

```python
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:

```bash
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:

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

```bash
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:

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

```bash
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:

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

- [ ] **Step 6: Run tests**

Run:

```bash
pytest tests/test_v05_positioning.py -q
```

Expected: pass.

- [ ] **Step 7: Commit**

```bash
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`:

```python
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:

```bash
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:

````markdown
# MCP Quickstart

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

```bash
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:

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

For Cursor:

```bash
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:

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

```bash
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:

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

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

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

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

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

- [ ] **Step 6: Run tests**

Run:

```bash
pytest tests/test_v05_positioning.py -q
```

Expected: pass.

- [ ] **Step 7: Commit**

```bash
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`:

```python
"""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:

```bash
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:

```python
"""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:

````markdown
Run the single-agent memory example:

```bash
python examples/single_agent_memory.py
```
````

- [ ] **Step 5: Run test**

Run:

```bash
pytest tests/test_examples_v05.py::test_single_agent_memory_example_runs -q
```

Expected: pass.

- [ ] **Step 6: Commit**

```bash
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`:

```python
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:

```bash
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:

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

Ensure the returned payload includes:

```python
{
    "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:

```python
{
    "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:

````markdown
Smoke the dependency-light LangGraph path without installing LangGraph:

```bash
python examples/langgraph_memory.py
```
````

- [ ] **Step 5: Run tests**

Run:

```bash
pytest tests/test_examples_v05.py -q
```

Expected: pass.

- [ ] **Step 6: Commit**

```bash
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`:

```python
    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:

```bash
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:

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

for `memory_bootstrap`.

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

for `memory_checkout`.

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

for `memory_feedback`.

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

for `coordination_report_finding`.

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

for `coordination_checkout`.

```python
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:

```markdown
## 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:

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

Expected: pass.

- [ ] **Step 6: Commit**

```bash
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:

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

Add a test:

```python
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:

```bash
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:

```bash
python scripts/build-site-docs.py
```

Expected: renders documentation pages under `site/`.

- [ ] **Step 4: Run docs tests and validation**

Run:

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

Expected: pass.

- [ ] **Step 5: Commit**

```bash
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`:

```python
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:

```bash
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`:

```markdown
## 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:

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

- [ ] **Step 5: Run tests**

Run:

```bash
pytest tests/test_v05_positioning.py -q
```

Expected: pass.

- [ ] **Step 6: Commit**

```bash
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:

```bash
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:

```bash
ruff check src tests examples
mypy src
```

Expected: both pass.

- [ ] **Step 3: Run docs validation**

Run:

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

Expected: both pass.

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

Run:

```bash
pytest
```

Expected: pass with coverage at or above 92%.

- [ ] **Step 5: Run release smoke**

Run:

```bash
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**

```bash
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.
