@intentius/chant 0.124.26 → 0.124.28

package/src/cli/registry.ts

@@ -72,6 +72,16 @@ export interface ParsedArgs {
    * unchanged; omitted (undefined, not false) when the flag isn't passed.
    */
   progressJson?: boolean;
+  /**
+   * `--events-json` (#4041) — stream the run's events to stdout, one
+   * `run-event.schema.json` line each (`../../run-event.ts`), on `chant run
+   * <op>`, `chant run --components`, `components promote|rollback|redeploy`,
+   * `components fan-out` and `components pr-plan|pr-apply`. Refused beside
+   * `--progress-json`, which prints the older shapes to the same stdout.
+   */
+  eventsJson?: boolean;
+  /** `chant run events <run> --follow` (#4042) — stream the run's events as they happen, until `run-settle`. */
+  follow?: boolean;
   live: boolean;
   /** `chant migrate --from <name>` (default "github") */
   migrateFrom?: string;
@@ -137,6 +147,8 @@ export interface ParsedArgs {
   namespace?: string;
   /** `chant workspace upgrade --allow-code` (#2550) — run migrations whose body is the template's own code. */
   allowCode?: boolean;
+  /** `chant components promote --allow-skip` (#4030): promote past a step of the member's declared promotion order. */
+  allowSkip?: boolean;
   /** `chant workspace upgrade --source <repo>[#<member>]` (#2551): move the scope to another template. */
   source?: string;
   /** `chant workspace adopt-lineage --tags <glob>` and `hash-index --tags` (#2551): the tags to compare. */
@@ -160,15 +172,21 @@ export interface ParsedArgs {
   verbatim?: boolean;
   /** `chant import --skip-undeclarable` — import what can be declared and warn about the live objects that cannot, instead of failing */
   skipUndeclarable?: boolean;
-  /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */
+  /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands. Also `chant release cut --src <dir>` (#4046): the build root of a project with no components. */
   src?: string;
   /** `--env <name>` — active environment: sets CHANT_ENV so env-aware source
    * re-evaluates for that environment (`build` + `graph`), and drives policy. */
   env?: string;
   /** `chant emulator up --port <container-port>=<host-port>`, repeatable (#3673); a bare `<host-port>` when one emulator is selected. */
   port?: string[];
-  /** `chant emulator up --image <ref>` (#3952): the image to start, when one emulator is selected. */
+  /**
+   * `chant emulator up --image <ref>` (#3952): the image to start, when one
+   * emulator is selected. `chant build --components --generate --image <ref>`
+   * (#4002): the image every generated job runs in.
+   */
   image?: string;
+  /** `chant build --components --generate --before-script <line>`, repeatable (#4002): shell lines every generated job runs before its command. */
+  beforeScript?: string[];
   /** `chant emulator up --network <name>` (#3952): the Docker network each started container joins. */
   network?: string;
   /** `chant emulator up --setting <KEY>=<VALUE>`, repeatable (#3952): an emulator setting such as `FLOCI_<NAME>`, passed as `-e`. */
@@ -434,6 +452,8 @@ export interface ParsedArgs {
   ciAppIdVar?: string;
   /** `chant ci workflow --app-key-secret <NAME>` (#3573): the secret holding that App's private key. */
   ciAppKeySecret?: string;
+  /** `chant ci workflow --runner-key-secret <NAME>` (#4031): the secret holding the runner key the tick signs its tags with. */
+  ciRunnerKeySecret?: string;
   /**
    * `chant workspace records review <id> --by <principal>` (#2670): the
    * reviewer, as the caller names them. Also `chant workspace records new
@@ -460,7 +480,7 @@ export interface ParsedArgs {
   prefix?: string;
   /** `chant workspace records|verify --require attested` (#2547): the provenance level a gate requires. */
   require?: string;
-  /** `chant workspace evidence sign --key` (a runner's Ed25519 PEM) and `signers sign --key` (an ssh private key) (#2553). */
+  /** `chant workspace evidence sign --key` (a runner's Ed25519 PEM) and `signers sign --key` (an ssh private key) (#2553). Also `chant ci tick --key` (#4031): the runner key the tick signs its tags with. */
   key?: string;
   /** `chant workspace evidence sign --check-id <id>` (#2553): the check the evidence is for. */
   checkId?: string;
@@ -541,6 +561,12 @@ export interface ParsedArgs {
   digest?: string;
   /** `chant components release record --release-plan <file>` (ws-055, #2733) — path to a release plan JSON file, persisted content-addressed to `_plans/<digest>.json` on chant/lifecycle and read back through the read contract (`chant workspace status --json`). The plan's own `digest` field supplies `--digest` when it is omitted, and must match it when both are given. Distinct from `--plan` (#2300, below), the Op gate-approval plan digest. */
   releasePlanFile?: string;
+  /** `chant components promote --release <label|digest>` (#4026): deploy under that release, reading the templates its target for `--to` recorded. */
+  release?: string;
+  /** `chant release cut --build <command>` (#4026): the shell command run in the member's directory before each environment's templates are read, with `CHANT_ENV` set to the environment. */
+  buildCommand?: string;
+  /** `chant release compile --artifacts` (#4026, internal): build the artifacts of `--component` instead of compiling the environment. */
+  artifacts?: boolean;
   /** Every `--digest` value, in order (#2602). `chant components promote --digest <component>=<sha256:...>` is repeatable, one per component; the other commands read the single {@link digest}. */
   digests?: string[];
   /** `chant components release record --git-sha <sha>` (#568) — git commit the deploy was built from. */

package/src/cli/run-events.ts

@@ -0,0 +1,54 @@
+/**
+ * `--events-json` (#4041): a command's run-event stream on stdout, one
+ * `run-event.schema.json` line per event, also kept on this host for replay
+ * (#4042, `../run-event-store.ts`). Shared by `chant run`, the
+ * components commands that deploy (promote, rollback, redeploy, fan-out) and
+ * the pull-request loop (pr-plan, pr-apply).
+ */
+
+import { formatError } from "./format";
+import { openRunEventStore, teeLines } from "../run-event-store";
+import { openRunEventStream, resolveRunEventRun, type RunEventStream } from "../run-event-stream";
+import type { RunEventKind } from "../run-event";
+import type { ParsedArgs } from "./registry";
+
+/** Refuse `--events-json` beside `--progress-json`: both print to stdout. Returns true after printing why. */
+export function refusesBothStreams(args: Pick<ParsedArgs, "eventsJson" | "progressJson">): boolean {
+  if (!args.eventsJson || !args.progressJson) return false;
+  console.error(formatError({
+    message: "--events-json and --progress-json both stream to stdout",
+    hint: "Pass one. --events-json prints the run-event stream; --progress-json prints the older progress lines.",
+  }));
+  return true;
+}
+
+/** Refuse `--events-json` beside `--json` where `--json` prints a report to stdout (pr-plan, pr-apply). Returns true after printing why. */
+export function refusesEventsWithJson(args: Pick<ParsedArgs, "eventsJson" | "json">, report: string): boolean {
+  if (!args.eventsJson || !args.json) return false;
+  console.error(formatError({
+    message: "--events-json and --json both stream to stdout",
+    hint: `Pass one. --events-json prints the run-event stream; --json prints ${report}.`,
+  }));
+  return true;
+}
+
+/** Writes one line to stdout. */
+export const stdoutLine = (line: string): void => void process.stdout.write(line);
+
+/**
+ * The run's stream on stdout when `--events-json` was passed, else
+ * undefined. The run is named by `runId` when the caller has one (so a
+ * release record and the stream name the same run), else by the CI run or a
+ * local id.
+ */
+export async function openCliRunEvents(
+  args: Pick<ParsedArgs, "eventsJson">,
+  run: { kind: RunEventKind; name: string; runId?: string; cwd?: string },
+): Promise<RunEventStream | undefined> {
+  if (!args.eventsJson) return undefined;
+  const resolved = await resolveRunEventRun(run);
+  // #4042: the stream is also kept on this host, so `chant run events <run>`
+  // replays it. Only a command that was asked for a stream keeps one.
+  const store = await openRunEventStore(run.cwd ?? process.cwd(), resolved.runId);
+  return openRunEventStream(resolved, teeLines(stdoutLine, store?.write.bind(store))!);
+}

package/src/cli/version.ts

@@ -1,15 +1,5 @@
-import { createRequire } from "node:module";
-
 /**
- * The installed chant's version, read from `@intentius/chant`'s own
- * package.json, or "0.0.0" when it can't be read. The path is the same from
- * `src/cli/` and `dist/cli/`, so it holds whether chant runs from source or
- * from its build.
+ * The installed chant's version. It lives in `../chant-version.ts`, outside
+ * `cli/`, so the Op entry can name it without loading the CLI (#4041).
  */
-export const CHANT_VERSION: string = (() => {
-  try {
-    return (createRequire(import.meta.url)("../../package.json") as { version?: string }).version ?? "0.0.0";
-  } catch {
-    return "0.0.0";
-  }
-})();
+export { CHANT_VERSION } from "../chant-version";

package/src/codegen/docs-in-site.test.ts

@@ -0,0 +1,166 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+
+import { docsPipeline, writeDocsSite } from "./docs";
+import { DOCS_SITE_DEPENDENCIES, findChantDocsSite, rebaseImports, resolveDocsMode } from "./docs-in-site";
+import type { DocsConfig } from "./docs-types";
+
+/**
+ * chant #3993: inside the chant repository a lexicon's docs are a section of
+ * the main Starlight site. These run against a fake repository (a `docs/`
+ * whose package.json is the chant docs package) with one lexicon under it.
+ */
+
+let repo: string;
+let lex: string;
+
+function config(overrides: Partial<DocsConfig> = {}): DocsConfig {
+  return {
+    name: "fixture",
+    displayName: "Fixture",
+    description: "fixture lexicon",
+    distDir: join(lex, "dist"),
+    outDir: join(lex, "docs"),
+    srcDir: join(lex, "src"),
+    basePath: "/chant/lexicons/fixture/",
+    ...overrides,
+  };
+}
+
+function page(name: string, frontmatter: string, body = "Body.\n"): void {
+  mkdirSync(join(lex, "docs", "pages"), { recursive: true });
+  writeFileSync(join(lex, "docs", "pages", name), `---\n${frontmatter}\n---\n\n${body}`);
+}
+
+const section = () => join(repo, "docs", "src", "content", "docs", "lexicons", "fixture");
+
+beforeEach(() => {
+  vi.stubEnv("CHANT_DOCS_MODE", "");
+  vi.stubEnv("CHANT_DOCS_SITE", "");
+  repo = mkdtempSync(join(tmpdir(), "chant-docs-in-site-"));
+  mkdirSync(join(repo, "docs"), { recursive: true });
+  writeFileSync(join(repo, "docs", "package.json"), JSON.stringify({ name: "@intentius/chant-docs" }));
+  writeFileSync(join(repo, "docs", "astro.config.mjs"), "export default {};\n");
+  lex = join(repo, "lexicons", "fixture");
+  mkdirSync(join(lex, "dist"), { recursive: true });
+  mkdirSync(join(lex, "src"), { recursive: true });
+  writeFileSync(
+    join(lex, "dist", "manifest.json"),
+    JSON.stringify({ name: "fixture", version: "0.0.0", intrinsics: [{ name: "ref", description: "a ref" }] }),
+  );
+  writeFileSync(join(lex, "dist", "meta.json"), JSON.stringify({}));
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  rmSync(repo, { recursive: true, force: true });
+});
+
+describe("which mode writeDocsSite runs in", () => {
+  test("a lexicon inside the chant repository goes in-site", () => {
+    expect(findChantDocsSite(lex)).toBe(join(repo, "docs"));
+    expect(resolveDocsMode(config())).toEqual({ mode: "in-site", siteDir: join(repo, "docs") });
+  });
+
+  test("a docs site that is not chant's does not count", () => {
+    writeFileSync(join(repo, "docs", "package.json"), JSON.stringify({ name: "someone-elses-docs" }));
+    expect(findChantDocsSite(lex)).toBeUndefined();
+    expect(resolveDocsMode(config()).mode).toBe("standalone");
+  });
+
+  test("config.mode and CHANT_DOCS_MODE override the detection", () => {
+    expect(resolveDocsMode(config({ mode: "standalone" })).mode).toBe("standalone");
+    vi.stubEnv("CHANT_DOCS_MODE", "standalone");
+    expect(resolveDocsMode(config()).mode).toBe("standalone");
+  });
+
+  test("in-site mode with no main site to write into is an error", () => {
+    rmSync(join(repo, "docs"), { recursive: true });
+    expect(() => resolveDocsMode(config({ mode: "in-site" }))).toThrow(/in-site mode needs the chant docs site/);
+  });
+});
+
+describe("in-site mode", () => {
+  test("writes pages and a sidebar fragment into the main site, and no app files", () => {
+    page("start.mdx", "title: Start\ndiataxis: tutorial");
+    page("secret.mdx", "title: Secret\ndiataxis: reference\nhidden: true");
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+
+    for (const f of ["index.mdx", "start.mdx", "secret.mdx", "intrinsics.mdx", "serialization.mdx"]) {
+      expect(existsSync(join(section(), f)), f).toBe(true);
+    }
+    for (const f of ["package.json", "astro.config.mjs", "tsconfig.json", "src"]) {
+      expect(existsSync(join(lex, "docs", f)), f).toBe(false);
+    }
+
+    const fragment = JSON.parse(readFileSync(join(section(), "_sidebar.json"), "utf-8"));
+    expect(fragment.hidden).toEqual(["lexicons/fixture/secret"]);
+    expect(fragment.group.label).toBe("Fixture");
+    expect(fragment.group.collapsed).toBe(true);
+    expect(fragment.group.items.map((i: { label: string }) => i.label)).toEqual(["Overview", "Tutorials", "Reference"]);
+    expect(fragment.group.items[0]).toEqual({ label: "Overview", slug: "lexicons/fixture" });
+    expect(fragment.group.items[1]).toEqual({
+      label: "Tutorials",
+      collapsed: true,
+      items: [{ label: "Start", slug: "lexicons/fixture/start" }],
+    });
+  });
+
+  test("generated reference tables get the diataxis field their sidebar group names", () => {
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+    expect(readFileSync(join(section(), "intrinsics.mdx"), "utf-8")).toMatch(/^---\n[\s\S]*\ndiataxis: reference\n---/);
+    expect(readFileSync(join(section(), "index.mdx"), "utf-8")).not.toContain("diataxis:");
+  });
+
+  test("a page the pipeline stops emitting is gone after the next run", () => {
+    page("start.mdx", "title: Start\ndiataxis: tutorial");
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+    rmSync(join(lex, "docs", "pages", "start.mdx"));
+    writeDocsSite(cfg, docsPipeline(cfg));
+    expect(existsSync(join(section(), "start.mdx"))).toBe(false);
+  });
+
+  test("a page's import of the app's Diagram component points at the main site's", () => {
+    page("concepts.mdx", "title: Concepts\ndiataxis: explanation", "import Diagram from '../../components/Diagram.astro';\n\n<Diagram name=\"x\" alt=\"x\" />\n");
+    const cfg = config();
+    writeDocsSite(cfg, docsPipeline(cfg));
+    expect(readFileSync(join(section(), "concepts.mdx"), "utf-8")).toContain(
+      "import Diagram from '../../../../components/Diagram.astro';",
+    );
+  });
+});
+
+describe("rebaseImports", () => {
+  test("re-points relative imports and leaves code fences and packages alone", () => {
+    const outDir = "/r/lexicons/x/docs";
+    const pageDir = "/r/docs/src/content/docs/lexicons/x";
+    const src = [
+      "import { Aside } from '@astrojs/starlight/components';",
+      "import raw from '../../../../examples/a.ts?raw';",
+      "```ts",
+      "import { y } from '../src/y';",
+      "```",
+    ].join("\n");
+    expect(rebaseImports(src, { outDir, siteDir: "/r/docs", pageDir }).split("\n")).toEqual([
+      "import { Aside } from '@astrojs/starlight/components';",
+      "import raw from '../../../../../../lexicons/x/examples/a.ts?raw';",
+      "```ts",
+      "import { y } from '../src/y';",
+      "```",
+    ]);
+  });
+});
+
+describe("standalone docs app pins", () => {
+  test("match the main docs site's Starlight and Astro", () => {
+    const docsPkg = JSON.parse(readFileSync(join(import.meta.dirname, "..", "..", "..", "..", "docs", "package.json"), "utf-8"));
+    for (const dep of ["@astrojs/starlight", "astro", "sharp"]) {
+      expect(DOCS_SITE_DEPENDENCIES[dep], dep).toBe(docsPkg.dependencies[dep]);
+    }
+  });
+});

package/src/codegen/docs-in-site.ts

@@ -0,0 +1,182 @@
+/**
+ * The in-site mode of the lexicon docs pipeline (chant #3993).
+ *
+ * Inside the chant repository every lexicon's docs are a section of the main
+ * Starlight site in `docs/`: one Astro build, one search index, one design.
+ * `writeDocsSite` writes a lexicon's pages to
+ * `docs/src/content/docs/lexicons/<name>/` and, beside them, `_sidebar.json`,
+ * the lexicon's collapsed sidebar group with its Diátaxis subgroups. The main
+ * site's `astro.config.mjs` reads every fragment through
+ * `docs/src/lexicon-sidebar.mjs`. Nothing else is written: no package.json, no
+ * Astro config, no components.
+ *
+ * Outside the repository (a third-party lexicon, a project scaffolded by
+ * `chant init-lexicon`) the pipeline keeps writing a standalone Starlight app
+ * into the lexicon's own `docs/`, as it always has.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, join, relative, resolve, sep } from "path";
+
+import { QUADRANT_LABELS, QUADRANTS } from "./docs-pages";
+import { quadrantItems } from "./docs-sidebar";
+import type { DocsConfig, DocsResult, Quadrant, SidebarPage } from "./docs-types";
+
+export type DocsSiteMode = "in-site" | "standalone";
+
+/**
+ * The dependencies a standalone lexicon docs app installs. They match
+ * `docs/package.json`, so a lexicon built on its own renders with the same
+ * Starlight and Astro as the main site; a test holds the two together.
+ */
+export const DOCS_SITE_DEPENDENCIES: Readonly<Record<string, string>> = {
+  "@astrojs/starlight": "^0.37.6",
+  astro: "5.6.1",
+  sharp: "^0.34.2",
+};
+
+/** Package name of the main docs site, `docs/package.json` in the chant repository. */
+const CHANT_DOCS_PACKAGE = "@intentius/chant-docs";
+
+/**
+ * The chant repository's main docs site (`<repo>/docs`) above `start`, or
+ * undefined. A directory qualifies when its `docs/package.json` is the chant
+ * docs package and `docs/astro.config.mjs` exists beside it, so a third-party
+ * repository with a docs site of its own is never mistaken for chant.
+ */
+export function findChantDocsSite(start: string): string | undefined {
+  let dir = resolve(start);
+  for (;;) {
+    const docs = join(dir, "docs");
+    const pkg = join(docs, "package.json");
+    if (existsSync(pkg) && existsSync(join(docs, "astro.config.mjs"))) {
+      try {
+        if ((JSON.parse(readFileSync(pkg, "utf-8")) as { name?: unknown }).name === CHANT_DOCS_PACKAGE) return docs;
+      } catch {
+        // Not JSON: not chant's docs site. Keep walking.
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * Which mode `writeDocsSite` runs in, and the main site's directory for
+ * in-site mode. `config.mode` wins, then `CHANT_DOCS_MODE`; with neither, a
+ * lexicon inside the chant repository goes in-site and any other standalone.
+ * `config.siteDir` or `CHANT_DOCS_SITE` names the main site when the walk up
+ * from `outDir` would not find it.
+ */
+export function resolveDocsMode(config: DocsConfig): { mode: DocsSiteMode; siteDir?: string } {
+  const env = process.env.CHANT_DOCS_MODE;
+  const requested = config.mode ?? (env === "in-site" || env === "standalone" ? env : undefined);
+  if (requested === "standalone") return { mode: "standalone" };
+  const siteDir = config.siteDir || process.env.CHANT_DOCS_SITE || findChantDocsSite(config.outDir);
+  if (requested === "in-site") {
+    if (!siteDir) {
+      throw new Error(
+        `[docs:${config.name}] in-site mode needs the chant docs site: none above ${resolve(config.outDir)}. ` +
+          `Set siteDir or CHANT_DOCS_SITE, or use standalone mode.`,
+      );
+    }
+    return { mode: "in-site", siteDir: resolve(siteDir) };
+  }
+  return siteDir ? { mode: "in-site", siteDir: resolve(siteDir) } : { mode: "standalone" };
+}
+
+/** Where a lexicon's section lives inside the main site's content collection. */
+export function sectionContentDir(siteDir: string, name: string): string {
+  return join(siteDir, "src", "content", "docs", "lexicons", name);
+}
+
+/**
+ * The lexicon's sidebar group for the main site: the lexicon's display name,
+ * collapsed, holding its overview and one collapsed group per non-empty
+ * Diátaxis quadrant. Slugs are prefixed with `lexicons/<name>/`.
+ */
+export function buildSectionGroup(config: DocsConfig, result: DocsResult): Record<string, unknown> {
+  const prefix = `lexicons/${config.name}`;
+  const byQuadrant = new Map<Quadrant, SidebarPage[]>();
+  for (const page of result.sidebarPages) {
+    if (page.hidden) continue;
+    const list = byQuadrant.get(page.quadrant) ?? [];
+    list.push({ ...page, slug: `${prefix}/${page.slug}` });
+    byQuadrant.set(page.quadrant, list);
+  }
+  const items: Array<Record<string, unknown>> = [{ label: "Overview", slug: prefix }];
+  for (const q of QUADRANTS) {
+    const pages = byQuadrant.get(q);
+    if (!pages || pages.length === 0) continue;
+    items.push({ label: QUADRANT_LABELS[q], collapsed: true, items: collapseGroups(quadrantItems(pages)) });
+  }
+  return { label: config.displayName, collapsed: true, items };
+}
+
+/** Every nested group starts collapsed, as on the rest of the main site. */
+function collapseGroups(items: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
+  return items.map((item) =>
+    Array.isArray(item.items)
+      ? { label: item.label, collapsed: true, items: collapseGroups(item.items as Array<Record<string, unknown>>) }
+      : item,
+  );
+}
+
+/** Slugs of pages written but kept out of the sidebar, prefixed for the main site. */
+export function hiddenSectionSlugs(config: DocsConfig, result: DocsResult): string[] {
+  const listed = new Set(result.sidebarPages.map((p) => p.slug));
+  return [...result.pages.keys()]
+    .map((f) => f.replace(/\.mdx?$/, ""))
+    .filter((slug) => slug !== "index" && !listed.has(slug))
+    .sort()
+    .map((slug) => `lexicons/${config.name}/${slug}`);
+}
+
+/**
+ * Give a page the `diataxis` field of the quadrant the sidebar files it under,
+ * when it has none. Authored pages always carry one; the generated reference
+ * tables do not, and the main site's Diátaxis check reads the field.
+ */
+export function withQuadrant(content: string, quadrant: Quadrant | undefined): string {
+  if (!quadrant || !content.startsWith("---\n")) return content;
+  const end = content.indexOf("\n---", 4);
+  if (end === -1) return content;
+  if (/^diataxis:/m.test(content.slice(4, end))) return content;
+  return `${content.slice(0, end)}\ndiataxis: ${quadrant}${content.slice(end)}`;
+}
+
+const IMPORT_RE = /^(\s*import\s[^'"]*?\sfrom\s+|\s*import\s+)(['"])(\.\.?\/[^'"]+)\2(.*)$/;
+
+/**
+ * Re-point a page's relative ESM imports from where the standalone app kept
+ * the page (`<outDir>/src/content/docs/`) to where the main site keeps it.
+ * An import of the app's own components (`<outDir>/src/components/X`) goes to
+ * the main site's `src/components/X`, which holds the one shared copy.
+ * Fenced code blocks are left alone; their `import` lines are examples.
+ */
+export function rebaseImports(content: string, opts: { outDir: string; siteDir: string; pageDir: string }): string {
+  const fromDir = join(resolve(opts.outDir), "src", "content", "docs");
+  const appComponents = join(resolve(opts.outDir), "src", "components") + sep;
+  const siteComponents = join(opts.siteDir, "src", "components");
+  let fence: string | null = null;
+  return content
+    .split("\n")
+    .map((line) => {
+      const marker = line.match(/^\s*(`{3,}|~{3,})/)?.[1];
+      if (marker) {
+        if (fence === null) fence = marker[0];
+        else if (marker[0] === fence) fence = null;
+        return line;
+      }
+      if (fence !== null) return line;
+      const m = line.match(IMPORT_RE);
+      if (!m) return line;
+      let target = resolve(fromDir, m[3]);
+      if (target.startsWith(appComponents)) target = join(siteComponents, target.slice(appComponents.length));
+      let spec = relative(opts.pageDir, target).split(sep).join("/");
+      if (!spec.startsWith(".")) spec = `./${spec}`;
+      return `${m[1]}${m[2]}${spec}${m[2]}${m[4]}`;
+    })
+    .join("\n");
+}

package/src/codegen/docs-site/AgentPrompt.astro

@@ -6,14 +6,26 @@
 // render it from their PageTitle override; lexicon sites get a copy of this
 // file from writeDocsSite (docs.ts). The content schema refuses a prompt with
 // no "Never" line. No Starlight import here, so the file works from any site.
+// `text`, `label` and `note` replace the page's prompt and the caption (the
+// main site's home page passes the setup prompt); an `icon` slot goes before
+// the label (the main site passes its logo).
 interface Props {
 	text?: string;
+	label?: string;
+	note?: string;
 }
+const {
+	label = 'Optional: hand this page to your coding agent',
+	note = 'The steps work by hand too.',
+} = Astro.props;
 const prompt = (Astro.props.text ?? Astro.locals.starlightRoute?.entry.data.prompt)?.trim();
 ---
 {prompt && (
 	<figure class="chant-prompt not-content" id="agent-prompt">
-		<figcaption>Optional: hand this page to your coding agent</figcaption>
+		<figcaption>
+			<span class="label"><slot name="icon" />{label}</span>
+			{note && <span class="note">{note}</span>}
+		</figcaption>
 		<details>
 			<summary>
 				<pre class="peek" aria-hidden="true">{prompt}</pre>
@@ -69,11 +81,24 @@ const prompt = (Astro.props.text ?? Astro.locals.starlightRoute?.entry.data.prom
 		--chant-prompt-blue: #60a5fa;
 	}
 	figcaption {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: baseline;
+		gap: 0.25rem 0.75rem;
 		padding: 0.7rem 1rem 0.4rem;
+	}
+	.label {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.5rem;
 		font-size: 0.85rem;
 		font-weight: 600;
 		color: var(--sl-color-white);
 	}
+	.note {
+		font-size: 0.75rem;
+		color: var(--sl-color-gray-3);
+	}
 	summary {
 		display: block;
 		list-style: none;

package/src/codegen/docs-types.ts

@@ -38,8 +38,21 @@ export interface DocsConfig {
   suppressPages?: string[];
   /** Source directory for scanning rule files (defaults to srcDir sibling of distDir) */
   srcDir?: string;
-  /** Base path for the generated Astro site (e.g. '/lexicons/aws/') */
+  /** Base path for the generated Astro site (e.g. '/lexicons/aws/'). Standalone mode only. */
   basePath?: string;
+  /**
+   * Where `writeDocsSite` writes (chant #3993). `in-site`: the lexicon's pages
+   * and sidebar fragment go into the chant repository's main docs site.
+   * `standalone`: a Starlight app of its own in `outDir`. Unset, the
+   * `CHANT_DOCS_MODE` environment variable decides, and without it a lexicon
+   * inside the chant repository goes in-site and any other standalone.
+   */
+  mode?: "in-site" | "standalone";
+  /**
+   * The main docs site (`<chant repo>/docs`) for in-site mode. Defaults to
+   * `CHANT_DOCS_SITE`, then to the first one found walking up from `outDir`.
+   */
+  siteDir?: string;
   /** Root directory for resolving {{file:...}} markers in extra page content */
   examplesDir?: string;
   /**