From fb3bd75056a18cd5e43a233968ec0f6fbaad9f08 Mon Sep 17 00:00:00 2001
From: scosman <scosman@users.noreply.github.com>
Date: Tue, 6 Oct 2026 19:58:58 +0000
Subject: [PATCH] Run the scaffold's serve command with its extra

A new world's README.md and AGENTS.md said `uv run seahaven serve`. The
next steps `seahaven new` prints say `uv sync`, which installs no extra,
so that command failed with "seahaven serve needs the serve extra". Both
now say `uv run --extra serve seahaven serve`, the form the framework
README already uses.

The new test reads every `uv run` command in the scaffold's docs and
fails on a `seahaven serve` or `seahaven mcp` without its extra.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UkCSvbssGtXeqthAaZsmmt
---
 .../cli/templates/base/AGENTS.md.tmpl         |  2 +-
 .../cli/templates/base/README.md.tmpl         |  2 +-
 tests/test_cli_new.py                         | 27 +++++++++++++++++++
 3 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/src/seahaven/cli/templates/base/AGENTS.md.tmpl b/src/seahaven/cli/templates/base/AGENTS.md.tmpl
index 353fa2c..9666a12 100644
--- a/src/seahaven/cli/templates/base/AGENTS.md.tmpl
+++ b/src/seahaven/cli/templates/base/AGENTS.md.tmpl
@@ -7,7 +7,7 @@ db_schema_and_fixtures.md, clock.md, testing.md, state.md, reference/lints.md; c
 this world adds other worlds.
 
 Commands: `uv run seahaven check` (lint; run before every commit), `uv run pytest`,
-`uv run seahaven fixture list`, `uv run seahaven serve`.
+`uv run seahaven fixture list`, `uv run --extra serve seahaven serve`.
 
 Rules: time comes from `ctx.clock` and ids and randomness from `ctx.ids`, so a replay of the same
 fixture and seed on a `fixed` or `tick` clock gives the same result; SQL goes through `ctx.db`
diff --git a/src/seahaven/cli/templates/base/README.md.tmpl b/src/seahaven/cli/templates/base/README.md.tmpl
index 8ba4566..8f1c7cd 100644
--- a/src/seahaven/cli/templates/base/README.md.tmpl
+++ b/src/seahaven/cli/templates/base/README.md.tmpl
@@ -21,7 +21,7 @@ with $package.world.instance(None) as instance:
     instance.call("get_item", item_id=item["id"])
 ```
 
-Serve it over OpenEnv with `uv run seahaven serve`, and run its tests with
+Serve it over OpenEnv with `uv run --extra serve seahaven serve`, and run its tests with
 `uv run pytest`.
 
 ## Making a fixture
diff --git a/tests/test_cli_new.py b/tests/test_cli_new.py
index 1cb3d77..e4a3c52 100644
--- a/tests/test_cli_new.py
+++ b/tests/test_cli_new.py
@@ -7,6 +7,7 @@
 """
 
 import os
+import re
 import shlex
 import subprocess
 import sys
@@ -116,6 +117,32 @@ def test_the_scaffold_declares_the_conflict_between_serve_and_mcp(scaffold: Path
     )
 
 
+def test_the_scaffold_docs_run_each_server_with_its_extra(scaffold: Path) -> None:
+    """Every `uv run seahaven serve` or `seahaven mcp` in the world's docs passes its extra.
+
+    The next steps `seahaven new` prints say `uv sync`, which installs no extra,
+    so a bare `uv run seahaven serve` after it fails with "needs the serve extra".
+    Each server command is named after the extra it needs.
+    """
+    servers = {"serve", "mcp"}
+    commands = [
+        shlex.split(span)
+        for page in ("README.md", "AGENTS.md")
+        for span in re.findall(r"`(uv run [^`]+)`", (scaffold / page).read_text(encoding="utf-8"))
+    ]
+    runs = [
+        (command, command[at + 1])
+        for command in commands
+        for at, word in enumerate(command[:-1])
+        if word == "seahaven" and command[at + 1] in servers
+    ]
+    assert runs, "the scaffold's docs run no server, so this test is asking the wrong question"
+    for command, extra in runs:
+        assert f"--extra {extra}" in shlex.join(command), (
+            f"{shlex.join(command)!r} lacks --extra {extra}"
+        )
+
+
 def test_the_scaffold_installs_pytest_with_uv_sync(scaffold: Path) -> None:
     """The next steps say `uv run pytest`, and seahaven does not depend on pytest.