@specbook/cli 0.3.0 → 0.4.0

package/agent-guide.md

@@ -0,0 +1,170 @@
+# Specbook
+
+> Specbook turns an OpenAPI spec into typed requests and flows that run as your API docs, as tests in CI, and as a monitor against production. Requests and flows are TypeScript files in the project's repo. The same files run in the terminal (`specbook test`), as one bundled `.mjs` file (`specbook bundle`), and in the browser (the docs UI, the QA portal and the "Try it" panel).
+
+Use this file when you are asked to add or change requests, flows, checks or setup in a project that uses Specbook (`@specbook/cli`, `@specbook/core`). Needs Node 24.
+
+Words used here: an **operation** is one endpoint of the spec. A **request** is a `.req.ts` file that calls one operation. A **flow** is a `.seq.ts` file that runs requests in order.
+
+## Set up a project
+
+1. `npm install --save-dev @specbook/cli @specbook/core`
+2. `npx specbook init` creates `.specbook/specbook.config.ts`, `.specbook/environments/` and the `#api/*` import in `package.json`.
+3. `npx specbook add <service> --spec <path or URL>` registers a spec and generates its types. A URL is downloaded to `openapi/` and recorded in `openapi/sources.json`. Set the service's address in `vars` (for example `petstoreUrl`) in the config; each environment can override it in `.specbook/environments/<env>.env`.
+4. `npx specbook check` validates specs, imports and environment files. `npx specbook generate` regenerates types; `test`, `dev` and `build` do it when they need to.
+
+Never edit `.generated/`. Never put a secret in a file: name it in the config (`secrets: { API_KEY: {} }`) and read it as `{{secrets.API_KEY}}`; its value comes from an environment variable or a gitignored `<env>.secrets.env`.
+
+## Add a request
+
+Put it at `requests/<service>/<name>.req.ts`. Import the operation from `#api/<service>` and export the request as the default:
+
+```ts
+import { FindPetsByStatus } from '#api/petstore'
+
+export default FindPetsByStatus.request({
+  name: 'Find pets by status',
+  tags: ['smoke', 'monitor'],
+  query: { status: '{{status}}' },
+  init: { status: 'available' },
+  capture: { pets: (res) => (res.status === 200 ? res.data : []) },
+  assert: (res, { assert }) => {
+    assert.is(res.status, 200, 'ok')
+    if (res.status === 200) assert.ok(res.data.length > 0, 'returns at least one pet')
+  },
+})
+```
+
+- Find the operation first. Its export name is the spec's `operationId` in PascalCase (`getPetById` becomes `GetPetById`). Read
+  `.generated/<service>/index.ts` (read only) or the spec to see them all; your editor completes `import { ... } from '#api/<service>'`.
+- Fields: `name`, `tags`, `init` (default values), `path`, `query`, `headers`, `data` (the body), `capture`, `assert`, `safe`, `timeoutMs`.
+- Give every `{{name}}` the request uses a default in `init`. Then the request also runs on its own, and its `vars` are typed.
+- `{{name}}` is filled from `init`, a flow's inputs, values captured by earlier steps, and the config's `vars`.
+- Path, query and body are typed from the spec. Let the compiler tell you what is missing.
+- Add `tags: ['monitor']` to what should run against production.
+- `safe: true` marks a POST that only reads (a search, a GraphQL query) so it is allowed in a `--safe` run.
+
+## Asserts
+
+- A request with no `assert` passes when the response is 2xx (the check is listed as `status is 2xx`). An `assert` replaces that check, so state the status you expect, even a 404.
+- The helper is uvu's `assert` (`ok`, `is`, `equal`, `match`, `type`, `instance`, `throws`, with `not.` versions). Give every call a short label as its last argument: `assert.is(res.status, 200, 'order placed')`. The label is what the report shows.
+- Check `res.status` before reading `res.data`: `if (res.status === 200) { ... }`. Then `res.data` has the type the spec gives that response.
+- The second argument also gives `vars` (everything in scope plus this step's captures) and `req` (the request as sent).
+- Every check runs and is reported. A failed one shows expected against received.
+
+## Capture
+
+`capture: { orderId: (res, vars) => (res.status === 200 ? res.data.id : undefined) }` keeps a value from the response for later steps. Return plain, JSON-serializable data. In a flow the value is `ctx.captured.orderId` and `{{orderId}}` in a later request.
+
+## Pass whole values, not just ids
+
+A placeholder that is the whole string gives the value itself, with its type: an object, an array, a number, a boolean. Capture the thing
+and send it on:
+
+- `capture: { category: (res) => (res.status === 200 ? res.data.category : undefined) }`, then `data: { category: '{{category}}' }` sends
+  the object. An array of objects works the same way (`tags: '{{tags}}'`), and the whole body can be one placeholder: `data: '{{order}}'`.
+- Inside a longer string the value becomes text, and an object or array becomes JSON: `name: 'copy of {{category.name}}'`.
+- Reach into a value with dots and array positions: `{{pet.category.name}}`, `{{tags[0].id}}` (`{{tags.0.id}}` is the same), `{{grid[1][0]}}`.
+  `{{tags.length}}` is the count. A name or position that is not there, such as `{{tags[5].id}}`, fails the step with `Missing variable`,
+  and only a value's own fields are read (not `toString` or `constructor`). There are no expressions or filters: for anything computed,
+  do it in `capture`, which is a function, and capture the shaped result.
+- Whole objects belong in the JSON or form body. Path, query and header values are text: an array in a query repeats the key, but an
+  object there is sent as "[object Object]". Use one of its fields (`{{pet.category.name}}`) or build the string in `capture`.
+- A number stays a number. To send one as a string, capture `String(id)`.
+- A name that does not exist fails the step with `Missing variable "{{name}}"`.
+
+## Build a flow
+
+Put it at `sequences/<name>.seq.ts`, importing the requests it uses:
+
+```ts
+import { c, sequence } from '@specbook/core'
+import findPets from '../requests/petstore/find-pets.req'
+import placeOrder from '../requests/petstore/place-order.req'
+
+export default sequence({
+  id: 'adopt-pet',
+  title: 'Adopt a pet',
+  description: 'Find available pets, pick one, order it.',
+  tags: ['petstore', 'smoke'],
+  inputs: {
+    quantity: c.number({ default: 1, min: 1, description: 'How many to order.' }),
+  },
+})
+  .step('Find available pets', findPets) // captures `pets`
+  .input('Choose a pet', (ctx) => ({
+    petId: c.select(ctx.captured.pets, {
+      label: (p) => `${p.name} (#${p.id})`,
+      value: (p) => p.id as number,
+      default: 0,
+    }),
+  }))
+  .step('Place order', placeOrder) // sends { petId, quantity }
+```
+
+- `.step(name, request)`; the second argument may be `(ctx) => request`, where `ctx` has `inputs`, `captured`, `vars` and `env`.
+- `request.with({ ... })` changes a request for one step (for example its `assert`).
+- Also: `.input(name, ctx => controls)` asks a person for values, `.each(name, items, make)` repeats a request per item, `.check(name, fn)` asserts on the flow's state, `.use(otherFlow)` includes another flow.
+- Controls are `c.number`, `c.text`, `c.select`, `c.multiselect`, `c.boolean`, `c.date`, `c.object`, `c.array`. A flow also runs unattended in CI and as a monitor, so every input and every `.input()` control needs a default that makes sense with nobody to ask.
+- For generated data: `import { faker } from '@specbook/core/faker'` and use it in a default, for example `c.text({ default: () => faker.person.fullName() })`.
+- Each step is also a request you can run alone.
+
+### Recipe: list, check, pick, act
+
+For "fetch the products, assert there is at least one, pick one, add it to the cart with a quantity from the inputs":
+
+1. `requests/shop/list-products.req.ts`: the list operation, `assert` that `res.data.length > 0`, and capture the list:
+   `capture: { products: (res) => (res.status === 200 ? res.data : []) }`.
+2. `requests/shop/add-to-cart.req.ts`: the add operation with `init: { productId: 1, quantity: 1 }` and
+   `data: { productId: '{{productId}}', quantity: '{{quantity}}' }`.
+3. `sequences/add-to-cart.seq.ts`: `inputs: { quantity: c.number({ default: 1, min: 1 }) }`, then
+   `.step('List products', listProducts)`, `.input('Choose a product', (ctx) => ({ productId: c.select(ctx.captured.products, { label: (p) => p.name, value: (p) => p.id, default: 0 }) }))`,
+   then `.step('Add to cart', addToCart)`.
+4. Run it: `npx specbook test --grep "Add to cart"`, and `--input quantity=3` to try another value.
+
+Capture is declared on the request that makes the response, and the flow reads it as `ctx.captured.<name>`. Pick the way to choose:
+- To take the first item with nobody asked, capture it in the list request (`capture: { productId: (res) => (res.status === 200 ? res.data[0]?.id : undefined) }`)
+  and leave out `.input()`. The next request's `{{productId}}` is filled in.
+- To let a person choose in the portal, use `.input()` with `c.select`, as above. Automation is not asked and takes the default, the first item.
+
+## Mocks
+
+The `mock` environment (the default for `specbook test` and the UI) answers from the spec's examples with the request's values filled in, and needs no server. When a check needs data the example lacks, wrap the request in `withMock` from `@specbook/core`; the file's one export stays the default:
+
+```ts
+export default withMock(GetOrderById.request({ /* ... */ }), (req, res) => {
+  if (res.status === 200) res.data.status = 'placed'
+})
+```
+
+## Run it
+
+- `npx specbook test` runs everything against mock data. `--env staging` runs against a real environment. `--tag monitor`, `--grep <re>`, `--list`, `--input name=value`, `--retries 1` (a pass on retry is reported as flaky), `--timeout <ms>`.
+- Against production always pass `--safe`: a request that is not a GET, HEAD or OPTIONS is refused.
+- Exit codes: 0 passed, 1 a flow failed or errored, 2 it could not run (missing secrets, a missing spec), 3 usage.
+- `npx specbook dev` opens the UI; `npx specbook build --minimal` publishes a small portal of only the project's requests and flows for QA; `npx specbook bundle` writes one `.mjs` that runs with just node, for CI and ops.
+
+## Write isomorphic code
+
+Requests and flows run in three places: node (`specbook test`), the single-file bundle (`specbook bundle`, run with just node) and the
+browser (the docs UI, the QA portal and "Try it"). Everything they import must work in all three. A build and a green `specbook test`
+do not prove it: a request that needs Node builds cleanly and passes in node, and only fails when someone opens it in the portal.
+
+- Use what is already there: `fetch` (global), `@specbook/core` (`assert`, `faker` from `@specbook/core/faker`, the `c` controls) and
+  the language itself (`Date`, `Intl`, `URL`, `btoa`, `crypto.randomUUID()`). Prefer no new dependencies. A library such as lodash does
+  work in the browser, but it adds a lot of weight to the portal and the bundle for something a few lines of code do.
+- Do not use `Buffer`: in the browser it is "Buffer is not defined". Use `btoa`, `Uint8Array`, `TextEncoder` and `TextDecoder`.
+- Do not use Node built-ins (`fs`, `path`, `os`, `net`, `child_process`): in the browser the first call throws "externalized for browser
+  compatibility". For a file a request uploads, use the request's file `data`, which is embedded in the portal and the bundle.
+- Do not read `process.env`. In the browser it is empty and silently `undefined`, so a request that reads a secret from it sends nothing.
+  Use `{{secrets.NAME}}` for secrets and the config's `vars` (`{{name}}`) for everything else.
+- Do not use native addons, packages that `require()` a computed path, or packages that read their own files at run time.
+- If a new package is unavoidable, it must be plain ESM JavaScript with no install scripts and no Node built-ins. Prove it three ways:
+  `npx specbook test`, `npx specbook bundle`, and `npx specbook build --minimal` followed by running the request in the portal.
+- `specbook bundle --external <package>` is not a way around this. It leaves the import for node to resolve and a browser cannot, so a
+  request that needs it will not run in the portal. Do not use it for requests or flows. There is no node-only exception: if a request
+  cannot be written with `fetch` and plain code, tell the user instead of adding a Node-only dependency.
+
+## Notes beside the code (optional)
+
+Markdown next to what it describes is shown in the UI: `requests/<service>/<Operation>/README.md` for an operation, `<name>.req.md` beside a request, `<name>.seq.md` beside a flow. A heading made of one code span (`` ## `petId` ``) attaches its text to that field.

package/dist/bin.js

@@ -2143,8 +2143,10 @@ function installFaker(mod, config = {}, opts = {}) {
 }
 
 // ../core/src/template.ts
-var WHOLE = /^\s*\{\{\s*([\w.$-]+)\s*\}\}\s*$/;
-var EMBED = /\{\{\s*([\w.$-]+)\s*\}\}/g;
+var NAME = String.raw`[\w.$\[\]-]+`;
+var WHOLE = new RegExp(String.raw`^\s*\{\{\s*(${NAME})\s*\}\}\s*$`);
+var EMBED = new RegExp(String.raw`\{\{\s*(${NAME})\s*\}\}`, "g");
+var rootName = (name) => name.split(/[.[]/, 1)[0];
 var DEFERRED_NAMESPACES = ["secrets", "session"];
 var TemplateError = class extends Error {
   constructor(variable) {
@@ -2169,11 +2171,12 @@ function fromFaker(path) {
   }
   return { found: true, value: typeof cur === "function" ? cur.call(parent) : cur };
 }
+var steps = (path) => path.replace(/\[(\d+)\]/g, ".$1").split(".");
 function lookup(scope, path) {
   if (isFakerName(path)) return fromFaker(path);
   let cur = scope;
-  for (const part of path.split(".")) {
-    if (cur !== null && typeof cur === "object" && part in cur) {
+  for (const part of steps(path)) {
+    if (cur !== null && typeof cur === "object" && Object.hasOwn(cur, part)) {
       cur = cur[part];
     } else {
       return { found: false };
@@ -2862,7 +2865,7 @@ function createColors(enabled) {
 // ../core/src/reporters/list.ts
 var MARKS = { pass: "\u2713", fail: "\u2717", error: "!", skipped: "\u2013" };
 var formatDuration = (ms) => ms < 1e3 ? `${Math.round(ms)}ms` : ms < 6e4 ? `${(ms / 1e3).toFixed(2)}s` : `${Math.floor(ms / 6e4)}m ${Math.round(ms % 6e4 / 1e3)}s`;
-var leaves = (steps) => steps.flatMap((s) => s.children?.length ? leaves(s.children) : [s]);
+var leaves = (steps3) => steps3.flatMap((s) => s.children?.length ? leaves(s.children) : [s]);
 function paint(status, c, text) {
   return status === "pass" ? c.green(text) : status === "skipped" ? c.dim(text) : status === "error" ? c.yellow(text) : c.red(text);
 }
@@ -2941,21 +2944,21 @@ function formatSummary(results, o = {}) {
   const c = o.colors ?? createColors(false);
   const t = reportTotals(results);
   const part = (n, word, paintFn) => n ? paintFn(`${n} ${word}`) : "";
-  const join18 = (...parts) => parts.filter(Boolean).join(c.dim(" | ")) || c.dim("none");
+  const join19 = (...parts) => parts.filter(Boolean).join(c.dim(" | ")) || c.dim("none");
   const lines2 = [
     "",
-    `${c.bold(" Flows      ")} ${join18(
+    `${c.bold(" Flows      ")} ${join19(
       part(t.flows.failed, "failed", c.red),
       part(t.flows.errored, "errored", c.yellow),
       part(t.flows.flaky, "flaky", c.yellow),
       part(t.flows.passed, "passed", c.green)
     )} ${c.dim(`(${results.length})`)}`,
-    `${c.bold(" Steps      ")} ${join18(
+    `${c.bold(" Steps      ")} ${join19(
       part(t.steps.failed, "failed", c.red),
       part(t.steps.skipped, "skipped", c.dim),
       part(t.steps.passed, "passed", c.green)
     )}`,
-    `${c.bold(" Assertions ")} ${join18(
+    `${c.bold(" Assertions ")} ${join19(
       part(t.assertions.failed, "failed", c.red),
       part(t.assertions.passed, "passed", c.green)
     )}`
@@ -3030,7 +3033,7 @@ var esc = (s) => String(s).replace(
   /[<>&"']|[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g,
   (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;", "'": "&apos;" })[c] ?? ""
 );
-var leafSteps = (steps) => steps.flatMap((s) => s.children?.length ? leafSteps(s.children) : [s]);
+var leafSteps = (steps3) => steps3.flatMap((s) => s.children?.length ? leafSteps(s.children) : [s]);
 function toJUnit(results, o = {}) {
   const suites = results.map((r) => {
     const flat = leafSteps(r.steps);
@@ -3225,6 +3228,31 @@ function buildUrl(base, req) {
   return `${base.replace(/\/+$/, "")}${req.url}${q2 ? `?${q2}` : ""}`;
 }
 var DEFAULT_TIMEOUT_MS = 3e4;
+var WHY = {
+  ECONNREFUSED: "connection refused",
+  ENOTFOUND: "host not found",
+  EAI_AGAIN: "host not found",
+  ECONNRESET: "connection reset",
+  ETIMEDOUT: "connection timed out",
+  UND_ERR_CONNECT_TIMEOUT: "connection timed out",
+  EHOSTUNREACH: "host unreachable",
+  ENETUNREACH: "network unreachable"
+};
+function unreachable2(e, url) {
+  const cause = e?.cause;
+  if (!(e instanceof TypeError) || !cause) return e;
+  const code = cause.code ?? cause.errors?.find((x2) => x2.code)?.code;
+  const tls = code && /^CERT_|^ERR_TLS|SELF_SIGNED|UNABLE_TO_VERIFY/.test(code) ? "certificate problem" : "";
+  const own = typeof cause.message === "string" && cause.message.length <= 120 ? cause.message : "";
+  const why = code && WHY[code] || tls || own;
+  if (!why) return e;
+  let host = url;
+  try {
+    host = new URL(url).host;
+  } catch {
+  }
+  return new Error(`Could not reach ${host}: ${why}.`, { cause: e });
+}
 function createFetchTransport(opts) {
   return async (req, signal) => {
     if (signal?.aborted) throw new Error("Stopped before the API answered.");
@@ -3243,8 +3271,9 @@ function createFetchTransport(opts) {
       ctl.abort();
     }, req.timeoutMs) : void 0;
     signal?.addEventListener("abort", () => ctl.abort());
+    const url = buildUrl(opts.baseUrl(req.service), req);
     try {
-      const res = await f2(buildUrl(opts.baseUrl(req.service), req), {
+      const res = await f2(url, {
         method: req.method,
         headers,
         body: body2,
@@ -3268,7 +3297,7 @@ function createFetchTransport(opts) {
     } catch (e) {
       if (timedOut) throw new Error(`Timed out after ${req.timeoutMs}ms: no answer from the API.`);
       if (signal?.aborted) throw new Error("Stopped before the API answered.");
-      throw e;
+      throw unreachable2(e, url);
     } finally {
       if (timer) clearTimeout(timer);
     }
@@ -3318,7 +3347,7 @@ function usesOf(names, layers, from) {
   const out = [];
   for (const name of names) {
     if (isDeferred(name) || isFakerName(name)) continue;
-    const key = name.split(".")[0];
+    const key = rootName(name);
     if (seen.has(key)) continue;
     seen.add(key);
     for (let i = layers.length - 1; i >= 0; i--) {
@@ -3587,7 +3616,7 @@ async function execute(rt2, def, name, flow, kind = "request", noAuth = false) {
   emit(rt2, { type: "step:end", name, status: result.status });
   return { result, response, authResults };
 }
-function summarize(steps) {
+function summarize(steps3) {
   const t = { steps: 0, passed: 0, failed: 0, skipped: 0, assertions: { passed: 0, failed: 0 } };
   const visit = (s) => {
     if (s.children?.length) {
@@ -3600,21 +3629,21 @@ function summarize(steps) {
     else t.failed++;
     for (const a3 of s.assertions) a3.pass ? t.assertions.passed++ : t.assertions.failed++;
   };
-  steps.forEach(visit);
+  steps3.forEach(visit);
   return t;
 }
-function overall(steps) {
+function overall(steps3) {
   const all = [];
   const walk2 = (s) => {
     all.push(s);
     s.children?.forEach(walk2);
   };
-  steps.forEach(walk2);
+  steps3.forEach(walk2);
   if (all.some((s) => s.status === "error")) return "error";
   if (all.some((s) => s.status === "fail")) return "fail";
   return "pass";
 }
-function finish(rt2, kind, meta, steps, startedAt) {
+function finish(rt2, kind, meta, steps3, startedAt) {
   const result = {
     schemaVersion: 1,
     runId: rid(),
@@ -3626,11 +3655,11 @@ function finish(rt2, kind, meta, steps, startedAt) {
     seed: rt2.o.seed,
     usedDrafts: rt2.o.usedDrafts ?? false,
     tags: meta.tags ?? [],
-    status: overall(steps),
+    status: overall(steps3),
     startedAt: new Date(startedAt).toISOString(),
     durationMs: (rt2.o.now?.() ?? now0()) - startedAt,
-    totals: summarize(steps),
-    steps
+    totals: summarize(steps3),
+    steps: steps3
   };
   const masked = maskDeep(result, rt2.mask);
   emit(rt2, { type: "done", result: masked });
@@ -3718,7 +3747,7 @@ async function runSequence(seq, o) {
     kind: "sequence",
     tags: seq.meta.tags
   });
-  const steps = [];
+  const steps3 = [];
   const captured = {};
   const from = {};
   const remember = (values, step) => {
@@ -3729,7 +3758,7 @@ async function runSequence(seq, o) {
   try {
     inputs = resolveControls(seq.meta.inputs ?? {}, o.inputs);
   } catch (e) {
-    steps.push({
+    steps3.push({
       name: "inputs",
       kind: "input",
       status: "error",
@@ -3738,7 +3767,7 @@ async function runSequence(seq, o) {
       error: e.message,
       durationMs: 0
     });
-    return finish(rt2, "sequence", seq.meta, steps, t0);
+    return finish(rt2, "sequence", seq.meta, steps3, t0);
   }
   const vars = o.vars ?? {};
   const ctx = () => ({
@@ -3748,7 +3777,7 @@ async function runSequence(seq, o) {
     env: o.env
   });
   let failed = false;
-  const skip = (name, kind) => steps.push({ name, kind, status: "skipped", assertions: [], captured: {}, durationMs: 0 });
+  const skip = (name, kind) => steps3.push({ name, kind, status: "skipped", assertions: [], captured: {}, durationMs: 0 });
   for (const node of seq.nodes) {
     if (failed && !seq.meta.continueOnFailure) {
       skip(node.name, node.kind === "step" ? "request" : node.kind);
@@ -3767,7 +3796,7 @@ async function runSequence(seq, o) {
           captured,
           from
         });
-        steps.push(...authResults, result);
+        steps3.push(...authResults, result);
         remember(result.captured, node.name);
         if (result.status !== "pass") failed = true;
       } else if (node.kind === "each") {
@@ -3803,7 +3832,7 @@ async function runSequence(seq, o) {
         parent.captured = collected;
         parent.durationMs = (o.now?.() ?? now0()) - p0;
         remember(collected, node.name);
-        steps.push(parent);
+        steps3.push(parent);
         if (parent.status !== "pass") failed = true;
       } else if (node.kind === "input") {
         const controls = node.controls(ctx());
@@ -3812,7 +3841,7 @@ async function runSequence(seq, o) {
         const given = o.onInput ? await o.onInput({ name: node.name, controls: described }) : o.inputs ?? {};
         const values = resolveControls(controls, given);
         inputs = { ...inputs, ...values };
-        steps.push({
+        steps3.push({
           name: node.name,
           kind: "input",
           status: "pass",
@@ -3842,12 +3871,12 @@ async function runSequence(seq, o) {
         s.assertions = a3.results;
         if (s.status === "pass" && a3.results.some((r) => !r.pass)) s.status = "fail";
         emit(rt2, { type: "step:end", name: node.name, status: s.status });
-        steps.push(s);
+        steps3.push(s);
         if (s.status !== "pass") failed = true;
       }
     } catch (e) {
       const isControl = e instanceof ControlError;
-      steps.push({
+      steps3.push({
         name: node.name,
         kind: node.kind === "step" ? "request" : node.kind,
         status: "error",
@@ -3859,7 +3888,7 @@ async function runSequence(seq, o) {
       failed = true;
     }
   }
-  return finish(rt2, "sequence", seq.meta, steps, t0);
+  return finish(rt2, "sequence", seq.meta, steps3, t0);
 }
 
 // ../core/src/runner/suite.ts
@@ -3919,7 +3948,7 @@ function headerLine(h2, colors2) {
 var retryLine = (colors2, title, attempt, allowed) => `  ${colors2.yellow("\u21BB")} retrying ${title} (attempt ${attempt} of ${allowed})
 `;
 function withoutLocations(results) {
-  const strip = (steps) => steps.map((s) => ({
+  const strip = (steps3) => steps3.map((s) => ({
     ...s,
     assertions: s.assertions.map((a3) => ({ ...a3, location: void 0 })),
     ...s.children ? { children: strip(s.children) } : {}
@@ -5472,8 +5501,9 @@ var faker2 = new Proxy({}, {
     return current[key];
   }
 });
-var WHOLE2 = /^\s*\{\{\s*([\w.$-]+)\s*\}\}\s*$/;
-var EMBED2 = /\{\{\s*([\w.$-]+)\s*\}\}/g;
+var NAME2 = String.raw`[\w.$\[\]-]+`;
+var WHOLE2 = new RegExp(String.raw`^\s*\{\{\s*(${NAME2})\s*\}\}\s*$`);
+var EMBED2 = new RegExp(String.raw`\{\{\s*(${NAME2})\s*\}\}`, "g");
 var DEFERRED_NAMESPACES2 = ["secrets", "session"];
 var TemplateError2 = class extends Error {
   constructor(variable) {
@@ -5498,11 +5528,12 @@ function fromFaker2(path) {
   }
   return { found: true, value: typeof cur === "function" ? cur.call(parent) : cur };
 }
+var steps2 = (path) => path.replace(/\[(\d+)\]/g, ".$1").split(".");
 function lookup2(scope, path) {
   if (isFakerName2(path)) return fromFaker2(path);
   let cur = scope;
-  for (const part of path.split(".")) {
-    if (cur !== null && typeof cur === "object" && part in cur) {
+  for (const part of steps2(path)) {
+    if (cur !== null && typeof cur === "object" && Object.hasOwn(cur, part)) {
       cur = cur[part];
     } else {
       return { found: false };
@@ -6143,7 +6174,7 @@ async function writeEnvKey(file, key, value) {
   await writeFile3(file, setDotenvKey(current, key, value));
 }
 var IGNORE = ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"];
-var NAME = /\.example\.json$/;
+var NAME22 = /\.example\.json$/;
 async function scanExamples(root, outDir, operations) {
   const examples = {};
   const assets = {};
@@ -6161,7 +6192,7 @@ async function scanExamples(root, outDir, operations) {
     const [svc, , id, file] = relative22(gen, abs).split(sep22);
     if (!operations.has(`${svc}/${id}`)) continue;
     add(`${svc}/${id}`, {
-      name: file.replace(NAME, ""),
+      name: file.replace(NAME22, ""),
       abs,
       source: "generated",
       dir: `${svc}/${id}@generated`
@@ -6175,7 +6206,7 @@ async function scanExamples(root, outDir, operations) {
     const key = `${svc}/${id}`;
     if (!svc || !id || !operations.has(key)) continue;
     add(key, {
-      name: file.replace(NAME, ""),
+      name: file.replace(NAME22, ""),
       abs,
       source: "project",
       dir: `${svc}/${id}@project`
@@ -7757,13 +7788,16 @@ function transportFor(ctx, env, vars) {
     }
   });
 }
-function originsFor(config, env, vars) {
+function originsFor(config, env, vars, basePath = false) {
   if (env === "mock") return {};
   const out = {};
   for (const service of Object.keys(config.services)) {
     try {
       const url = baseUrlFor(config, service, env, vars);
-      if (url) out[service] = new URL(url).origin;
+      if (url) {
+        const u = new URL(url);
+        out[service] = basePath ? `${u.origin}${u.pathname.replace(/\/+$/, "")}` : u.origin;
+      }
     } catch {
     }
   }
@@ -7844,6 +7878,7 @@ async function execute2(ctx, o, picked, specs, fileVars, secrets) {
   const vars = environmentScope(config, o.env, { ...fileVars, ...given });
   const transport = transportFor(ctx, o.env, vars);
   const origins = originsFor(config, o.env, vars);
+  const addresses = originsFor(config, o.env, vars, true);
   const faker3 = await ctx.loadFaker();
   const git2 = { ...ctx.git ?? gitInfo(ctx.root) };
   const ci = detectCi(process.env);
@@ -7862,7 +7897,7 @@ async function execute2(ctx, o, picked, specs, fileVars, secrets) {
     colors: colors2,
     quiet: o.quiet,
     trace: o.trace,
-    origins,
+    origins: addresses,
     cwd: ctx.root,
     readSource,
     rerun: (r) => `${ctx.command}${r.file && ctx.command === "specbook test" ? ` ${r.file}` : ""} --env ${o.env} --grep ${quote3(escapeRegExp(r.title))}${o.safe ? " --safe" : ""}`
@@ -7971,7 +8006,7 @@ async function execute2(ctx, o, picked, specs, fileVars, secrets) {
         toJUnit(clean, {
           timestamp: meta.startedAt,
           hostname: hostname(),
-          origins,
+          origins: addresses,
           properties: { env: o.env, sha: git2.sha, branch: git2.branch, specbook: meta.specbook }
         })
       );
@@ -8279,7 +8314,7 @@ async function bundleCommand(project, loader, o) {
 ${e instanceof Error ? e.message : e}`
     );
     console.error(
-      "A package that cannot be compiled in (a native addon, a computed require) can stay an import: --external <package>."
+      "A package that cannot be compiled in (a native addon, a computed require) can stay an import: --external <package>. A browser cannot load it, so replace it with fetch or plain code if the request must also run in the portal."
     );
     return 2;
   }
@@ -8432,9 +8467,9 @@ async function checkCommand(project, loader) {
       ...def.dataPatches
     ]);
     const init2 = new Set(Object.keys(def.input.init ?? {}));
-    const roots = new Set([...used2].map((n) => n.split(".")[0]));
+    const roots = new Set([...used2].map(rootName));
     for (const name of used2) {
-      const root = name.split(".")[0];
+      const root = rootName(name);
       if (name.startsWith("secrets.")) {
         if (!declared.has(name.slice(8)))
           warnings.push(`[${rel2}] secret "${name.slice(8)}" is not declared in config.secrets`);
@@ -8468,15 +8503,124 @@ async function generateCommand(project, loader, only) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync9 } from "fs";
+import { existsSync as existsSync10 } from "fs";
+import { mkdir as mkdir8, readFile as readFile16, writeFile as writeFile9 } from "fs/promises";
+import { join as join15 } from "path";
+
+// src/commands/agents.ts
+import { existsSync as existsSync9, realpathSync } from "fs";
 import { mkdir as mkdir7, readFile as readFile15, writeFile as writeFile8 } from "fs/promises";
 import { join as join14 } from "path";
-async function initCommand(cwd) {
+import { fileURLToPath as fileURLToPath2 } from "url";
+var FILES = ["AGENTS.md", "CLAUDE.md"];
+var START = "<!-- specbook:start";
+var END = "<!-- specbook:end -->";
+function agentBlock(eol = "\n") {
+  return [
+    `${START} (written by specbook init; \`specbook init --agents\` refreshes it) -->`,
+    "## Specbook",
+    "",
+    "This project uses Specbook: requests (`requests/**/*.req.ts`) and flows (`sequences/**/*.seq.ts`) built from OpenAPI specs run as",
+    "the docs, as tests and as monitors. Before adding or changing one, read `.specbook/agent-guide.md`. In short:",
+    "",
+    "- Import operations from `#api/<service>`. Never edit `.generated/`.",
+    "- Label every `assert`, and use `capture` to pass values between steps.",
+    "- Write isomorphic code: requests and flows also run in the browser, so no Node built-ins, `Buffer` or `process.env`.",
+    "- Run `npx specbook check` and `npx specbook test` before you finish.",
+    END
+  ].join(eol);
+}
+function withBlock(text) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const block = agentBlock(eol);
+  const start = text.indexOf(START);
+  if (start >= 0) {
+    const end = text.indexOf(END, start);
+    if (end < 0) return { text, status: "unterminated" };
+    const next = text.slice(0, start) + block + text.slice(end + END.length);
+    return { text: next, status: next === text ? "unchanged" : "updated" };
+  }
+  if (!text.trim()) return { text: `${block}${eol}`, status: "added" };
+  const lead = text.endsWith("\n") ? "" : eol;
+  return { text: `${text}${lead}${eol}${block}${eol}`, status: "added" };
+}
+var importsAgents = (text) => /^@AGENTS\.md\b/m.test(text);
+async function readGuide() {
+  for (const rel2 of ["../agent-guide.md", "../../agent-guide.md"])
+    try {
+      return await readFile15(fileURLToPath2(new URL(rel2, import.meta.url)), "utf8");
+    } catch {
+    }
+  throw new Error("agent-guide.md is missing from the @specbook/cli package");
+}
+async function agentsStep(cwd, agents) {
+  if (agents === false) return;
   const dir = join14(cwd, ".specbook");
   await mkdir7(dir, { recursive: true });
-  const cfg = join14(dir, "specbook.config.ts");
-  if (!existsSync9(cfg)) {
+  const guide = await readGuide();
+  await writeFile8(
+    join14(dir, "agent-guide.md"),
+    `<!-- Written by specbook init v${cliVersion()}. Re-run \`specbook init\` to refresh it, and put project rules in AGENTS.md. -->
+
+${guide}`
+  );
+  console.log("\u2713 wrote .specbook/agent-guide.md");
+  const seen = /* @__PURE__ */ new Set();
+  const found = [];
+  for (const f2 of FILES) {
+    if (!existsSync9(join14(cwd, f2))) continue;
+    const real = realpathSync(join14(cwd, f2));
+    if (seen.has(real)) continue;
+    seen.add(real);
+    found.push(f2);
+  }
+  if (found.length === 0) {
     await writeFile8(
+      join14(cwd, "AGENTS.md"),
+      `# AGENTS.md
+
+Instructions for AI coding agents working in this repository.
+
+${agentBlock()}
+`
+    );
+    console.log("\u2713 created AGENTS.md (read by Claude Code, Codex and other coding agents)");
+    return;
+  }
+  if (!agents) {
+    console.log(
+      `${found.join(" and ")} already ${found.length > 1 ? "exist" : "exists"} and was not changed. To add Specbook's section to ${found.length > 1 ? "them" : "it"}: specbook init --agents`
+    );
+    return;
+  }
+  for (const file of found) {
+    const path = join14(cwd, file);
+    const text = await readFile15(path, "utf8");
+    if (file === "CLAUDE.md" && found.includes("AGENTS.md") && importsAgents(text)) {
+      console.log("CLAUDE.md imports AGENTS.md: its section covers Claude Code too");
+      continue;
+    }
+    const r = withBlock(text);
+    if (r.status === "unterminated") {
+      console.log(`! ${file} has a "${START}" marker with no end marker; left unchanged`);
+      continue;
+    }
+    if (r.status === "unchanged") {
+      console.log(`${file} already has Specbook's section`);
+      continue;
+    }
+    await writeFile8(path, r.text);
+    console.log(`\u2713 ${r.status === "added" ? "added" : "updated"} Specbook's section in ${file}`);
+  }
+}
+
+// src/commands/init.ts
+async function initCommand(cwd, opts = {}) {
+  const dir = join15(cwd, ".specbook");
+  await mkdir8(dir, { recursive: true });
+  const cfg = join15(dir, "specbook.config.ts");
+  if (!existsSync10(cfg)) {
+    await writeFile9(
       cfg,
       `import { defineConfig } from '@specbook/core'
 
@@ -8495,55 +8639,56 @@ export default defineConfig({
     console.log("\u2713 created .specbook/specbook.config.ts");
   }
   const envDir = await ensureEnvironmentsDir(cwd);
-  const example = join14(envDir, "staging.secrets.env.example");
-  if (!existsSync9(example)) {
-    await writeFile8(
+  const example = join15(envDir, "staging.secrets.env.example");
+  if (!existsSync10(example)) {
+    await writeFile9(
       example,
       "# Copy to staging.secrets.env (gitignored) and fill in. One KEY=value per line.\n# YOUR_API_KEY=\n"
     );
-    await writeFile8(
-      join14(envDir, "staging.env"),
+    await writeFile9(
+      join15(envDir, "staging.env"),
       '# Non-secret variables for the "staging" environment (committed).\n# region=eu-west-1\n'
     );
     console.log("\u2713 created .specbook/environments/ (staging.env, staging.secrets.env.example)");
   }
-  const pkgPath = join14(cwd, "package.json");
-  const pkg = existsSync9(pkgPath) ? JSON.parse(await readFile15(pkgPath, "utf8")) : { name: "my-apis", private: true, type: "module" };
+  const pkgPath = join15(cwd, "package.json");
+  const pkg = existsSync10(pkgPath) ? JSON.parse(await readFile16(pkgPath, "utf8")) : { name: "my-apis", private: true, type: "module" };
   pkg.imports = { ...pkg.imports ?? {}, "#api/*": "./.generated/*/index.ts" };
   pkg.scripts = { ...pkg.scripts ?? {} };
   if (!pkg.scripts.prepare) pkg.scripts.prepare = "specbook generate";
-  await writeFile8(pkgPath, `${JSON.stringify(pkg, null, 2)}
+  await writeFile9(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `);
   console.log('\u2713 added the "#api/*" subpath import and a "prepare" script to package.json');
-  const gi = join14(cwd, ".gitignore");
-  const current = existsSync9(gi) ? await readFile15(gi, "utf8") : "";
+  const gi = join15(cwd, ".gitignore");
+  const current = existsSync10(gi) ? await readFile16(gi, "utf8") : "";
   const missing = [".generated", ".specbook/secrets.local.env"].filter(
     (entry) => !current.split("\n").some((l) => l.trim() === entry)
   );
   if (missing.length) {
-    await writeFile8(
+    await writeFile9(
       gi,
       `${current}${current.endsWith("\n") || !current ? "" : "\n"}${missing.join("\n")}
 `
     );
     console.log(`\u2713 gitignored ${missing.join(", ")}`);
   }
+  await agentsStep(cwd, opts.agents);
 }
 
 // src/commands/preview.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync10, readFileSync as readFileSync2 } from "fs";
-import { mkdir as mkdir8, mkdtemp as mkdtemp2, rm as rm4, symlink, writeFile as writeFile10 } from "fs/promises";
+import { existsSync as existsSync11, readFileSync as readFileSync2 } from "fs";
+import { mkdir as mkdir9, mkdtemp as mkdtemp2, rm as rm4, symlink, writeFile as writeFile11 } from "fs/promises";
 import { createRequire as createRequire6 } from "module";
 import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname8, extname, join as join16, resolve as resolve12 } from "path";
+import { dirname as dirname8, extname, join as join17, resolve as resolve12 } from "path";
 import SwaggerParser4 from "@apidevtools/swagger-parser";
 
 // src/commands/ui.ts
-import { copyFile, cp, readFile as readFile16, stat, writeFile as writeFile9 } from "fs/promises";
+import { copyFile, cp, readFile as readFile17, stat, writeFile as writeFile10 } from "fs/promises";
 import { createRequire as createRequire5 } from "module";
-import { basename as basename5, dirname as dirname7, join as join15, resolve as resolve11, sep as sep8 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { basename as basename5, dirname as dirname7, join as join16, resolve as resolve11, sep as sep8 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import { build, createServer } from "vite";
 function uiRoot() {
   const require2 = createRequire5(import.meta.url);
@@ -8562,10 +8707,10 @@ function enclosingNodeModules(file) {
 }
 function dependencyFolders(root) {
   const found = /* @__PURE__ */ new Set([
-    ...enclosingNodeModules(fileURLToPath2(import.meta.url)),
-    ...enclosingNodeModules(join15(root, "package.json"))
+    ...enclosingNodeModules(fileURLToPath3(import.meta.url)),
+    ...enclosingNodeModules(join16(root, "package.json"))
   ]);
-  for (const from of [join15(root, "package.json"), fileURLToPath2(import.meta.url)]) {
+  for (const from of [join16(root, "package.json"), fileURLToPath3(import.meta.url)]) {
     const require2 = createRequire5(from);
     for (const name of ["vite", "prism-code-editor", "preact", "@preact/signals"]) {
       try {
@@ -8623,7 +8768,7 @@ async function devCommand(project, port = 5173) {
 }
 async function buildCommand(project, outDir, options = {}) {
   const out = resolve11(project.root, outDir);
-  const generated = join15(project.root, project.config.codegen?.outDir ?? ".generated");
+  const generated = join16(project.root, project.config.codegen?.outDir ?? ".generated");
   const operations = options.minimal ? await usedOperationKeys(project, generated) : void 0;
   if (operations && operations.size === 0)
     throw new Error("Nothing to publish: no request or flow imports an operation (see --minimal)");
@@ -8645,25 +8790,25 @@ async function buildCommand(project, outDir, options = {}) {
       }
     }
   });
-  await copyMetadata(join15(generated, "specbook.json"), join15(out, "specbook.json"), operations);
+  await copyMetadata(join16(generated, "specbook.json"), join16(out, "specbook.json"), operations);
 }
 async function copyMetadata(from, to, operations) {
   try {
     if (!operations) return await copyFile(from, to);
-    const meta = JSON.parse(await readFile16(from, "utf8"));
+    const meta = JSON.parse(await readFile17(from, "utf8"));
     for (const [svc, s] of Object.entries(meta.services)) {
       s.operations = Object.fromEntries(
         Object.entries(s.operations).filter(([id]) => operations.has(`${svc}/${id}`))
       );
       if (Object.keys(s.operations).length === 0) delete meta.services[svc];
     }
-    await writeFile9(to, `${JSON.stringify(meta)}
+    await writeFile10(to, `${JSON.stringify(meta)}
 `);
   } catch {
   }
 }
 async function copyViewer(project, outDir, viewerDir = resolve11(uiRoot(), "dist-viewer")) {
-  const has2 = await stat(join15(viewerDir, "index.html")).then(
+  const has2 = await stat(join16(viewerDir, "index.html")).then(
     () => true,
     () => false
   );
@@ -8682,10 +8827,10 @@ var slug3 = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/
 async function link(root, name) {
   try {
     let dir = dirname8(createRequire6(import.meta.url).resolve(name));
-    while (!existsSync10(join16(dir, "package.json")) || JSON.parse(readFileSync2(join16(dir, "package.json"), "utf8")).name !== name)
+    while (!existsSync11(join17(dir, "package.json")) || JSON.parse(readFileSync2(join17(dir, "package.json"), "utf8")).name !== name)
       dir = dirname8(dir);
-    const dest = join16(root, "node_modules", ...name.split("/"));
-    await mkdir8(dirname8(dest), { recursive: true });
+    const dest = join17(root, "node_modules", ...name.split("/"));
+    await mkdir9(dirname8(dest), { recursive: true });
     await symlink(dir, dest, "dir");
   } catch {
   }
@@ -8705,7 +8850,7 @@ async function previewCommand(source, o = {}) {
   const { servers } = openApiServers(api, source);
   const where = servers.length === 0 ? "" : servers.length === 1 && servers[0]?.name === "live" ? `, live calls go to ${servers[0].url}` : `
   Environments: ${servers.map((s) => `${s.name} \u2192 ${s.url}`).join(", ")}`;
-  const root = await mkdtemp2(join16(tmpdir2(), "specbook-preview-"));
+  const root = await mkdtemp2(join17(tmpdir2(), "specbook-preview-"));
   const cleanup = () => rm4(root, { recursive: true, force: true }).catch(() => {
   });
   process.once("SIGINT", () => cleanup().then(() => process.exit(0)));
@@ -8715,9 +8860,9 @@ async function previewCommand(source, o = {}) {
     const res = await fetch(source);
     if (!res.ok) throw new Error(`Could not fetch ${source} (${res.status})`);
     const ext = /ya?ml/.test(extname(new URL(source).pathname)) ? ".yaml" : ".json";
-    specFile = join16(root, `openapi/api${ext}`);
-    await mkdir8(dirname8(specFile), { recursive: true });
-    await writeFile10(specFile, await res.text());
+    specFile = join17(root, `openapi/api${ext}`);
+    await mkdir9(dirname8(specFile), { recursive: true });
+    await writeFile11(specFile, await res.text());
   }
   const {
     auth,
@@ -8750,14 +8895,14 @@ async function previewCommand(source, o = {}) {
       }
     }
   };
-  const configFile = join16(root, ".specbook/specbook.config.ts");
-  await mkdir8(dirname8(configFile), { recursive: true });
-  await writeFile10(configFile, `export default ${JSON.stringify(config, null, 2)}
+  const configFile = join17(root, ".specbook/specbook.config.ts");
+  await mkdir9(dirname8(configFile), { recursive: true });
+  await writeFile11(configFile, `export default ${JSON.stringify(config, null, 2)}
 `);
   await link(root, "@specbook/core");
   await link(root, "@faker-js/faker");
   console.log(`Generating "${title}" \u2026`);
-  const out = await generateToDisk({ spec: specFile, service, outDir: join16(root, ".generated") });
+  const out = await generateToDisk({ spec: specFile, service, outDir: join17(root, ".generated") });
   console.log(`\u2713 ${out.operations.length} operations${where}`);
   const project = { root, configFile, config };
   const server = await devCommand(project, o.port ?? 5173);
@@ -8826,8 +8971,8 @@ import { resolve as resolve15 } from "path";
 
 // src/examples.ts
 import { File } from "buffer";
-import { readFile as readFile17 } from "fs/promises";
-import { basename as basename6, dirname as dirname9, join as join17, resolve as resolve14 } from "path";
+import { readFile as readFile18 } from "fs/promises";
+import { basename as basename6, dirname as dirname9, join as join18, resolve as resolve14 } from "path";
 import fg9 from "fast-glob";
 var IGNORE3 = ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"];
 function exampleLoadersFor(project) {
@@ -8835,9 +8980,9 @@ function exampleLoadersFor(project) {
   const example = async (op, name) => {
     const rel2 = `${op.service}/${op.id}/${name}.example.json`;
     const [custom] = await fg9(`**/${rel2}`, { cwd: project.root, absolute: true, ignore: IGNORE3 });
-    const file = custom ?? join17(outDir, op.service, "examples", op.id, `${name}.example.json`);
+    const file = custom ?? join18(outDir, op.service, "examples", op.id, `${name}.example.json`);
     try {
-      const doc = JSON.parse(await readFile17(file, "utf8"));
+      const doc = JSON.parse(await readFile18(file, "utf8"));
       return { ...doc, source: custom ? "project" : "generated", dir: dirname9(file) };
     } catch {
       return void 0;
@@ -8845,7 +8990,7 @@ function exampleLoadersFor(project) {
   };
   const read = async (path, dir) => {
     const abs = resolve14(dir ?? project.root, path);
-    return new File([await readFile17(abs)], basename6(abs));
+    return new File([await readFile18(abs)], basename6(abs));
   };
   return { example, readFile: read };
 }
@@ -9012,7 +9157,9 @@ function testOptions(values, patterns) {
 // src/bin.ts
 var HELP = `specbook <command>
 
-  init                         scaffold config, #api/* import and the environments folder
+  init                         scaffold config, #api/* import, the environments folder and an agent guide
+      --agents                 add a Specbook section to an existing AGENTS.md or CLAUDE.md (never edited otherwise)
+      --no-agents              skip the agent guide and AGENTS.md
   add <service> --spec <p|url> register an OpenAPI spec in the config and generate it; an address is downloaded to
                                openapi/ and recorded in openapi/sources.json
   add --refresh [service...]   download the recorded addresses again, say what changed and regenerate it
@@ -9028,7 +9175,7 @@ var HELP = `specbook <command>
 ${TEST_HELP}
   bundle [--out <file>]        compile the tests into one .mjs that runs with just node: for CI or ops, no install
       --tag <t>                only the requests and flows with this tag (repeatable)
-      --external <pkg>         leave a package as an import (it must be installed where the file runs; repeatable)
+      --external <pkg>         leave a package as an import (installed where the file runs; a browser cannot load it; repeatable)
   check                        validate specs, generated code drift, imported operations, placeholders and environment files
   secrets [--env <name>]       show where each declared secret resolves from (never values)
       --secrets-file <path>    include a dotenv file, as test would
@@ -9046,6 +9193,8 @@ async function main() {
       out: { type: "string" },
       external: { type: "string", multiple: true },
       "no-open": { type: "boolean" },
+      agents: { type: "boolean" },
+      "no-agents": { type: "boolean" },
       viewer: { type: "boolean" },
       minimal: { type: "boolean" },
       help: { type: "boolean", short: "h" }
@@ -9070,7 +9219,13 @@ async function main() {
     });
   }
   if (cmd === "init") {
-    await initCommand(cwd);
+    if (values.agents && values["no-agents"]) {
+      console.error("init: pass --agents or --no-agents, not both\n");
+      return 3;
+    }
+    await initCommand(cwd, {
+      agents: values["no-agents"] ? false : values.agents ? true : void 0
+    });
     return 0;
   }
   if (!["generate", "test", "bundle", "dev", "build", "add", "check", "secrets"].includes(cmd)) {

package/dist/standalone.js

@@ -164,13 +164,16 @@ function transportFor(ctx, env, vars) {
     }
   });
 }
-function originsFor(config, env, vars) {
+function originsFor(config, env, vars, basePath = false) {
   if (env === "mock") return {};
   const out = {};
   for (const service of Object.keys(config.services)) {
     try {
       const url = baseUrlFor(config, service, env, vars);
-      if (url) out[service] = new URL(url).origin;
+      if (url) {
+        const u = new URL(url);
+        out[service] = basePath ? `${u.origin}${u.pathname.replace(/\/+$/, "")}` : u.origin;
+      }
     } catch {
     }
   }
@@ -251,6 +254,7 @@ async function execute(ctx, o, picked, specs, fileVars, secrets) {
   const vars = environmentScope(config, o.env, { ...fileVars, ...given });
   const transport = transportFor(ctx, o.env, vars);
   const origins = originsFor(config, o.env, vars);
+  const addresses = originsFor(config, o.env, vars, true);
   const faker = await ctx.loadFaker();
   const git = { ...ctx.git ?? gitInfo(ctx.root) };
   const ci = detectCi(process.env);
@@ -269,7 +273,7 @@ async function execute(ctx, o, picked, specs, fileVars, secrets) {
     colors,
     quiet: o.quiet,
     trace: o.trace,
-    origins,
+    origins: addresses,
     cwd: ctx.root,
     readSource,
     rerun: (r) => `${ctx.command}${r.file && ctx.command === "specbook test" ? ` ${r.file}` : ""} --env ${o.env} --grep ${quote(escapeRegExp(r.title))}${o.safe ? " --safe" : ""}`
@@ -378,7 +382,7 @@ async function execute(ctx, o, picked, specs, fileVars, secrets) {
         toJUnit(clean, {
           timestamp: meta.startedAt,
           hostname: hostname(),
-          origins,
+          origins: addresses,
           properties: { env: o.env, sha: git.sha, branch: git.branch, specbook: meta.specbook }
         })
       );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Specbook command line: init, add, generate, dev, build, test, bundle, check, secrets and preview.",
   "keywords": [
     "specbook",
@@ -32,15 +32,16 @@
   },
   "files": [
     "dist",
+    "agent-guide.md",
     "!**/*.test.*"
   ],
   "dependencies": {
     "@apidevtools/swagger-parser": "10.1.1",
     "@faker-js/faker": "9.3.0",
-    "@specbook/codegen": "0.3.0",
-    "@specbook/core": "0.3.0",
-    "@specbook/ui": "0.3.0",
-    "@specbook/vite": "0.3.0",
+    "@specbook/codegen": "0.4.0",
+    "@specbook/core": "0.4.0",
+    "@specbook/ui": "0.4.0",
+    "@specbook/vite": "0.4.0",
     "fast-glob": "3.3.2",
     "rolldown": "1.2.13",
     "swagger2openapi": "7.0.8",