feat(explorer): ship Effort Graph visualizer with flatbread start

.agents/skills/effort-graph/setup.md

@@ -84,3 +84,22 @@ On resume, begin with `flatbread effort list --status active`, then use bounded
 effort-scoped reads. Capture mutation `generation` tokens and use
 `--strict-min-generation` for immediate read-after-write checks; never implement
 client polling loops. Semantic changes go through `flatbread effort write`.
+
+## 4. Open the explorer (optional)
+
+With a complete `effortGraphContent()` preset in config, Flatbread serves the
+content-relation explorer automatically (`@flatbread/explorer` ships with
+`flatbread`):
+
+```bash
+npx flatbread start --watch --open
+```
+
+Flatbread checks for the prebuilt single-page app (SPA) assets under
+`dist/static/`. When those assets are missing, Flatbread does not serve the
+explorer and `npx flatbread start --open` opens `/graphql` instead.
+
+- Explorer UI (when served): `http://localhost:5057/`
+- Apollo GraphQL sandbox: `http://localhost:5057/graphql`
+
+No separate app install is required.

AGENTS.md

@@ -65,7 +65,7 @@ The repo uses Mergify stacks for PR management. The `mergify-cli` is installed v
 - **Vitest packages run in watch mode by default.** Always use `vitest run` (not bare `vitest`) to get a single run and exit.
 - **`flatbread` CLI is not on PATH globally.** From `examples/nextjs`, prefer `pnpm exec flatbread …` (local binary), or `npx flatbread` from a shell. The `pnpm play` script from the root handles this automatically.
 - **Build before test.** All packages must be built (`pnpm build`) before running tests or starting dev servers. `pnpm test` handles this automatically.
-- **The Next.js example `dev` script uses `--https`.** This requires an SSL certificate. In headless/CI environments, run without `--https`: `pnpm exec flatbread start -- next dev --turbopack`.
+- **`-H, --https` does not make Flatbread serve HTTPS.** The server listens over plain HTTP whatever you pass. From `examples/nextjs`, run `pnpm exec flatbread start -- next dev --turbopack`.
 - **Full local CI parity check:** `pnpm verify` runs lint, typecheck, build, and all tests.
 
 ### Weave merge driver

CONTRIBUTING.md

@@ -24,8 +24,7 @@ Use this path first. The Next.js app reads shared content from
 2. `cd examples/nextjs`
 3. One-shot codegen: `pnpm exec flatbread codegen --verbose` (output: `generated/graphql.ts`; globs and dirs come from `flatbread.config.js`).
 4. Run the app **and** Flatbread together with **`flatbread start`** (there is **no** `flatbread dev` subcommand):
-   - **`pnpm dev`** — starts Next with local HTTPS and watches Flatbread content, config, and GraphQL documents. GraphQL runs on **5057** and Next on **3000**.
-   - Headless / no HTTPS: `pnpm exec flatbread start --watch -- next dev --turbopack`.
+   - **`pnpm dev`** — starts Next and watches Flatbread content, config, and GraphQL documents (`pnpm exec flatbread start --watch -- next dev --turbopack`). GraphQL runs on **5057** and Next on **3000**.
 
 Optional **`pnpm play`** from the repo root is a shortcut for **`cd examples/nextjs && pnpm dev`** — same as step 4 above, not a separate product command.
 
@@ -35,7 +34,10 @@ Optional **`pnpm play`** from the repo root is a shortcut for **`cd examples/nex
 - Build all packages: `pnpm build`
 - **Workspace libraries (watch-only):** `pnpm dev` — runs package `dev` scripts (e.g. `tsup --watch`) for `packages/*`; it does **not** start the Next.js example.
 - **Next.js example:** prefer the flow under [Recommended onboarding](#recommended-onboarding-try-flatbread-in-the-nextjs-example); or `pnpm play` as a convenience alias.
-- **Effort Graph viz (`examples/effort-viz`):** after `pnpm build`, run `pnpm play:efforts` (or `pnpm --filter effort-viz dev`) to dogfood `.flatbread-efforts` with live SSE updates — see that example's README.
+- **Effort Graph explorer:**
+  1. Run `pnpm play:efforts` (builds `@flatbread/explorer` via `preplay:efforts`, then `flatbread start --watch --open`).
+  2. When `flatbread.config.js` uses `effortGraphContent()`, Flatbread serves `@flatbread/explorer` at `http://localhost:5057/`. The Apollo sandbox is at `/graphql`.
+  3. For hot module replacement (HMR) on the single-page app (SPA) shell, run `pnpm exec flatbread start --watch` and `pnpm --filter @flatbread/explorer dev` in parallel. Vite on **5173** proxies API routes to **5057**.
 - Check local CI parity before opening a PR: `pnpm verify`
 
 ## Working on a package

ava.config.js

@@ -13,6 +13,8 @@ export default {
     // parser/runtime guardrails.
     '!packages/codegen/src/__tests__/**',
     '!packages/utils/src/__tests__/**',
+    // Explorer SPA uses Node's built-in test runner (see package scripts).
+    '!packages/explorer/**',
   ],
   extensions: {
     js: true,

docs/local-dev-loop.md

@@ -26,12 +26,11 @@ cd examples/nextjs
 pnpm exec flatbread codegen --verbose
 ```
 
-For development, use the unified watcher. This path avoids the example
-package's HTTPS convenience script and keeps the Flatbread GraphQL endpoint on
-plain HTTP port `5057`.
+For development, use the unified watcher. It serves GraphQL on port `5057`,
+refreshes generated artifacts, and runs Next.js. The example package's
+`pnpm dev` script runs the same command.
 
 ```bash
-# serve GraphQL, refresh generated artifacts, and run Next.js without HTTPS
 pnpm exec flatbread start --watch -- next dev --turbopack
 ```
 
@@ -104,10 +103,8 @@ Watch mode does the following:
   or config change. If a change is invalid, it keeps the previous schema.
 - Watch mode is a long-running process; do not use it in CI or one-shot
   scripts.
-- The Next.js example `pnpm dev` includes `--https` for local convenience, but
-  the Flatbread GraphQL endpoint remains documented as HTTP on `5057`. In
-  headless environments prefer
-  `pnpm exec flatbread start --watch -- next dev --turbopack`.
+- Flatbread serves plain HTTP. The `-H, --https` flag does not change how it
+  listens, so the GraphQL endpoint is always HTTP on `5057`.
 - Codegen failures are logged and do not undo a committed schema generation.
 - Watch mode requires a source plugin with `fetchPaths`; sources without it fail
   fast at startup.