- );
-}
diff --git a/src/components/HomepageFeatures/styles.module.css b/src/components/HomepageFeatures/styles.module.css
deleted file mode 100644
index 242ddb3..0000000
--- a/src/components/HomepageFeatures/styles.module.css
+++ /dev/null
@@ -1,82 +0,0 @@
-.features {
- width: 100%; /* Ensure the features section spans the full width */
- max-width: 98%;
- margin-top: 20px;
- padding: 0; /* Remove padding around the section */
- display: flex;
- flex-wrap: wrap;
- margin-bottom: 20px;
-}
-
-.feature {
- margin: 8px;
- font-family: "Inter", sans-serif;
- padding: 20px 10px;
- min-height: 250px;
- background: linear-gradient(18deg, rgba(7, 7, 7, 0.325) 52.75%, var(--ifm-color-primary) 180%);
- text-align: left;
- display: flex; /* Added for aligning the title and description horizontally */
- flex-direction: column; /* Stack title and description vertically */
- justify-content: space-evenly;
- border-radius: 8px;
- /* Remove any border that could be causing lines */
- border: none;
- box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1);
-}
-
-.feature h2 {
- margin: 0;
- border: none;
- letter-spacing: 0.35px;
- font-size: 1.8rem;
-}
-
-.description {
- font-size: 1rem;
- padding: 20px;
- padding-bottom: 10px;
-}
-
-.row {
- display: flex;
- width: 100%; /* Ensures the row spans the full width */
- margin: 0; /* Eliminate space between rows */
-}
-
-.features .col {
- margin: 0;
- padding: 0;
-}
-
-@media (min-width: 768px) { /* Adjust breakpoint as necessary */
- .col--6 {
- padding: 0;
- }
-}
-
-.buttons {
- text-align: right; /* Aligns the button to the right */
-}
-
-.button {
- margin-right: 14px;
-}
-
-.heading {
- padding-left: 20px;
- display: flex;
- align-items: center;
-}
-
-.icon {
- background: rgba(239, 71, 121, .3);
- padding: 20px;
- margin-right: 20px;
- border-radius: 5px;
- font-size: 1.8rem;
- display: block;
- /* Remove any border or outline that might be causing lines */
- border: none;
- outline: none;
- box-shadow: none;
-}
\ No newline at end of file
diff --git a/src/components/NotFoundContent/index.tsx b/src/components/NotFoundContent/index.tsx
deleted file mode 100644
index 9c8dc1e..0000000
--- a/src/components/NotFoundContent/index.tsx
+++ /dev/null
@@ -1,65 +0,0 @@
-import React from "react";
-import Link from "@docusaurus/Link";
-import styles from "./styles.module.css";
-
-const SUGGESTIONS: Array<{ label: string; description: string; to: string }> = [
- {
- label: "Get Started",
- description: "Install Suites and write your first test.",
- to: "/docs/get-started/",
- },
- {
- label: "Quickstart",
- description: "A minimal end-to-end example.",
- to: "/docs/get-started/quickstart",
- },
- {
- label: "Guides",
- description: "Solitary, sociable, test doubles, and fundamentals.",
- to: "/docs/guides/",
- },
- {
- label: "API Reference",
- description: "TestBed, Mock, and configuration APIs.",
- to: "/docs/api-reference/",
- },
- {
- label: "Migrating from Automock",
- description: "Move an existing Automock setup to Suites.",
- to: "/docs/migration-guides/from-automock",
- },
-];
-
-export default function NotFoundContent(): React.ReactElement {
- return (
-
-
-
404
-
This page took an early return.
-
- We may have moved or renamed it during the recent docs refresh.
- Try one of these instead:
-
-
-
- {SUGGESTIONS.map((item) => (
-
-
- {item.label}
- {item.description}
-
-
- ))}
-
-
-
- Still stuck? Go to the homepage or{" "}
-
- open an issue on GitHub
-
- .
-
-
-
- );
-}
diff --git a/src/components/NotFoundContent/styles.module.css b/src/components/NotFoundContent/styles.module.css
deleted file mode 100644
index 53d71d9..0000000
--- a/src/components/NotFoundContent/styles.module.css
+++ /dev/null
@@ -1,86 +0,0 @@
-.container {
- display: flex;
- align-items: center;
- justify-content: center;
- padding: 6rem 1.5rem;
- min-height: 60vh;
-}
-
-.inner {
- max-width: 720px;
- width: 100%;
- text-align: left;
-}
-
-.code {
- font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, "Cascadia Mono", monospace;
- font-size: 1rem;
- letter-spacing: 0.15em;
- color: var(--ifm-color-emphasis-600);
- margin-bottom: 1rem;
- text-transform: uppercase;
-}
-
-.title {
- font-size: 2.25rem;
- line-height: 1.2;
- margin: 0 0 1rem;
-}
-
-.subtitle {
- font-size: 1.05rem;
- color: var(--ifm-color-emphasis-700);
- margin-bottom: 2.5rem;
-}
-
-.list {
- list-style: none;
- padding: 0;
- margin: 0 0 2.5rem;
- display: grid;
- grid-template-columns: 1fr;
- gap: 0.75rem;
-}
-
-@media (min-width: 640px) {
- .list {
- grid-template-columns: 1fr 1fr;
- }
-}
-
-.item {
- margin: 0;
-}
-
-.itemLink {
- display: flex;
- flex-direction: column;
- gap: 0.25rem;
- padding: 1rem 1.25rem;
- border: 1px solid var(--ifm-color-emphasis-300);
- border-radius: 0.5rem;
- text-decoration: none;
- color: inherit;
- transition: border-color 0.15s ease, transform 0.15s ease;
-}
-
-.itemLink:hover {
- border-color: var(--ifm-color-primary);
- text-decoration: none;
- transform: translateY(-1px);
-}
-
-.itemLabel {
- font-weight: 600;
- font-size: 1rem;
-}
-
-.itemDescription {
- font-size: 0.9rem;
- color: var(--ifm-color-emphasis-700);
-}
-
-.footer {
- font-size: 0.95rem;
- color: var(--ifm-color-emphasis-700);
-}
diff --git a/src/components/blackbox/BddReverseDemo.astro b/src/components/blackbox/BddReverseDemo.astro
new file mode 100644
index 0000000..a108c4f
--- /dev/null
+++ b/src/components/blackbox/BddReverseDemo.astro
@@ -0,0 +1,203 @@
+---
+import { Code } from 'astro-expressive-code/components';
+
+const sourceTest = `test.system('subscribe-flow', 'alice subscribes to the pro tier', () => {
+ test('alice is an existing user with no active subscription', async ({ request, system }) => {
+ const response = await request.post(\`\${system.bff.hostBaseUrl}/subscriptions\`, {
+ data: { userId: 'alice', paymentMethodId: 'pm_card_visa' },
+ });
+
+ expect(response.status()).toBe(201);
+ });
+});`;
+
+const analyzedTrace = `adapter: playwright
+feature: subscribing to the pro tier
+flow: subscribe-flow
+
+scenario: alice is an existing user with no active subscription
+ when:
+ alice POSTs /subscriptions with a valid card
+ then:
+ response status is 201
+
+grammar:
+ aaa-shape: pass
+ missing-then: pass
+ opaque-step: none`;
+
+const featureFile = `@flow:subscribe-flow
+Feature: subscribing to the pro tier
+
+ Scenario: alice is an existing user with no active subscription
+ When alice POSTs /subscriptions with a valid card
+ Then the response status is 201`;
+
+const gateOutput = `$ pnpm exec blackbox features check --features ./features --tests ./e2e/tests
+syntax: 1/1 .feature files parsed cleanly.
+drift: no drift detected.
+
+$ pnpm exec blackbox features lint ./e2e/tests --fail-on error
+no lint findings`;
+---
+
+
+
+
+ Test to Feature REPL
+
Future package-backed REPL flow: load a test, analyze the AAA/Given-When-Then shape, emit Gherkin, then run the gates.
+
+
+
+
+
+
+
+
+
+
+
+
Source Test
+
The input can be a plain Playwright-style system test or a Blackbox BDD-DSL test. Plain tests are decompiled best-effort; DSL-authored tests preserve more intent.
+
+
+
+
+
Analyzed Behavior Trace
+
The analyzer turns test structure into a behavior trace. The linter checks that the trace has a valid AAA shape: `Given*`, `When+`, `Then+`.
+
+
+
+
+
Generated Gherkin
+
The feature file is a readable projection from the test source. It is useful for review, but it is still checked against the source instead of trusted as disconnected prose.
+
+
+
+
+
Verification Gate
+
The gate is two-part: Cucumber-compatible Gherkin syntax validation, plus feature-file drift detection against the test source. Runtime effects and observation comparison can add stronger gates later.
+
+
+
+
+
+
+
+
diff --git a/src/components/blackbox/BlackboxDemo.astro b/src/components/blackbox/BlackboxDemo.astro
new file mode 100644
index 0000000..3d1812d
--- /dev/null
+++ b/src/components/blackbox/BlackboxDemo.astro
@@ -0,0 +1,305 @@
+---
+// Front-page Blackbox demo simulation. Lives as a real Astro component
+// because MDX otherwise tries to parse the `{...}` JS object literals in the
+// script body as MDX expressions, which throws acorn errors.
+//
+// Behavior: click to start, auto-advances through states with a setTimeout
+// loop, respects prefers-reduced-motion, no GIFs or images. Five states,
+// four transitions: idle, executing, spans captured, feature file revealed,
+// forbids-on-physical-absence demo.
+---
+
+
+
+
+
+ State 0 of 4. Idle.
+
+
+
+ Playwright test (authored once)
+
{`scenario('subscribe-flow', 'subscribing as a pro tier user', ({ given }) => {
+ given('alice is an existing user', async ({ system, capture, when }) => {
+ await when('alice POSTs /subscriptions', async ({ then }) => {
+ await then('the captured effects satisfy the subscribe-flow catalog entry', async () => {
+ await expect(capture).toMatchCatalog();
+ });
+ });
+ });
+});`}
+
+
+ Generated feature file (regenerates every run)
+
{`# the file is generated; run the simulation to see it appear`}
+
+
+
+
Idle. Press Run.
+
The Playwright test executes. The bff, order-service, postgres, redis, and SQS containers receive real requests.
+
Blackbox observes the OpenTelemetry spans the run emits at the boundary.
+
The generated subscribe-flow.feature appears. Every line is backed by a captured effect.
+
The ghost-user path returns 404. The forbids clauses pass because the Stripe and SQS spans are physically not there.
+
+
+
+
+
+
diff --git a/src/components/blackbox/OverviewDiagram.astro b/src/components/blackbox/OverviewDiagram.astro
new file mode 100644
index 0000000..44420ec
--- /dev/null
+++ b/src/components/blackbox/OverviewDiagram.astro
@@ -0,0 +1,345 @@
+---
+interface Props {
+ kind: 'workflow' | 'fit' | 'coverage' | 'blind-spot' | 'quickstart' | 'proof-loop';
+}
+
+const { kind } = Astro.props;
+---
+
+{kind === 'proof-loop' && (
+
+
+ The combined workflow is stronger than any artifact alone: tests keep behavior executable, effects make runtime proof reviewable, and feature files give humans and agents a readable behavior surface.
+
+)}
+
+{kind === 'blind-spot' && (
+
+
+ Normal E2E assertions usually see the outside of the workflow. Blackbox adds a review surface for the required, forbidden, and missing effects that explain whether the workflow really behaved correctly.
+
+)}
+
+{kind === 'workflow' && (
+
+
+ Blackbox starts with the test run you already trust, then turns the observed behavior into evidence, effect coverage, behavior artifacts, and gates that can be reviewed in CI.
+
+)}
+
+{kind === 'fit' && (
+
+
+ Start with controlled system tests when you need a deterministic merge gate. Use broader E2E runs when the goal is full-journey evidence and you can tolerate more environmental noise.
+
+)}
+
+{kind === 'coverage' && (
+
+
+ System-test effect coverage does not replace the assertion or the coverage report. It adds the missing behavior view: which required, forbidden, and decision-sensitive effects appeared in the run.
+
+)}
+
+{kind === 'quickstart' && (
+
+
+ The first run is not finished when the endpoint returns 201. It is finished when the evidence, effect contract, reports, and optional readable spec can be inspected together.
+
+)}
+
+
diff --git a/src/components/blackbox/QuickstartTrackDiagram.astro b/src/components/blackbox/QuickstartTrackDiagram.astro
new file mode 100644
index 0000000..30039fe
--- /dev/null
+++ b/src/components/blackbox/QuickstartTrackDiagram.astro
@@ -0,0 +1,175 @@
+---
+interface Props {
+ kind: 'existing' | 'new-test' | 'specs';
+}
+
+const { kind } = Astro.props;
+---
+
+{kind === 'existing' && (
+
+
+ Existing tests already create useful traffic. Blackbox turns that traffic into observed effects, a reviewed effect catalog, and effect coverage on the next run.
+
+)}
+
+{kind === 'new-test' && (
+
+
+ When no useful system tests exist, the showcase is the fastest way to understand the effect proof loop before adding one narrow flow to your own service.
+
+)}
+
+{kind === 'specs' && (
+
+
+ Feature files do not require effect coverage. They need a test source. Effects add runtime proof when the team wants the stronger path.
+
+)}
+
+
diff --git a/src/components/blackbox/QuickstartTracks.astro b/src/components/blackbox/QuickstartTracks.astro
new file mode 100644
index 0000000..9c7f176
--- /dev/null
+++ b/src/components/blackbox/QuickstartTracks.astro
@@ -0,0 +1,648 @@
+---
+import { Code } from 'astro-expressive-code/components';
+import QuickstartTrackDiagram from './QuickstartTrackDiagram.astro';
+
+const existingSteps = [
+ 'Add wrapper',
+ 'Run command',
+ 'Review catalog',
+ 'Tighten catalog',
+ 'Read coverage',
+];
+
+const newSteps = [
+ 'Run showcase',
+ 'Inspect proof',
+ 'Copy test shape',
+ 'Write one flow',
+ 'Read coverage',
+];
+
+const existingTestSnippet = `import { expect, test } from './testbed.js';
+
+test.system('checkout-flow', 'customer completes checkout', () => {
+ test('existing checkout test', async ({ capture, request, system }) => {
+ const response = await request.post(\`\${system.app.hostBaseUrl}/checkout\`, {
+ data: { cartId: 'cart-123', paymentMethodId: 'pm_card_visa' },
+ });
+
+ expect(response.status()).toBe(201);
+
+ await expect(capture).toMatchCatalog();
+ });
+});`;
+
+const showcaseTestSnippet = `import { expect, test } from './testbed.js';
+
+test.system('subscribe-flow', 'subscribing a user to the pro tier', () => {
+ test('alice subscribes', async ({ capture, request, system }) => {
+ const response = await request.post(\`\${system.bff.hostBaseUrl}/subscriptions\`, {
+ data: { userId: 'alice', paymentMethodId: 'pm_card_visa' },
+ });
+
+ expect(response.status()).toBe(201);
+
+ await expect(capture).toMatchCatalog();
+ });
+});`;
+
+const existingCatalogSnippet = `specVersion: "0.1"
+
+checkout-flow:
+ requires:
+ - { boundary: postgres, op: INSERT, key: orders }
+ - { boundary: http, op: POST, key: /payments }
+ - { boundary: sqs, op: SendMessage }`;
+
+const existingReviewedCatalogSnippet = `specVersion: "0.1"
+
+checkout-flow:
+ requires:
+ - { boundary: postgres, op: INSERT, key: orders }
+ forbids:
+ - { boundary: http, op: POST, key: /refunds }`;
+
+const showcaseCatalogSnippet = `specVersion: "0.1"
+
+subscribe-flow:
+ requires:
+ - { boundary: redis, op: GET, key: "user:*:tier" }
+ - { boundary: postgres, op: INSERT, key: subscriptions }
+ - { boundary: sqs, op: SendMessage }
+ forbids:
+ - { boundary: postgres, op: DELETE }
+ - { boundary: http, op: POST, key: /v1/refunds }`;
+
+const existingRunCommand = ``;
+
+const playwrightExampleCommand = `npx playwright test --config ./e2e/playwright.config.ts`;
+
+const showcaseRunCommand = `pnpm test:system`;
+
+const baselineMessage = `toMatchCatalog: no catalog entry for "checkout-flow"; baseline pending.
+Will be written at fixture teardown.`;
+
+const effectCoverageOutput = `effect coverage
+metric value
+catalog entries 1
+satisfied 1 (100%)
+failed 0
+uncovered 0
+
+ entry state runs why
+✓ checkout-flow satisfied 1/1
+written: /coverage.json`;
+
+const showcaseProofArtifacts = `e2e/tests/__effects__/00-baseline-subscribe.system.effects.yaml
+e2e/.blackbox-coverage/coverage.json
+e2e/.blackbox-coverage/omcdc-propagation.md`;
+
+const replayCommand = `pnpm exec blackbox coverage replay --coverage-dir e2e/.blackbox-coverage --out reports`;
+
+const omcdcArtifacts = `e2e/.blackbox-coverage/omcdc-propagation.md
+e2e/.blackbox-coverage/omcdc-propagation.json
+e2e/.blackbox-coverage/omcdc.html`;
+
+const featureCommands = `pnpm exec blackbox features emit ./e2e/tests --out ./e2e/features
+pnpm exec blackbox features check --features ./e2e/features --tests ./e2e/tests`;
+---
+
+
+
+
+ Before you start
+
Install Blackbox first. Then choose the path that matches your repo: an existing system or E2E test, or the Blackbox showcase.
+
+
+ First success
+
One run records effects, one catalog entry is reviewed, and the next run reports a satisfied effect coverage entry.
Track 1: Add Effect Coverage To An Existing System Test
+
Use this path when you already have a system or E2E test that exercises a valuable flow. The first win is not a new suite. It is evidence for behavior your existing test already drives.
+
+
+
+
1Add the Blackbox wrapper and matcher
+
Keep the request and response assertions you already trust. Add the Blackbox system boundary and `toMatchCatalog()` at the end of one valuable flow.
+
+
+
+
+
2Run your normal system-test command
+
Blackbox does not need to replace your runner. Use the command your project already uses; the Playwright command below is only an example.
+
+
+
You should see a baseline-pending message the first time the catalog entry does not exist.
+
+
+
+
+
3Review the effect catalog
+
The first useful artifact is the generated catalog. It starts as observed behavior, not a trusted contract. Review it before committing it.
+
+
+
+
+
4Tighten the catalog to one meaningful contract
+
`toMatchCatalog()` is already the matcher. Your job here is to edit the catalog: keep one required effect that proves useful behavior and add one forbid for behavior that must not happen.
+
+
+
+
+
5Rerun and read effect coverage
+
On the next run, the terminal should show whether the reviewed catalog entry was satisfied, failed, or uncovered.
+
+
That is the first quickstart win: the same flow now proves something about the behavior inside the system, not only its response.
+
+
+
+
+
Track 2: Showcase First
+
Use this path when you do not yet have a useful system test. First learn the proof loop in the Blackbox showcase, then write one narrow flow in your own system.
+
+
+
+
1Run the showcase
+
From the Blackbox showcase repo root, run the system-test script. The subscription flow is intentionally small but effect-rich: Redis, Postgres, HTTP, and SQS all participate.
+
+
+
+
+
2Inspect the proof trail
+
A successful showcase run should produce a catalog and coverage artifacts. Start with these three; spans and V8 payloads are diagnostics for later.
+
+
+
+
+
3Copy the smallest test shape
+
The important shape is `test.system(...)` plus `toMatchCatalog()`. The matcher seeds a baseline when no catalog entry exists, then enforces the reviewed catalog on later runs.
+
+
+
+
+
4Write one narrow flow in your system
+
Pick a flow where input/output success is not enough: checkout, signup, webhook handling, account deletion, refund prevention, or another side-effect-heavy path.
+
The goal is not a broad journey. The goal is one controlled system flow whose effects matter.
+
+
+
+
5Review the catalog and read coverage
+
The first custom catalog begins as observed behavior. Keep the effects that define correctness, add forbids for dangerous behavior, then rerun to see effect coverage.
+
+
+
+
+
+
+
+
+
+
+
diff --git a/src/components/docs/Breadcrumb.astro b/src/components/docs/Breadcrumb.astro
new file mode 100644
index 0000000..601ffe0
--- /dev/null
+++ b/src/components/docs/Breadcrumb.astro
@@ -0,0 +1,54 @@
+---
+/*
+ * Docs breadcrumb. Computes a trail from the slug.
+ *
+ * Shape: Section / Subsection / ... / Current Page
+ *
+ * No "Docs" prefix, no "Home" prefix; both are tautological. The topbar's
+ * `Suites / docs` brand mark already signals "you are in docs", and the active
+ * product tab (Unit / Blackbox) already shows the section root. The breadcrumb
+ * starts at the first slug segment so the first item is always a useful jump.
+ *
+ * Separator is a thin slash character (not an SVG chevron) so it lines up
+ * cleanly with the text baseline at 13px and matches the existing brand-mark
+ * "Suites / docs" pattern in the header.
+ *
+ * Intermediate segments are humanized from the slug (`effect-coverage` -> `Effect coverage`,
+ * only first word capitalised so multi-word labels do not become Title Case).
+ * The final segment uses the page's frontmatter title verbatim so it matches the h1.
+ */
+
+interface Props {
+ slug: string;
+ title?: string;
+}
+
+const { slug, title } = Astro.props;
+
+function humanize(segment: string): string {
+ const decoded = decodeURIComponent(segment).replace(/[-_]/g, ' ');
+ return decoded.charAt(0).toUpperCase() + decoded.slice(1);
+}
+
+const segments = slug.split('/').filter(Boolean);
+const items = segments.map((seg, i) => {
+ const href = '/docs/' + segments.slice(0, i + 1).join('/');
+ const isLast = i === segments.length - 1;
+ const label = isLast && title ? title : humanize(seg);
+ return { label, href, isLast };
+});
+---
+
diff --git a/src/components/docs/LastUpdated.astro b/src/components/docs/LastUpdated.astro
new file mode 100644
index 0000000..e12f771
--- /dev/null
+++ b/src/components/docs/LastUpdated.astro
@@ -0,0 +1,23 @@
+---
+/*
+ * Small "last updated" stamp at the bottom of the article, before the prev/next pager.
+ * Reads an ISO date string from frontmatter. If absent the component renders nothing
+ * (the layout decides whether to call this or skip it).
+ */
+
+interface Props {
+ iso: string;
+}
+
+const { iso } = Astro.props;
+
+function fmt(s: string): string {
+ const d = new Date(s);
+ if (Number.isNaN(d.getTime())) return s;
+ return d.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
+}
+---
+
+ Last updated
+
+
diff --git a/src/components/docs/PageActions.astro b/src/components/docs/PageActions.astro
new file mode 100644
index 0000000..26bd2e4
--- /dev/null
+++ b/src/components/docs/PageActions.astro
@@ -0,0 +1,132 @@
+---
+/*
+ * Docs page-actions cluster.
+ *
+ * Three affordances, dark-mode-first:
+ * 1. Copy Markdown -- copies the page's raw markdown body to the clipboard so
+ * the reader can paste it into an LLM, an issue, or their notes. The body
+ * is rendered as a hidden
+
+
diff --git a/src/components/docs/PrevNext.astro b/src/components/docs/PrevNext.astro
new file mode 100644
index 0000000..2b8d723
--- /dev/null
+++ b/src/components/docs/PrevNext.astro
@@ -0,0 +1,39 @@
+---
+import sidebar, { productFromPath } from '@/config/sidebar';
+
+interface Props {
+ slug: string;
+}
+const { slug } = Astro.props;
+
+const currentHref = `/docs/${slug}`.replace(/\/$/, '');
+const product = productFromPath(`${currentHref}/`);
+const flat = sidebar[product].flatMap((group) => group.items);
+
+const idx = flat.findIndex((item) => item.href.replace(/\/$/, '') === currentHref);
+
+const prev = idx > 0 ? flat[idx - 1] : null;
+const next = idx >= 0 && idx < flat.length - 1 ? flat[idx + 1] : null;
+---
+{(prev || next) && (
+
+)}
diff --git a/src/components/docs/Sidebar.astro b/src/components/docs/Sidebar.astro
new file mode 100644
index 0000000..b2777f2
--- /dev/null
+++ b/src/components/docs/Sidebar.astro
@@ -0,0 +1,46 @@
+---
+import sidebar, { productFromPath } from '@/config/sidebar';
+
+const currentPath = Astro.url.pathname.replace(/\/$/, '') || '/';
+const activeProduct = productFromPath(Astro.url.pathname);
+const groups = sidebar[activeProduct];
+
+function isGroupActive(items: { href: string }[]) {
+ return items.some((item) => {
+ const h = item.href.replace(/\/$/, '');
+ return currentPath === h || currentPath.startsWith(h + '/');
+ });
+}
+---
+
diff --git a/src/components/docs/TOC.astro b/src/components/docs/TOC.astro
new file mode 100644
index 0000000..3a3ed6b
--- /dev/null
+++ b/src/components/docs/TOC.astro
@@ -0,0 +1,90 @@
+---
+interface Heading {
+ depth: number;
+ text: string;
+ slug: string;
+}
+interface Props {
+ headings: Heading[];
+}
+const { headings } = Astro.props;
+const filtered = headings.filter((h) => h.depth >= 2 && h.depth <= 4);
+---
+{filtered.length > 0 && (
+
+ );
+}
diff --git a/src/components/islands/DocSearch.tsx b/src/components/islands/DocSearch.tsx
new file mode 100644
index 0000000..daacf7f
--- /dev/null
+++ b/src/components/islands/DocSearch.tsx
@@ -0,0 +1,136 @@
+import React, { useEffect } from 'react';
+import { DocSearch } from '@docsearch/react';
+import '@docsearch/css';
+import {
+ ALGOLIA_APP_ID,
+ ALGOLIA_API_KEY,
+ ALGOLIA_INDEX_NAME,
+} from '@/lib/algolia';
+
+/*
+ * Algolia DocSearch island.
+ *
+ * Algolia handles the cmd+k / ctrl+k shortcut binding, the platform-aware hint
+ * chip (Mac vs Windows/Linux), modal open/close, focus trap inside the modal,
+ * escape-to-close, focus return to the trigger, recent-searches persistence,
+ * and arrow-key navigation between hits. We do not re-implement those.
+ *
+ * Our job is:
+ * 1. Scope the modal under a stable wrapper so .DocSearch-* overrides in
+ * components.css cannot leak.
+ * 2. Provide a sensible "no results" fallback URL (GitHub issues) so users
+ * have a next step instead of a dead end (ui-ux-pro-max search/no-results).
+ * 3. Localize the placeholder + button text so screen readers announce a
+ * useful label.
+ * 4. Bind the extra "/" shortcut that the button aria-label advertises, since
+ * Algolia only binds cmd+k / ctrl+k natively. We ignore the keypress when
+ * the user is already typing in an input/textarea/contenteditable element.
+ *
+ * Hydration cost: this is the only search island in the header, mounted with
+ * client:only="react". We deliberately do not import additional runtime deps.
+ */
+export default function DocSearchIsland() {
+ // Bind "/" as a global open shortcut. Algolia's button is rendered inside our
+ // wrapper, so we click it to inherit Algolia's own focus + a11y behaviour
+ // (which restores focus to the button on close).
+ useEffect(() => {
+ const isEditable = (el: EventTarget | null): boolean => {
+ if (!(el instanceof HTMLElement)) return false;
+ const tag = el.tagName;
+ if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return true;
+ if (el.isContentEditable) return true;
+ return false;
+ };
+
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (event.key !== '/') return;
+ if (event.defaultPrevented) return;
+ if (event.metaKey || event.ctrlKey || event.altKey) return;
+ if (isEditable(event.target)) return;
+ // If the Algolia modal is already open, do not steal the keystroke.
+ if (document.querySelector('.DocSearch-Modal')) return;
+
+ const trigger = document.querySelector(
+ '.suites-docsearch .DocSearch-Button',
+ );
+ if (!trigger) return;
+ event.preventDefault();
+ trigger.click();
+ };
+
+ window.addEventListener('keydown', onKeyDown);
+ return () => window.removeEventListener('keydown', onKeyDown);
+ }, []);
+
+ return (
+
+
+ `https://github.com/suites-dev/suites/issues/new?title=${encodeURIComponent(
+ `Docs search: no results for "${query}"`,
+ )}&labels=docs`
+ }
+ // Cast: a few translation keys (clearButtonTitle, recentConversationsTitle,
+ // backToSearchText) exist in newer @docsearch/react runtimes but are
+ // not yet present in the installed type definitions. Algolia accepts
+ // them at runtime; the cast lets us ship the strings without dropping
+ // them on the floor or pinning to stale types.
+ translations={{
+ button: {
+ buttonText: 'Search documentation',
+ buttonAriaLabel: 'Search documentation (press / or Cmd K)',
+ },
+ modal: {
+ searchBox: {
+ clearButtonTitle: 'Clear',
+ clearButtonAriaLabel: 'Clear the query',
+ closeButtonText: 'Close',
+ closeButtonAriaLabel: 'Close',
+ placeholderText: 'Search documentation',
+ placeholderTextAskAi: 'Ask AI a question',
+ placeholderTextAskAiStreaming: 'Answering',
+ searchInputLabel: 'Search',
+ backToKeywordSearchButtonText: 'Back to keyword search',
+ backToKeywordSearchButtonAriaLabel: 'Back to keyword search',
+ },
+ startScreen: {
+ recentSearchesTitle: 'Recent',
+ noRecentSearchesText: 'No recent searches',
+ saveRecentSearchButtonTitle: 'Save this search',
+ removeRecentSearchButtonTitle: 'Remove this search from history',
+ favoriteSearchesTitle: 'Favorites',
+ removeFavoriteSearchButtonTitle: 'Remove this search from favorites',
+ recentConversationsTitle: 'Recent conversations',
+ removeRecentConversationButtonTitle: 'Remove conversation from history',
+ },
+ errorScreen: {
+ titleText: 'Unable to fetch results',
+ helpText: 'You might want to check your network connection.',
+ },
+ footer: {
+ selectText: 'to select',
+ selectKeyAriaLabel: 'Enter key',
+ navigateText: 'to navigate',
+ navigateUpKeyAriaLabel: 'Arrow up',
+ navigateDownKeyAriaLabel: 'Arrow down',
+ closeText: 'to close',
+ closeKeyAriaLabel: 'Escape key',
+ backToSearchText: 'Back to search',
+ },
+ noResultsScreen: {
+ noResultsText: 'No results for',
+ suggestedQueryText: 'Try searching for',
+ reportMissingResultsText: 'Believe this query should return results?',
+ reportMissingResultsLinkText: 'Let us know.',
+ },
+ },
+ } as any}
+ />
+
+ );
+}
diff --git a/src/components/islands/GoogleAnalytics.astro b/src/components/islands/GoogleAnalytics.astro
new file mode 100644
index 0000000..485cdb7
--- /dev/null
+++ b/src/components/islands/GoogleAnalytics.astro
@@ -0,0 +1,11 @@
+---
+const GA_ID = 'G-G7FJBNFPJJ';
+---
+
+
diff --git a/src/components/mdx/Aside.astro b/src/components/mdx/Aside.astro
new file mode 100644
index 0000000..66f47a9
--- /dev/null
+++ b/src/components/mdx/Aside.astro
@@ -0,0 +1,50 @@
+---
+interface Props {
+ type?: 'tip' | 'info' | 'note' | 'warning' | 'danger' | 'caution';
+ title?: string;
+}
+const { type = 'info', title } = Astro.props;
+
+const variantMap: Record = {
+ tip: 'success',
+ info: 'info',
+ note: 'info',
+ warning: 'warning',
+ caution: 'warning',
+ danger: 'error',
+};
+
+const symbolMap: Record = {
+ tip: '✓',
+ info: 'i',
+ note: 'i',
+ warning: '!',
+ caution: '!',
+ danger: '×',
+};
+
+// Accessible name announced by screen readers for the note region.
+// Matches the visual variant so users hear the severity even without the icon.
+const labelMap: Record = {
+ info: 'Note',
+ success: 'Tip',
+ warning: 'Warning',
+ error: 'Danger',
+};
+
+const variant = variantMap[type] ?? 'info';
+const symbol = symbolMap[type] ?? 'i';
+const label = labelMap[variant];
+---
+
diff --git a/src/components/mdx/MermaidDiagram.tsx b/src/components/mdx/MermaidDiagram.tsx
new file mode 100644
index 0000000..f9e55e2
--- /dev/null
+++ b/src/components/mdx/MermaidDiagram.tsx
@@ -0,0 +1,135 @@
+import React, { useEffect, useRef, useState } from 'react';
+
+interface MermaidDiagramProps {
+ chart: string;
+ /** Accessible description of what the diagram shows. */
+ alt?: string;
+ /** Optional visible caption rendered below the diagram. */
+ caption?: string;
+}
+
+let mermaidInitialized = false;
+
+function prefersReducedMotion(): boolean {
+ if (typeof window === 'undefined' || !window.matchMedia) return false;
+ return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+export default function MermaidDiagram({ chart, alt, caption }: MermaidDiagramProps) {
+ const containerRef = useRef(null);
+ const [svg, setSvg] = useState('');
+ const [error, setError] = useState('');
+
+ useEffect(() => {
+ let cancelled = false;
+
+ const render = async () => {
+ try {
+ const mermaid = (await import('mermaid')).default;
+
+ if (!mermaidInitialized) {
+ // Dark palette tuned to suites.dev tokens (graphite bg #0F0F12,
+ // brand pink #EF4779, muted #A1A1AA). All foreground colors verified
+ // >= 4.5:1 against the diagram surface.
+ // Reduced-motion users get the linear curve variant so edges don't
+ // animate into Bezier shapes. Other rendering settings are identical.
+ const reduceMotion = prefersReducedMotion();
+ mermaid.initialize({
+ startOnLoad: false,
+ theme: 'base',
+ securityLevel: 'strict',
+ fontFamily:
+ '"ABC Diatype", "Geist", "Inter", ui-sans-serif, system-ui, sans-serif',
+ flowchart: {
+ useMaxWidth: true,
+ htmlLabels: true,
+ curve: reduceMotion ? 'linear' : 'basis',
+ },
+ sequence: { useMaxWidth: true },
+ themeVariables: {
+ background: '#0F0F12',
+ primaryColor: '#1A1A20',
+ primaryTextColor: '#F4F4F5',
+ primaryBorderColor: '#EF4779',
+ secondaryColor: '#131318',
+ tertiaryColor: '#0F0F12',
+ lineColor: '#A1A1AA',
+ textColor: '#F4F4F5',
+ mainBkg: '#1A1A20',
+ nodeBorder: '#EF4779',
+ clusterBkg: '#131318',
+ clusterBorder: 'rgba(255,255,255,0.16)',
+ edgeLabelBackground: '#0F0F12',
+ noteBkgColor: '#131318',
+ noteTextColor: '#F4F4F5',
+ noteBorderColor: 'rgba(255,255,255,0.16)',
+ },
+ });
+ mermaidInitialized = true;
+ }
+
+ const id = `mermaid-${Math.random().toString(36).slice(2)}`;
+ const { svg: rendered } = await mermaid.render(id, chart);
+
+ if (!cancelled) {
+ setSvg(rendered);
+ }
+ } catch (err) {
+ if (!cancelled) {
+ setError(err instanceof Error ? err.message : String(err));
+ }
+ }
+ };
+
+ render();
+
+ return () => {
+ cancelled = true;
+ };
+ }, [chart]);
+
+ // Reserve vertical space while the diagram loads so layout does not jump.
+ // 240px is a reasonable median for the diagrams used in this codebase; the
+ // figure shrinks to fit content once rendered.
+ const placeholderStyle: React.CSSProperties = {
+ minHeight: svg ? undefined : 240,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ };
+
+ if (error) {
+ return (
+
+
diff --git a/src/components/site/ThemeToggle.astro b/src/components/site/ThemeToggle.astro
new file mode 100644
index 0000000..8c1ee3e
--- /dev/null
+++ b/src/components/site/ThemeToggle.astro
@@ -0,0 +1,69 @@
+---
+/*
+ * Theme toggle. Flips between light and dark by setting data-theme on
+ * and persisting to localStorage. The actual theme value is resolved by the
+ * inline script in BaseLayout.astro head; this button just flips and saves.
+ *
+ * Two icons live inside; one is hidden by CSS based on the active theme so
+ * the button always shows the destination state (clicking it produces what
+ * the icon depicts).
+ */
+---
+
+
+
diff --git a/src/components/ui/Alert.astro b/src/components/ui/Alert.astro
new file mode 100644
index 0000000..218417d
--- /dev/null
+++ b/src/components/ui/Alert.astro
@@ -0,0 +1,30 @@
+---
+interface Props {
+ variant: 'info' | 'success' | 'warning' | 'error';
+ title?: string;
+}
+const { variant, title } = Astro.props;
+const symbols: Record = {
+ info: 'i',
+ success: '✓',
+ warning: '!',
+ error: '×',
+};
+const labels: Record = {
+ info: 'Note',
+ success: 'Success',
+ warning: 'Warning',
+ error: 'Error',
+};
+const symbol = symbols[variant] ?? 'i';
+// warning/error are time-sensitive; use role=alert so AT announces immediately.
+// info/success are passive context; role=note keeps them in the page flow.
+const role = variant === 'warning' || variant === 'error' ? 'alert' : 'note';
+---
+
+ )}
+
+
diff --git a/src/components/ui/Shell.astro b/src/components/ui/Shell.astro
new file mode 100644
index 0000000..71d0c49
--- /dev/null
+++ b/src/components/ui/Shell.astro
@@ -0,0 +1,7 @@
+---
+---
+{/* Plain wrapper (not ): BaseLayout already provides the
+ landmark. Keeping a second here violates HTML5 landmark rules. */}
+
+
+
diff --git a/src/components/ui/Topbar.astro b/src/components/ui/Topbar.astro
new file mode 100644
index 0000000..2792d21
--- /dev/null
+++ b/src/components/ui/Topbar.astro
@@ -0,0 +1,8 @@
+---
+---
+
+
+
+
diff --git a/src/config/sidebar.ts b/src/config/sidebar.ts
new file mode 100644
index 0000000..e92340f
--- /dev/null
+++ b/src/config/sidebar.ts
@@ -0,0 +1,221 @@
+export interface SidebarItem {
+ label: string;
+ href: string;
+}
+
+export interface SidebarGroup {
+ label: string;
+ items: SidebarItem[];
+}
+
+export type ProductKey = 'unit' | 'blackbox';
+
+export interface SidebarConfig {
+ unit: SidebarGroup[];
+ blackbox: SidebarGroup[];
+}
+
+// Top-level product tabs. Order in the header matches this order.
+export const products: Array<{ key: ProductKey; label: string; href: string; badge?: string }> = [
+ { key: 'unit', label: 'Unit', href: '/docs/get-started/' },
+ { key: 'blackbox', label: 'Blackbox', href: '/docs/blackbox/overview/what-is-blackbox', badge: 'alpha' },
+];
+
+// Resolve the active product from a URL pathname.
+export function productFromPath(pathname: string): ProductKey {
+ return pathname.startsWith('/docs/blackbox/') ? 'blackbox' : 'unit';
+}
+
+// Labels are taken verbatim from each file's `title:` frontmatter.
+// Items within each section are ordered by `sidebar_position`.
+const sidebar: SidebarConfig = {
+ unit: [
+ {
+ label: 'Get Started',
+ items: [
+ // sidebar_position: 1
+ { label: 'Get Started', href: '/docs/get-started/' },
+ // sidebar_position: 2
+ { label: 'Why Suites?', href: '/docs/get-started/why-suites' },
+ // sidebar_position: 3
+ {
+ label: 'Install Suites for NestJS, Inversify, Jest, Vitest, and Sinon',
+ href: '/docs/get-started/installation',
+ },
+ // sidebar_position: 4
+ {
+ label: 'Suites Quick Start: Write Your First Unit Test in 5 Minutes',
+ href: '/docs/get-started/quickstart',
+ },
+ ],
+ },
+ {
+ label: 'Guides',
+ items: [
+ // sidebar_position: 2 (section index)
+ { label: 'Guides', href: '/docs/guides/' },
+ // sidebar_position: 1
+ { label: 'Unit Testing Fundamentals', href: '/docs/guides/fundamentals' },
+ // sidebar_position: 2
+ {
+ label: 'TypeScript Test Doubles: Auto-Generated Mocks, Stubs, Spies & Fakes',
+ href: '/docs/guides/test-doubles',
+ },
+ // sidebar_position: 3
+ { label: 'Testing in Isolation (Solitary)', href: '/docs/guides/solitary' },
+ // sidebar_position: 4
+ { label: 'Testing Components Together (Sociable)', href: '/docs/guides/sociable' },
+ // sidebar_position: 7
+ { label: 'Virtual Test Container Concept', href: '/docs/guides/virtual-test-container' },
+ ],
+ },
+ {
+ label: 'API Reference',
+ items: [
+ // sidebar_position: 3 (section index)
+ { label: 'API Reference', href: '/docs/api-reference/' },
+ // sidebar_position: 2
+ { label: 'TestBed.solitary()', href: '/docs/api-reference/testbed-solitary' },
+ // sidebar_position: 3
+ { label: 'TestBed.sociable()', href: '/docs/api-reference/testbed-sociable' },
+ // sidebar_position: 4
+ { label: 'Mock Configuration', href: '/docs/api-reference/mock-configuration' },
+ // sidebar_position: 5 (unit-reference)
+ { label: 'UnitReference', href: '/docs/api-reference/unit-reference' },
+ // sidebar_position: 5 (mock)
+ { label: 'mock() and stub()', href: '/docs/api-reference/mock' },
+ // sidebar_position: 6
+ { label: 'Types', href: '/docs/api-reference/types' },
+ ],
+ },
+ {
+ label: 'Migration Guides',
+ items: [
+ // sidebar_position: 5 (section index)
+ { label: 'Migration Guides', href: '/docs/migration-guides/' },
+ // sidebar_position: 5
+ { label: 'Migrating from Automock to Suites', href: '/docs/migration-guides/from-automock' },
+ ],
+ },
+ {
+ label: 'Changelog',
+ items: [
+ // sidebar_position: 6
+ { label: 'Changelog', href: '/docs/changelog' },
+ ],
+ },
+ ],
+
+ // Blackbox sidebar is organized around the first-visit path first,
+ // then concepts, lifecycle, workflows, reference, recovery, trust, use cases, and project info.
+ blackbox: [
+ {
+ label: 'Overview',
+ items: [
+ { label: 'What is Blackbox?', href: '/docs/blackbox/overview/what-is-blackbox' },
+ { label: 'Tests, Effects, and Feature Files', href: '/docs/blackbox/overview/tests-effects-and-feature-files' },
+ { label: 'Where Blackbox Fits', href: '/docs/blackbox/overview/where-blackbox-fits' },
+ { label: 'System Test Effect Coverage', href: '/docs/blackbox/overview/system-test-effect-coverage' },
+ { label: 'When to Use Blackbox', href: '/docs/blackbox/overview/when-to-use-blackbox' },
+ ],
+ },
+ {
+ label: 'Quickstart',
+ items: [
+ { label: 'Requirements and Supported Stacks', href: '/docs/blackbox/quickstart/requirements' },
+ { label: 'Install Blackbox', href: '/docs/blackbox/quickstart/install' },
+ { label: '5-Minute Quickstart', href: '/docs/blackbox/quickstart/first-proven-feature' },
+ { label: 'Feature Files From Tests', href: '/docs/blackbox/quickstart/feature-files-from-tests' },
+ { label: 'Troubleshooting First Run', href: '/docs/blackbox/quickstart/troubleshooting-first-run' },
+ ],
+ },
+ {
+ label: 'Concepts',
+ items: [
+ { label: 'System Effects', href: '/docs/blackbox/concepts/system-effects' },
+ { label: 'Unit, Integration, System, and E2E', href: '/docs/blackbox/concepts/unit-integration-system-e2e-blackbox-testing' },
+ { label: 'Runtime Evidence', href: '/docs/blackbox/concepts/system-tests-and-runtime-evidence' },
+ { label: 'Effects, Runtime, and Specs', href: '/docs/blackbox/concepts/bdd-runtime-and-effects' },
+ { label: 'OMC/DC Coverage', href: '/docs/blackbox/concepts/omc-dc-coverage' },
+ { label: 'Requires and Forbids', href: '/docs/blackbox/concepts/requires-and-forbids' },
+ { label: 'Feature Files, BDD, and Staleness', href: '/docs/blackbox/concepts/feature-files-and-staleness' },
+ ],
+ },
+ {
+ label: 'Lifecycle',
+ items: [
+ { label: 'The Blackbox Lifecycle', href: '/docs/blackbox/lifecycle/the-blackbox-lifecycle' },
+ { label: 'Developer Workflow', href: '/docs/blackbox/lifecycle/developer-workflow' },
+ { label: 'AI-Assisted Workflow', href: '/docs/blackbox/lifecycle/agentic-workflow' },
+ ],
+ },
+ {
+ label: 'Use Cases',
+ items: [
+ { label: 'Covering Before Refactor', href: '/docs/blackbox/use-cases/covering-before-refactor' },
+ { label: 'Legacy Modernization', href: '/docs/blackbox/use-cases/legacy-modernization' },
+ { label: 'Microservices Regression', href: '/docs/blackbox/use-cases/microservices-regression' },
+ { label: 'Incident Regression', href: '/docs/blackbox/use-cases/incident-regression' },
+ { label: 'Spec-Driven Development', href: '/docs/blackbox/use-cases/spec-driven-development' },
+ { label: 'AI-Assisted Development', href: '/docs/blackbox/use-cases/ai-assisted-development' },
+ ],
+ },
+ {
+ label: 'Guides',
+ items: [
+ { label: 'Writing Scenarios', href: '/docs/blackbox/guides/writing-scenarios' },
+ { label: 'Generating Feature Files', href: '/docs/blackbox/guides/generating-feature-files' },
+ { label: 'Reading Coverage Reports', href: '/docs/blackbox/guides/reading-coverage-reports' },
+ { label: 'Run with the Testbed', href: '/docs/blackbox/guides/using-the-testbed' },
+ { label: 'Configure CI Gates', href: '/docs/blackbox/guides/ci-behavioral-gates' },
+ ],
+ },
+ {
+ label: 'CLI and API Reference',
+ items: [
+ { label: 'CLI Reference', href: '/docs/blackbox/reference/cli' },
+ { label: 'API Reference', href: '/docs/blackbox/reference/api' },
+ { label: 'Testbed API', href: '/docs/blackbox/reference/testbed-api' },
+ { label: 'Scenario DSL', href: '/docs/blackbox/reference/scenario-dsl' },
+ { label: 'Matchers and Effect Builders', href: '/docs/blackbox/reference/matchers-and-effect-builders' },
+ { label: 'Catalog Schema', href: '/docs/blackbox/reference/catalog-schema' },
+ { label: 'Report Formats', href: '/docs/blackbox/reference/report-formats' },
+ { label: 'Configuration', href: '/docs/blackbox/reference/configuration' },
+ { label: 'Environment Variables', href: '/docs/blackbox/reference/environment-variables' },
+ { label: 'Files and Artifacts', href: '/docs/blackbox/reference/files-and-artifacts' },
+ { label: 'Exit Codes', href: '/docs/blackbox/reference/exit-codes' },
+ ],
+ },
+ {
+ label: 'Troubleshooting',
+ items: [
+ { label: 'No Spans Captured', href: '/docs/blackbox/troubleshooting/no-spans-captured' },
+ { label: 'Feature Drift', href: '/docs/blackbox/troubleshooting/feature-drift' },
+ { label: 'Catalog Failures', href: '/docs/blackbox/troubleshooting/catalog-failures' },
+ { label: 'Docker and Testbed', href: '/docs/blackbox/troubleshooting/docker-and-testbed' },
+ { label: 'Diagnostics and Debug Logs', href: '/docs/blackbox/troubleshooting/diagnostics-and-debug-logs' },
+ { label: 'Reporting a Bug', href: '/docs/blackbox/troubleshooting/reporting-a-bug' },
+ ],
+ },
+ {
+ label: 'Security and Trust',
+ items: [
+ { label: 'What Blackbox Runs', href: '/docs/blackbox/security-and-trust/what-blackbox-runs' },
+ { label: 'Network Access and Isolation', href: '/docs/blackbox/security-and-trust/network-access-and-isolation' },
+ { label: 'Data and Telemetry', href: '/docs/blackbox/security-and-trust/data-and-telemetry' },
+ { label: 'Secrets and Containers', href: '/docs/blackbox/security-and-trust/secrets-and-containers' },
+ ],
+ },
+ {
+ label: 'Project',
+ items: [
+ { label: 'Examples and Sample Project', href: '/docs/blackbox/project/examples-and-sample-project' },
+ { label: 'Supported Platforms and Integrations', href: '/docs/blackbox/project/supported-platforms-and-integrations' },
+ { label: 'Upgrade and Version Compatibility', href: '/docs/blackbox/project/upgrade-and-version-compatibility' },
+ { label: 'License and Support', href: '/docs/blackbox/project/license-and-support' },
+ ],
+ },
+ ],
+};
+
+export default sidebar;
diff --git a/src/content/config.ts b/src/content/config.ts
new file mode 100644
index 0000000..0e9d05a
--- /dev/null
+++ b/src/content/config.ts
@@ -0,0 +1,49 @@
+import { defineCollection, z } from 'astro:content';
+
+/*
+ * Docs content collection schema.
+ *
+ * Prisma's docs pattern, applied: every page is the same page. The frontmatter
+ * contract below is the single source of truth for what a docs page is. The
+ * DocLayout reads from this schema to render breadcrumb, title, page-actions,
+ * body, last-updated, and prev/next, so cross-cutting changes ship in one edit
+ * (the layout) instead of one-per-page.
+ *
+ * Required: title.
+ * All other fields are optional with sensible defaults computed in the layout.
+ */
+const docs = defineCollection({
+ type: 'content',
+ schema: z.object({
+ /* Identity */
+ title: z.string(),
+ description: z.string().optional(),
+ badge: z.enum(['alpha', 'beta', 'new', 'deprecated']).optional(),
+
+ /* Ordering + routing */
+ sidebar_position: z.number().optional(),
+ slug: z.string().optional(),
+
+ /* SEO surface */
+ keywords: z.array(z.string()).optional(),
+ meta_title: z.string().optional(), // overrides when set
+ meta_description: z.string().optional(), // overrides description for OG/meta
+ no_index: z.boolean().optional(), // robots noindex on dev/draft pages
+
+ /* Page chrome */
+ last_updated: z.string().optional(), // ISO date; the layout will fall back to file mtime if missing
+ edit_url: z.string().url().optional(), // override the auto-derived "Edit on GitHub" URL
+ toc_min_heading_level: z.number().optional(),
+ hide_toc: z.boolean().optional(), // full-bleed mode
+
+ /* Legacy SEO block (kept for back-compat with existing pages) */
+ seo: z.object({
+ primary_keyword: z.string(),
+ secondary_keywords: z.array(z.string()).optional(),
+ search_intent: z.string().optional(),
+ snippet_angle: z.string().optional(),
+ }).optional(),
+ }),
+});
+
+export const collections = { docs };
diff --git a/docs/api-reference/index.md b/src/content/docs/api-reference/index.md
similarity index 98%
rename from docs/api-reference/index.md
rename to src/content/docs/api-reference/index.md
index fb40012..ffc66bd 100644
--- a/docs/api-reference/index.md
+++ b/src/content/docs/api-reference/index.md
@@ -4,8 +4,6 @@ title: API Reference
description: Complete API reference for Suites testing framework
---
-# API Reference
-
API reference for setting up and managing unit tests with Suites.
<div class="in-this-section">
@@ -67,4 +65,4 @@ stubFn.mockReturnValue(42);
- **Mock**: A complete replacement of a dependency class where each method has been replaced with a stub
- **Stub**: An individual method replacement that provides predefined responses
-- **Mocked\<T\>**: The type representing a mocked dependency with stubbed methods
\ No newline at end of file
+- **Mocked\<T\>**: The type representing a mocked dependency with stubbed methods
diff --git a/docs/api-reference/mock-configuration.md b/src/content/docs/api-reference/mock-configuration.mdx
similarity index 98%
rename from docs/api-reference/mock-configuration.md
rename to src/content/docs/api-reference/mock-configuration.mdx
index 297cc3e..a27885c 100644
--- a/docs/api-reference/mock-configuration.md
+++ b/src/content/docs/api-reference/mock-configuration.mdx
@@ -4,15 +4,15 @@ title: Mock Configuration
description: Configure mock behavior with .final() and .impl()
---
-# Mock Configuration
+import Aside from '@/components/mdx/Aside.astro';
Suites provides two methods for configuring mock behavior:
* `.mock().final()` for immutable configurations
* `.mock().impl()` for flexible implementations
-:::note
+<Aside type="note">
This page describes the `.mock()` configuration method for `TestBed`. For creating standalone mocks manually, see the [`mock()` and `stub()` utility functions](/docs/api-reference/mock).
-:::
+</Aside>
## Methods
diff --git a/docs/api-reference/mock.md b/src/content/docs/api-reference/mock.mdx
similarity index 96%
rename from docs/api-reference/mock.md
rename to src/content/docs/api-reference/mock.mdx
index 31b85fd..e5328ba 100644
--- a/docs/api-reference/mock.md
+++ b/src/content/docs/api-reference/mock.mdx
@@ -4,14 +4,14 @@ title: mock() and stub()
description: Create type-safe mocks and stubs for any TypeScript code. Works without dependency injection frameworks.
---
-# mock() and stub()
+import Aside from '@/components/mdx/Aside.astro';
Standalone utility functions for creating type-safe mocks. Works with any TypeScript code, with or without dependency injection frameworks.
-:::info Mock and Stub Functions Are Adapter-Specific
+<Aside type="info" title="Mock and Stub Functions Are Adapter-Specific">
These functions are provided by your installed doubles adapter: `@suites/doubles.jest` (Jest), `@suites/doubles.vitest`
(Vitest) and `@suites/doubles.sinon` (Sinon).
-:::
+</Aside>
## When to Use
@@ -21,10 +21,10 @@ Use `mock()` and `stub()` functions when:
- Testing plain TypeScript classes, functions, or modules
- You're comfortable with **manual dependency wiring**
-:::note Trade-off: Manual vs Automatic Mocking
+<Aside type="note" title="Trade-off: Manual vs Automatic Mocking">
`mock()` provides type-safe mocking for any TypeScript code **but requires you to manually wire dependencies and track
mock references**. `TestBed` automates this but currently requires dependency injection frameworks.
-:::
+</Aside>
## mock()
@@ -47,9 +47,9 @@ function mock<T>(mockImplementation: DeepPartial<T> = {}): Mocked<T>
`Mocked<T>` - A deeply mocked instance where all methods are automatically stubbed.
-:::note
+<Aside type="note">
See [Types](/docs/api-reference/types#mockedt) for more about the `Mocked<T>` type.
-:::
+</Aside>
### How It Works
@@ -195,14 +195,14 @@ function stub<TArgs extends any[] = any[]>(): Mock<any, TArgs>
function stub<TArgs extends any[] = any[]>(): SinonStub
```
-:::info Alias for Native Stub
+<Aside type="info" title="Alias for Native Stub">
`stub()` is an alias for your test framework's native stub function:
- **Jest**: `jest.fn()`
- **Vitest**: `vi.fn()`
- **Sinon**: `sinon.stub()`
Use it for consistent API across frameworks.
-:::
+</Aside>
### Returns
diff --git a/docs/api-reference/testbed-sociable.md b/src/content/docs/api-reference/testbed-sociable.mdx
similarity index 95%
rename from docs/api-reference/testbed-sociable.md
rename to src/content/docs/api-reference/testbed-sociable.mdx
index 8f28e16..bbca02a 100644
--- a/docs/api-reference/testbed-sociable.md
+++ b/src/content/docs/api-reference/testbed-sociable.mdx
@@ -4,15 +4,15 @@ title: TestBed.sociable()
description: Test business logic interactions with real and mocked dependencies
---
-# TestBed.sociable()
+import Aside from '@/components/mdx/Aside.astro';
Creates a test environment that mixes real implementations with mocked dependencies for testing interactions between business logic classes.
-:::info Sociable Tests Are Still Unit Tests
+<Aside type="info" title="Sociable Tests Are Still Unit Tests">
Even with multiple real classes, sociable tests remain unit tests because external I/O (databases, HTTP, caches) are
injected via tokens (`@Inject('DATABASE')`) which are automatically mocked. You're testing business logic interactions,
not actual I/O. See the [Sociable Unit Tests Guide](/docs/guides/sociable) for concepts.
-:::
+</Aside>
## Signature
diff --git a/docs/api-reference/testbed-solitary.md b/src/content/docs/api-reference/testbed-solitary.md
similarity index 99%
rename from docs/api-reference/testbed-solitary.md
rename to src/content/docs/api-reference/testbed-solitary.md
index bd612d5..9604515 100644
--- a/docs/api-reference/testbed-solitary.md
+++ b/src/content/docs/api-reference/testbed-solitary.md
@@ -4,8 +4,6 @@ title: TestBed.solitary()
description: Create isolated unit tests with all dependencies mocked
---
-# TestBed.solitary()
-
Creates a test environment where all dependencies are automatically mocked for testing a class in complete isolation.
## Signature
diff --git a/docs/api-reference/types.md b/src/content/docs/api-reference/types.mdx
similarity index 94%
rename from docs/api-reference/types.md
rename to src/content/docs/api-reference/types.mdx
index 403c4e7..67cd16a 100644
--- a/docs/api-reference/types.md
+++ b/src/content/docs/api-reference/types.mdx
@@ -4,7 +4,7 @@ title: Types
description: TypeScript types and interfaces used in Suites
---
-# Types
+import Aside from '@/components/mdx/Aside.astro';
TypeScript type definitions used throughout Suites.
@@ -58,9 +58,9 @@ declare module '@suites/unit' {
This means the same `Mocked<T>` import resolves to different concrete types based on which adapter is installed.
-:::tip Zero Configuration
+<Aside type="tip" title="Zero Configuration">
This works automatically when you install an adapter package. No manual configuration needed - TypeScript resolves the correct types based on your installed dependencies.
-:::
+</Aside>
### Why This Architecture Matters
@@ -88,4 +88,4 @@ describe('UserService', () => {
- [UnitReference](/docs/api-reference/unit-reference) - Using the UnitReference interface
- [Mock Configuration](/docs/api-reference/mock-configuration) - Configuring mocks with proper types
-- [TypeScript Configuration](/docs/get-started/installation#typescript-configuration) - Setting up TypeScript for Suites
\ No newline at end of file
+- [TypeScript Configuration](/docs/get-started/installation#typescript-configuration) - Setting up TypeScript for Suites
diff --git a/docs/api-reference/unit-reference.md b/src/content/docs/api-reference/unit-reference.md
similarity index 99%
rename from docs/api-reference/unit-reference.md
rename to src/content/docs/api-reference/unit-reference.md
index cf953e7..c447a5f 100644
--- a/docs/api-reference/unit-reference.md
+++ b/src/content/docs/api-reference/unit-reference.md
@@ -4,8 +4,6 @@ title: UnitReference
description: Access mocked dependencies in your tests
---
-# UnitReference
-
The `UnitReference` object provides access to mocked dependencies within the test environment. It's returned by both
`TestBed.solitary()` and `TestBed.sociable()` after compilation.
@@ -208,4 +206,4 @@ const logger = unitRef.get<Logger>('LoggerToken'); // ✅ Correct symbol
- [Types](/docs/api-reference/types) - Type definitions including `Mocked<T>`
- [Mock Configuration](/docs/api-reference/mock-configuration) - Configuring mock behavior
- [TestBed.solitary()](/docs/api-reference/testbed-solitary) - Creating isolated tests
-- [TestBed.sociable()](/docs/api-reference/testbed-sociable) - Creating sociable tests
\ No newline at end of file
+- [TestBed.sociable()](/docs/api-reference/testbed-sociable) - Creating sociable tests
diff --git a/src/content/docs/blackbox/concepts/bdd-runtime-and-effects.md b/src/content/docs/blackbox/concepts/bdd-runtime-and-effects.md
new file mode 100644
index 0000000..c8dd539
--- /dev/null
+++ b/src/content/docs/blackbox/concepts/bdd-runtime-and-effects.md
@@ -0,0 +1,88 @@
+---
+title: "Effects, Runtime, and Specs"
+description: "Understand the Blackbox adoption model: runtime evidence is the source, effect catalogs are the core contract, and feature files are optional readable specs."
+sidebar_position: 4
+keywords: ["effect catalogs", "runtime evidence", "feature files", "BDD", "behavior specs"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "runtime evidence"
+ secondary_keywords: ["effect catalogs", "feature files", "BDD", "behavior specs"]
+ search_intent: "developers deciding whether Blackbox requires BDD, Gherkin, or feature files"
+ snippet_angle: "Blackbox starts from runtime evidence and effect catalogs; feature files are an optional readable layer, not a requirement"
+---
+
+Blackbox does not require a team to adopt BDD before it can prove system behavior.
+
+The core model is simpler:
+
+1. Runtime evidence is the source.
+2. Effect catalogs are the core behavior contract.
+3. Feature files and behavior specs are optional readable projections.
+
+That distinction matters because many teams already have runnable system or E2E tests, but they do not have current feature files. Other teams have feature files, but the files have drifted from the implementation. Blackbox should help both groups without pretending they are starting from the same place.
+
+## The Core Path
+
+The core Blackbox path starts with a real system run.
+
+A test executes a workflow. Blackbox captures runtime evidence from that execution. The evidence is mapped into effects: database writes, queue messages, cache operations, HTTP calls, emitted events, email intents, and forbidden side effects.
+
+Those effects become the reviewable contract. A future run can then ask:
+
+1. Did the required effects happen?
+2. Did forbidden effects stay absent?
+3. Did the effect coverage change?
+4. Did a decision produce a distinguishable system-level outcome?
+
+This is the part of Blackbox that should be present in the first adoption story. Feature files can improve the story, but the effect catalog is where the verification gate lives.
+
+## Why Specs Are Optional
+
+Feature files, BDD scenarios, and spec-driven development documents are useful because they give teams a readable language for intent. They help product, QA, and engineering talk about behavior without reading traces or YAML catalogs.
+
+They are not required for Blackbox to create value.
+
+If a team already has system tests, Blackbox can start by observing those tests and creating effect catalogs. If the team later wants readable scenarios, Blackbox can generate or maintain behavior specs from the runtime-backed artifacts.
+
+If a team already has feature files, Blackbox can help check whether the running system still matches them. The feature file remains the statement of intent. The runtime evidence shows what happened. The effect catalog becomes the executable behavior contract between the two.
+
+## Common Adoption Shapes
+
+| Starting point | What the team already has | How Blackbox fits |
+| --- | --- | --- |
+| Existing system tests | Runnable workflows with response assertions | Capture runtime evidence, review observed effects, create effect catalogs |
+| Existing E2E tests | Full journeys, often with broad input/output checks | Add behavioral evidence for the effects between input and output |
+| Existing feature files | Written scenarios that may drift | Connect readable intent to runtime evidence and effect catalogs |
+| Refactor work | A system whose current behavior must be preserved | Record current effects before the change, then gate the refactor against them |
+| AI-assisted development | Faster code changes and generated implementations | Give reviewers an external behavior artifact beyond model output and local assertions |
+
+These paths are not equal product modes. They are entry points into the same model. The durable center is the effect catalog backed by runtime evidence.
+
+## The E2E Blind Spot
+
+Traditional E2E tests are often strongest at the edges of a workflow: send this input, expect this output. That is necessary, but it can miss the behavior in the middle.
+
+A checkout, subscription, onboarding, or webhook flow might return the expected response while skipping an event, missing an audit write, calling a deprecated service, duplicating a notification, or mutating a cache incorrectly.
+
+Blackbox adds the missing evidence layer. It does not discard the E2E assertion. It asks what the system actually did while satisfying that assertion.
+
+## How To Think About The Artifacts
+
+The artifacts have different jobs:
+
+| Artifact | Job |
+| --- | --- |
+| Runtime evidence | The observed facts from a real execution |
+| Effect catalog | The required, allowed, and forbidden behavior contract |
+| Effect coverage report | The review surface for what behavior was exercised or missed |
+| OMC/DC report | A system-level signal for whether decision changes are visible through effects |
+| Feature file | An optional readable spec derived from, or checked against, runtime-backed behavior |
+
+When the docs talk about Blackbox, they should lead with the first three. Feature files belong in the story when the reader cares about BDD, spec-driven development, living documentation, or behavior language for humans.
+
+## What To Read Next
+
+1. [System Effects](/docs/blackbox/concepts/system-effects)
+2. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
+3. [Requires and Forbids](/docs/blackbox/concepts/requires-and-forbids)
+4. [Feature Files, BDD, and Staleness](/docs/blackbox/concepts/feature-files-and-staleness)
diff --git a/src/content/docs/blackbox/concepts/feature-files-and-staleness.md b/src/content/docs/blackbox/concepts/feature-files-and-staleness.md
new file mode 100644
index 0000000..2788d7f
--- /dev/null
+++ b/src/content/docs/blackbox/concepts/feature-files-and-staleness.md
@@ -0,0 +1,128 @@
+---
+title: "Feature Files, BDD, and Staleness"
+description: "Relate BDD, Gherkin, Cucumber, stale feature files, and the Blackbox gates that keep behavior artifacts synchronized."
+sidebar_position: 5
+keywords: ["gherkin staleness", "bdd feature files", "living documentation", "feature-file drift"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "given when then"
+ secondary_keywords: ["gherkin syntax", "bdd feature files", "living documentation", "feature-file drift"]
+ search_intent: "BDD education intent from teams worried that Gherkin and feature files become stale"
+ snippet_angle: "feature files stay useful when they are generated from test sources and checked by syntax, drift, and runtime gates"
+---
+
+BDD and Gherkin had the right ambition: make behavior visible, reviewable, and connected to executable checks. The failure mode was maintenance.
+
+When `.feature` files become another hand-written artifact, they can drift from product intent, test source, and system behavior. A sentence can still read well while the service no longer calls the same dependency, emits the same event, writes the same record, or blocks the same forbidden action.
+
+Blackbox does not ask every team to return to classic Cucumber-style BDD. It keeps the useful shape, then adds gates around it.
+
+## Why Feature Files Go Stale
+
+Feature files go stale when they are treated as the source of truth but are not continuously checked against what developers actually run.
+
+Classic BDD often created three things that had to agree:
+
+1. The `.feature` file.
+2. The step definitions.
+3. The implementation and test runner behavior.
+
+That can work when the team has discipline and stable behavior. It breaks down when a system changes quickly, when tests are mostly written by engineers rather than product/QA, or when AI-assisted changes increase the amount of behavior reviewers must verify.
+
+## Two Kinds Of Drift
+
+Blackbox separates two drift problems that often get mixed together:
+
+| Drift type | Question | Blackbox gate |
+| --- | --- | --- |
+| Feature-file drift | Does the `.feature` file still match the test source? | `blackbox features check` or `blackbox features drift` |
+| Behavioral drift | Did the running system behavior change in a meaningful way? | Effect catalog, effect coverage, and optional observation comparison |
+
+Feature-file drift is about synchronization between source tests and readable Gherkin. Behavioral drift is about runtime effects, assertions, outcomes, and system boundaries.
+
+Do not use bare “drift” when writing docs or error messages. Say which kind.
+
+## The Blackbox Direction
+
+Blackbox starts from tests and evidence:
+
+1. A system test exercises a behavior.
+2. The feature analyzer derives an AAA/Given-When-Then trace from the test source.
+3. The feature emitter writes a Gherkin `.feature` file from that trace.
+4. The syntax and drift gate checks the `.feature` file against the source.
+5. Runtime evidence and effect catalogs prove what the system did at its boundaries.
+
+The feature file becomes a review surface over executable behavior, not a promise that must be trusted by itself.
+
+## Relationship To BDD And Gherkin
+
+Blackbox does not need to argue that BDD was wrong. BDD correctly focused teams on behavior. The problem was the direction and cost of synchronization.
+
+Traditional flow:
+
+1. Human writes feature file.
+2. Automation binds steps to code.
+3. People must maintain the feature file as the system evolves.
+
+Blackbox flow:
+
+1. Test source describes or exercises the behavior.
+2. Blackbox analyzes the behavior grammar.
+3. Blackbox emits or checks the feature file.
+4. Runtime gates prove the behavior through effects and observations.
+5. People review the artifact changes instead of manually maintaining every sentence.
+
+Gherkin remains the human-readable format. Cucumber-compatible parsing is used for syntax validation. Cucumber-style step definitions are not required.
+
+## The Behavior Grammar
+
+The Blackbox feature pipeline is built around AAA:
+
+```text
+Given* When+ Then+
+```
+
+`Given` describes setup and preconditions. `When` describes the action. `Then` is the concluder: the scenario must end in observable assertions. A feature file without a meaningful `Then` is documentation, not verification.
+
+The linter enforces this shape and catches common failure modes:
+
+1. `Then` before any `When`.
+2. `Given` after the action.
+3. `When` after assertions.
+4. Missing action.
+5. Missing assertion.
+6. Opaque generated steps.
+7. Repeated setup that should become a `Background`.
+
+## The Cycle Of Gates
+
+Blackbox connects feature files, system tests, and E2E suites in a cycle of gates:
+
+1. `features lint` checks the behavior grammar.
+2. `features emit` generates Gherkin from test source.
+3. `features check` validates Gherkin syntax and catches feature-file drift.
+4. The project system-test command runs the behavior.
+5. Effect catalogs and effect coverage catch boundary behavior changes.
+6. Observation comparison can catch meaningful runtime differences during migration or refactor.
+
+This is the connection to verification gates: feature files are not just docs, and runtime evidence is not just debugging data. Each artifact has a gate that can run locally, in CI, or inside an SDD/agent workflow.
+
+## How The REPL Should Teach This
+
+The ideal REPL is not a marketing animation. It should load `@suites/blackbox-features`, accept a small test, and show the transformation in real time:
+
+1. Source test.
+2. Detected adapter: Playwright or BDD DSL.
+3. Analyzed AAA/Given-When-Then trace.
+4. Generated `.feature` file.
+5. Lint findings, syntax result, and feature-file drift result.
+6. Optional observation comparison when baseline and candidate runs exist.
+
+That REPL would make the product promise concrete: you can see exactly what Blackbox inferred, where it was confident, where it fell back to generic text, and which gate will protect the artifact.
+
+## What To Read Next
+
+1. [Feature Files From Tests](/docs/blackbox/quickstart/feature-files-from-tests)
+2. [Generating Feature Files](/docs/blackbox/guides/generating-feature-files)
+3. [Configure CI Gates](/docs/blackbox/guides/ci-behavioral-gates)
+4. [Scenario DSL](/docs/blackbox/reference/scenario-dsl)
diff --git a/src/content/docs/blackbox/concepts/omc-dc-coverage.md b/src/content/docs/blackbox/concepts/omc-dc-coverage.md
new file mode 100644
index 0000000..b756abf
--- /dev/null
+++ b/src/content/docs/blackbox/concepts/omc-dc-coverage.md
@@ -0,0 +1,131 @@
+---
+title: "OMC/DC Coverage"
+description: "Explain how Blackbox turns real system runs into decision coverage artifacts."
+sidebar_position: 4
+keywords: ["omc dc coverage", "decision coverage", "system test coverage"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "omc dc coverage"
+ secondary_keywords: ["decision coverage", "system test coverage", "mcdc coverage"]
+ search_intent: "educational intent from developers comparing decision coverage with system-test behavior coverage"
+ snippet_angle: "explain OMC/DC as system-test decision coverage based on observed effects, not unit-test line coverage"
+---
+
+## Abstract
+
+OMC/DC coverage is Blackbox's decision-coverage view of a real system run. It answers a different question from unit-test coverage: not "which lines ran in a small function test," but "which decisions changed the observable behavior of the system test?"
+
+It is related to MCDC, but Blackbox applies the idea at the system-test evidence layer. The engine looks at branches, the tests that exercised their arms, and the runtime effects observed for those tests.
+
+## Audience
+
+Readers who want to understand what Blackbox means by coverage before they look at the report files.
+
+## What It Covers
+
+1. Branch and decision behavior observed during a system test.
+2. Whether the run exercised the expected boundary effects.
+3. Whether the run left gaps, masking candidates, or uncovered behavior.
+4. Whether those runs came from serial chains or parallel siblings in the BDD DSL.
+
+## How It Relates To System Effects
+
+OMC/DC coverage is not the effect catalog, and it is not another name for effect coverage.
+
+The effect catalog records the effects that matter for a flow. Matchers use that catalog to check whether the run covered required effects and avoided forbidden effects. OMC/DC uses the observed effects as evidence for a different question: did a decision in the system produce behavior that the system test could distinguish?
+
+That distinction keeps the artifacts readable:
+
+| Artifact | Job |
+| --- | --- |
+| Effect catalog | Records required and forbidden effects for a flow |
+| Effect coverage | Reports whether cataloged effects were observed, missing, forbidden, or newly seen |
+| OMC/DC coverage | Reports whether decisions produced distinguishable observed behavior |
+
+## What OMC/DC Means Here
+
+In classic MCDC, the useful question is whether each condition can independently affect a decision outcome. In Blackbox, the useful system-test question is whether a decision arm affected the observable runtime behavior that the system test can prove.
+
+That is why the report compares branch arms against effect signatures. If both arms ran but produced the same boundary evidence, the system test may still be passing, but the evidence is not strong enough to prove that the decision mattered at the boundary.
+
+## How It Differs From Unit-Test Coverage
+
+1. Unit-test coverage asks what code paths a small test suite hit inside isolated logic.
+2. OMC/DC coverage asks what decision behavior and boundary effects a full system run actually exercised.
+3. Unit coverage is often local and implementation-shaped.
+4. OMC/DC coverage is behavioral and run-shaped.
+
+## What Blackbox Does With It
+
+1. Collect runtime evidence from the real run.
+2. Propagate that evidence through the coverage engine.
+3. Render propagation artifacts and summaries.
+4. Use the result as proof, not as a replacement for the run itself.
+
+## How To Read The Result
+
+The important question is not only "did the test pass?" It is "did the run exercise the decision behavior and boundary effects we expected?"
+
+That is why the report family matters:
+
+1. The propagation artifact shows how the engine arrived at the verdict.
+2. The markdown and HTML versions make the result easier for humans to read.
+3. The summary artifacts make it easier to compare runs over time.
+
+## Verdicts
+
+| Verdict | What it tells you |
+| --- | --- |
+| `propagating` | The observed evidence distinguishes the branch arms. |
+| `masking-candidate` | Both arms were exercised, but their observed effect signatures were indistinguishable. |
+| `coverage-gap` | The run did not observe enough arm coverage to prove the decision. |
+| `undecidable` | The engine could not decide from the evidence it had. |
+| `multi-arm` | The decision shape is more complex than a simple two-arm comparison. |
+| `unsupported-mcdc` | The current alpha engine does not support this decision shape yet. |
+
+These verdicts are about proof strength. A `coverage-gap` does not mean the application is wrong. It means the current evidence does not prove enough. A `masking-candidate` does not automatically mean a bug. It means the test ran both arms but the effects looked the same from the evidence Blackbox could see.
+
+## Parallel And Serial Shapes
+
+Blackbox's BDD DSL supports both ordered and concurrent execution shapes.
+
+1. `scenario.shared(...)` preserves state across an ordered chain.
+2. `scenario.isolated(...)` gives concurrent siblings separate isolation groups.
+3. `outline(...)` expands into repeated cases that can be read and executed like the rest of the suite.
+4. The showcase file demonstrates that parallelism is part of the model, not an edge case.
+
+This matters because the coverage model is about the run, not the shape of the prose. The same verification story can be exercised by a serial chain, a parallel sibling set, or an outline table, as long as the testbed keeps the evidence path intact.
+
+## What The Artifacts Mean
+
+1. `omcdc-propagation.json` is the machine-readable propagation artifact.
+2. `omcdc-propagation.md` is the reviewable markdown form.
+3. `omcdc.html` is the interactive report.
+4. `coverage.json` and `shape-coverage.json` summarize catalog and shape coverage.
+5. `omcdc.junit.xml` is the CI-facing test-result form when JUnit is enabled.
+
+The detailed propagation artifacts include endpoint groups, branch coordinates, true-arm and false-arm test IDs, not-observed test IDs, verdicts, hints, and observed effect shapes. That is why they are useful for review after a refactor or an AI-assisted change: they show not only that a test passed, but what behavior the run actually distinguished.
+
+## Gaps And Limits
+
+1. It proves exercised behavior for the run, not formal proof of all behavior.
+2. It depends on instrumentation and a runnable system test.
+3. Parallel and concurrent execution are supported; attribution still depends on the testbed preserving a clean path from each run to its evidence.
+4. Coverage before instrumentation starts is invisible by design.
+5. Detached continuations can escape trace attribution.
+6. The coverage output is only useful if the evidence and artifact story are preserved.
+7. Function-level spans can help distinguish internal decisions whose boundary effects look identical, but they are an opt-in evidence layer rather than a requirement for basic effect coverage.
+
+## What The Engine Does Not Try To Solve
+
+1. Formal proof of all behavior.
+2. Exhaustive concurrency correctness.
+3. Coverage of code that never reaches the monitored boundary.
+4. Coverage of arbitrary native or dynamic code unless the instrumentation path can see it.
+5. A replacement for the test runner or the runtime evidence layer.
+
+## Figure Placeholder
+
+**Caption:** OMC/DC coverage turning one real system test into decision-coverage artifacts.
+
+**Slot:** `<!-- TODO: insert OMC/DC report screenshot, animated flow, or interactive branch view here -->`
diff --git a/src/content/docs/blackbox/concepts/requires-and-forbids.md b/src/content/docs/blackbox/concepts/requires-and-forbids.md
new file mode 100644
index 0000000..795a063
--- /dev/null
+++ b/src/content/docs/blackbox/concepts/requires-and-forbids.md
@@ -0,0 +1,67 @@
+---
+title: "Requires and Forbids"
+description: "Explain positive requirements, forbidden effects, and proving the negative through physical absence."
+sidebar_position: 4
+keywords: ["behavioral assertions", "behavior assertions", "requires forbids", "forbidden effects"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "behavioral assertions"
+ secondary_keywords: ["behavior assertions", "requires forbids", "forbidden effects"]
+ search_intent: "brand-building intent for teams looking for assertions over runtime behavior rather than implementation details"
+ snippet_angle: "behavioral assertions include both required effects and forbidden effects at the system boundary"
+---
+
+## Abstract
+
+Explain positive requirements, forbidden effects, and proving the negative through physical absence.
+
+This page explains the two halves of a behavior contract: what must happen and what must not happen.
+
+## Audience
+
+These pages define the nouns and mental models behind effect coverage and behavioral verification.
+
+## Behavioral Assertions
+
+Behavioral assertions are assertions over what the running system did at the boundary. They are different from unit-level expectations because they describe externally visible behavior: events, writes, calls, messages, emails, and other effects.
+
+Blackbox splits behavioral assertions into two families: requires and forbids.
+
+## Requires
+
+Required effects are the behaviors the team needs to see in a successful run.
+
+## Forbids
+
+Forbidden effects are the behaviors that should not appear at the boundary.
+
+## Why The Negative Matters
+
+The absence of a forbidden effect is often the thing the team cares about most. Blackbox makes that absence reviewable by comparing the run against the contract.
+
+## How It Fits The Workflow
+
+1. The scenario defines the expected behavior.
+2. The run emits effects.
+3. The catalog or report compares observed behavior to required and forbidden effects.
+4. The team decides whether the change is acceptable.
+
+## Content Outline
+
+1. Define the concept in one paragraph.
+2. Explain how it appears in the Blackbox workflow.
+3. Connect it to stale specs, runtime evidence, or behavioral gates where relevant.
+4. Link to the guide or reference page that makes it practical.
+
+## Practical Guidance
+
+1. Keep requires and forbids specific.
+2. Tie them to a real boundary effect.
+3. Avoid wording that only tests internal implementation details.
+4. Prefer contracts that a reviewer can understand quickly.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/concepts/system-effects.md b/src/content/docs/blackbox/concepts/system-effects.md
new file mode 100644
index 0000000..4d0059e
--- /dev/null
+++ b/src/content/docs/blackbox/concepts/system-effects.md
@@ -0,0 +1,123 @@
+---
+title: "System Effects"
+description: "Understand effects, effect catalogs, effect coverage, and how OMC/DC adds a separate decision-coverage view."
+sidebar_position: 1
+keywords: ["system effects", "effect catalog", "effect coverage", "behavioral evidence", "system test coverage"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "system effects"
+ secondary_keywords: ["effect catalog", "effect coverage", "behavioral evidence", "system test coverage"]
+ search_intent: "developers trying to understand the Blackbox behavior model for system and E2E tests"
+ snippet_angle: "system effects are the observed behaviors behind Blackbox catalogs, matcher coverage, and enriched OMC/DC reports"
+---
+
+## Abstract
+
+System effects are the behaviors a real system run leaves behind: a row written, an event published, a queue message sent, a downstream service called, a cache updated, an email intent emitted, or a forbidden dependency avoided.
+
+Blackbox starts from those effects. The effect catalog records which effects matter. Matchers use that catalog to check whether the effects were covered during the run. OMC/DC coverage is a separate enriched coverage view that asks whether decisions in the system produced distinguishable observed effects.
+
+## Audience
+
+Read this page when you want the core Blackbox mental model before reading report files, matcher APIs, generated feature files, or OMC/DC details.
+
+## The E2E Gap
+
+Many E2E tests prove the edge of a workflow:
+
+1. Send this input.
+2. Expect this output.
+
+That is necessary, but it can miss the behavior between the two. A request can return `201 Created` while the system skipped an audit write, failed to publish an event, called the wrong dependency, duplicated a notification, or silently missed a cache update.
+
+Blackbox adds a behavior evidence layer to that run. It does not replace the input/output assertion. It records what the system did while satisfying the assertion.
+
+## The Four Related Ideas
+
+These terms are related, but they are not the same thing.
+
+| Term | What it is | Main question |
+| --- | --- | --- |
+| System effect | One observed boundary behavior from a real run | What did the system do? |
+| Effect catalog | The reviewed recording and contract for important effects | Which effects should future runs require or forbid? |
+| Effect coverage | The matcher/report view over cataloged effects | Which required, forbidden, observed, or missing effects were covered? |
+| OMC/DC coverage | Enriched decision coverage based on observed effects | Did decisions produce distinguishable system behavior? |
+
+The catalog is the contract. Effect coverage is the covered-or-missing view of that contract. OMC/DC is another coverage layer, not another name for the catalog.
+
+## What Counts As A System Effect
+
+A useful effect is observable at a boundary and meaningful enough to review.
+
+Common examples:
+
+1. A database record was inserted or updated.
+2. A domain event was published.
+3. A queue message was enqueued.
+4. A downstream HTTP call was made.
+5. A cache entry was written or invalidated.
+6. An email or notification intent was emitted.
+7. A deprecated dependency was not called.
+
+Not every span is an effect. Spans are often how Blackbox sees behavior. The effect is the behavior your team cares about.
+
+## The Effect Catalog
+
+The effect catalog is the reviewed behavior contract behind Blackbox.
+
+The first useful run can observe what happened and produce a baseline. After review, the catalog separates important behavior from incidental noise:
+
+1. `requires` entries describe effects that must appear.
+2. `forbids` entries describe effects that must stay absent.
+3. Matchers compare future runtime evidence against that catalog.
+4. CI can fail when required effects disappear or forbidden effects appear.
+
+The catalog is intentionally different from a mock, stub, spy, or fake. Test doubles control or inspect collaborators in lower-level tests. The effect catalog records behavior from a real system or E2E run.
+
+## Effect Coverage
+
+Effect coverage asks whether the effects in the catalog were covered by the run.
+
+A report should help answer:
+
+1. Which required effects were observed?
+2. Which required effects were missing?
+3. Which forbidden effects appeared?
+4. Which observed effects are not yet part of the reviewed catalog?
+5. Which behavior changed since the last accepted run?
+
+This is different from line coverage. A test can execute code and still fail to prove that the system published the right event, wrote the right record, or avoided the wrong side effect.
+
+## OMC/DC Is A Separate Enriched Coverage Layer
+
+OMC/DC coverage uses runtime evidence and effect signatures to ask a different question: did a decision in the system produce distinguishable behavior at the system-test evidence layer?
+
+For example, two branch arms might both execute and both return a passing response. If their observed effects are indistinguishable, the run may not prove that the decision mattered at the boundary.
+
+That makes OMC/DC useful, but it is not the same as effect coverage:
+
+1. Effect coverage checks cataloged effects.
+2. OMC/DC checks decision evidence through observed effects.
+3. Both depend on runtime evidence.
+4. Both are stronger when the catalog is reviewed and the system test is intentional.
+
+## How It Fits The Workflow
+
+The core Blackbox workflow is:
+
+1. Run a system or E2E flow.
+2. Capture runtime evidence.
+3. Derive observed system effects.
+4. Review the effect catalog.
+5. Assert future runs with matchers.
+6. Inspect effect coverage and OMC/DC reports.
+7. Optionally generate readable feature files or behavior specs.
+
+Feature files are useful when teams want readable behavior language, BDD, or spec-driven development. They are not required for effect coverage.
+
+## What To Read Next
+
+1. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
+2. [Requires and Forbids](/docs/blackbox/concepts/requires-and-forbids)
+3. [OMC/DC Coverage](/docs/blackbox/concepts/omc-dc-coverage)
+4. [Effects, Runtime, and Specs](/docs/blackbox/concepts/bdd-runtime-and-effects)
diff --git a/src/content/docs/blackbox/concepts/system-tests-and-runtime-evidence.md b/src/content/docs/blackbox/concepts/system-tests-and-runtime-evidence.md
new file mode 100644
index 0000000..5365357
--- /dev/null
+++ b/src/content/docs/blackbox/concepts/system-tests-and-runtime-evidence.md
@@ -0,0 +1,105 @@
+---
+title: "Runtime Evidence"
+description: "Explain how system tests, E2E tests, characterization testing, and trace-based evidence become Blackbox proof artifacts."
+sidebar_position: 6
+keywords: ["characterization testing", "runtime verification", "what is system testing", "trace based testing", "golden master testing"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "characterization testing"
+ secondary_keywords: ["runtime verification", "what is system testing", "golden master testing", "trace based testing", "runtime evidence"]
+ search_intent: "educational intent from teams trying to understand system tests, legacy characterization, and evidence-based regression checks"
+ snippet_angle: "characterization testing captures existing behavior; Blackbox updates that idea with system-test runtime evidence and effect coverage"
+---
+
+## Abstract
+
+Runtime evidence is what Blackbox trusts from a real run: traces, spans, generated artifacts, test output, and other observable facts produced while the system executed.
+
+In older testing language, this is close to characterization testing or golden master testing: capture what the system does before you change it, then compare future behavior against that baseline. Blackbox makes that idea more specific for modern backend systems by using runtime evidence, effects, catalogs, and coverage reports.
+
+## Audience
+
+Readers who want to understand why a real run can become a behavior report, and why Blackbox treats observed runtime evidence as more trustworthy than stale written intent.
+
+## What Is Runtime Evidence?
+
+Runtime evidence is the observed record of a system test or E2E run. It can include:
+
+1. OpenTelemetry spans.
+2. Playwright or runner output.
+3. Logs, traces, and request records.
+4. Generated effect catalogs and feature files.
+5. Coverage artifacts such as OMC/DC reports.
+
+Blackbox uses this evidence to answer a practical question: what did the system actually do at the boundary during this run?
+
+## What Is System Testing?
+
+In these docs, a system test runs a composed system under controlled conditions. The test may include managed dependencies such as databases, queues, caches, local services, Docker Compose services, Testcontainers, and an OpenTelemetry collector.
+
+System tests usually replace, stub, sandbox, or omit unmanaged dependencies such as real auth providers, email delivery, payment processors, vendor APIs, and shared remote environments. That control makes the result more repeatable and usually better suited for CI gates.
+
+E2E tests are different. They often run a complete journey against a remote or production-like environment and may involve unmanaged dependencies. Blackbox can observe both, but system tests usually produce cleaner evidence for repeated verification.
+
+## Characterization Testing For Modern Systems
+
+Characterization testing is the practice of capturing existing behavior before changing a system. It is useful when the system is valuable but poorly understood, especially before a refactor or modernization project.
+
+Blackbox applies that idea at the system boundary:
+
+1. Run a workflow before the change.
+2. Capture runtime evidence.
+3. Derive effects from the run.
+4. Save the behavior as a reviewable contract.
+5. Run the workflow again after the change.
+6. Compare what changed.
+
+This is similar in spirit to golden master testing, but the artifact is not only a raw snapshot. Blackbox separates observed effects, required effects, forbidden effects, and coverage reports so the team can review behavior instead of accepting an opaque blob.
+
+## Runtime Verification And Trace-Based Testing
+
+Runtime verification checks behavior from facts produced while the system runs. In Blackbox, that means system tests and E2E runs produce evidence that can be compared with required and forbidden behavior.
+
+Trace-based testing checks behavior through traces and spans. Blackbox uses traces as one evidence source, but the product goal is broader than asserting on a trace shape.
+
+| Practice | Main artifact | What it proves |
+| --- | --- | --- |
+| Trace-based testing | Trace assertions | A trace contained expected spans or attributes |
+| Runtime verification | Runtime facts compared to expected behavior | The running system satisfied a verification rule |
+| Characterization testing | Captured baseline | Existing behavior stayed stable or changed visibly |
+| Blackbox runtime evidence | Effects, catalog, feature files, coverage reports | Runtime behavior matched required and forbidden effects |
+
+The difference is the review layer. Blackbox turns evidence into artifacts that humans and CI can reason about.
+
+## What Blackbox Trusts
+
+Blackbox trusts evidence tied to an actual run. It does not trust a feature file, task list, or spec by itself.
+
+A strong Blackbox run has:
+
+1. A real system or E2E workflow.
+2. Clear runtime boundaries.
+3. Enough instrumentation to observe relevant effects.
+4. Artifacts that can be inspected after the run.
+5. A catalog or assertion layer that marks what was required and forbidden.
+
+If any of those are missing, Blackbox may still produce useful diagnostics, but the proof is weaker.
+
+## Why This Matters
+
+System behavior often fails outside the unit under edit. A refactor can keep unit tests green and still stop publishing an event. A generated agent patch can satisfy a task and still skip a downstream call. A spec can stay readable while the system drifts.
+
+Runtime evidence is the correction. It gives the team something observed, current, and reviewable. It is also the basis for behavior trace testing and runtime behavior testing: not only whether code ran, but whether the observed behavior matched the model the team cares about.
+
+## What To Read Next
+
+1. [Unit, Integration, System, and E2E Testing](/docs/blackbox/concepts/unit-integration-system-e2e-blackbox-testing)
+2. [System Effects](/docs/blackbox/concepts/system-effects)
+3. [OMC/DC Coverage](/docs/blackbox/concepts/omc-dc-coverage)
+4. [Covering Before Refactor](/docs/blackbox/use-cases/covering-before-refactor)
+
+## Figure Placeholder
+
+**Caption:** A system test run becoming runtime evidence, effects, and a reviewable report.
+
+**Slot:** `<!-- TODO: insert evidence pipeline screenshot or GIF here -->`
diff --git a/src/content/docs/blackbox/concepts/unit-integration-system-e2e-blackbox-testing.md b/src/content/docs/blackbox/concepts/unit-integration-system-e2e-blackbox-testing.md
new file mode 100644
index 0000000..b4bb4e5
--- /dev/null
+++ b/src/content/docs/blackbox/concepts/unit-integration-system-e2e-blackbox-testing.md
@@ -0,0 +1,123 @@
+---
+title: "Unit, Integration, System, and E2E Testing"
+description: "Compare unit, integration, system, end-to-end, black-box, and white-box testing, and show where Suites Unit and Suites Blackbox fit."
+sidebar_position: 2
+keywords: ["unit testing vs integration testing", "blackbox vs whitebox testing", "system testing", "e2e testing", "testing pyramid"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "unit testing vs integration testing"
+ secondary_keywords: ["blackbox vs whitebox testing", "what is system testing", "what is e2e testing", "testing pyramid"]
+ search_intent: "comparison and education for teams choosing the right test layer"
+ snippet_angle: "explain each test layer, then show where Suites Unit and Suites Blackbox fit"
+---
+
+## Abstract
+
+Blackbox is named after black-box testing, but the product is more specific: Suites Blackbox helps teams prove system and end-to-end behavior from runtime evidence. Suites Unit works closer to the code, at the unit and integration layers. The two tools answer different confidence questions and should be used together when the risk profile justifies it.
+
+This page defines the testing layers the Blackbox docs use, including the difference between managed and unmanaged dependencies.
+
+## Audience
+
+Developers, engineering leads, and agent-workflow builders who need a clear map of where unit, integration, system, end-to-end, black-box, and white-box testing belong.
+
+## The Short Answer
+
+Unit tests verify small pieces of code. Integration tests verify several code pieces working together. System tests verify a composed system with dependencies the team controls. E2E tests verify a full journey in an environment closer to production, often involving remote or unmanaged dependencies.
+
+Suites Unit helps at the unit and integration layers. Suites Blackbox helps at the system and E2E layers by observing runtime behavior from the outside.
+
+## The Testing Layers
+
+| Layer | What it verifies | Typical dependencies | Where Suites fits |
+| --- | --- | --- | --- |
+| Unit test | One function, class, provider, or module | Mostly mocked, faked, or in-memory | Suites Unit |
+| Integration test | Several code units or providers working together | Controlled collaborators, in-process wiring, fakes, or test containers | Suites Unit and ordinary test runners |
+| System test | A composed application or service topology | Managed dependencies such as database, queue, cache, local services, Docker Compose, or Testcontainers | Suites Blackbox |
+| E2E test | A full user or business journey through a deployed or production-like environment | Often includes remote services, auth, email, payment sandboxes, third-party APIs, or shared environments | Suites Blackbox can observe the run |
+| Black-box test | Behavior observed from the outside | Depends on the chosen layer | Suites Blackbox when the layer is system or E2E |
+| White-box test | Behavior checked with knowledge of internals | Source code, branches, classes, modules, and implementation paths | Suites Unit and code coverage tools |
+
+Teams use these names differently. In the Blackbox docs, the distinction is about scope, control, and what kind of proof the test produces.
+
+## Managed And Unmanaged Dependencies
+
+A **managed dependency** is something the team controls during the test run. Examples include a local database, queue, cache, containerized service, fake mail server, OpenTelemetry collector, or Docker Compose dependency created for the test.
+
+An **unmanaged dependency** is something outside the test's direct control. Examples include a real auth provider, real email delivery, SMS, payment processors, vendor APIs, production-like shared environments, or remote infrastructure owned by another team.
+
+This distinction matters because repeatability changes the meaning of the result:
+
+1. System tests usually include managed dependencies and replace, stub, sandbox, or omit unmanaged dependencies.
+2. E2E tests more often involve unmanaged dependencies or remote environments.
+3. System tests usually make stronger CI gates because the environment is controlled.
+4. E2E tests usually give stronger journey realism, but with more latency, flakiness, and external variance.
+
+Blackbox can collect runtime evidence from both system tests and E2E tests. The evidence is still useful, but teams should interpret failures differently depending on how much of the environment they control.
+
+## Unit Testing Vs Integration Testing
+
+A unit test keeps the scope small. It checks a class, function, provider, or module with most collaborators replaced by test doubles. The value is speed, locality, and fast feedback when an implementation changes.
+
+An integration test checks several pieces working together. In a TypeScript backend, that might mean a provider graph, a service and repository, a controller and service, or a small module boundary. Some dependencies may still be mocked, but the test is no longer only about one isolated unit.
+
+Suites Unit is strongest in this part of the stack. It helps teams create solitary and sociable unit tests around TypeScript classes, providers, and dependency graphs without turning every test into manual mocking work. For the deeper unit-testing model, see [Unit Testing Fundamentals](/docs/guides/fundamentals) and [Why Suites](/docs/get-started/why-suites).
+
+## System Testing Vs E2E Testing
+
+A system test runs the composed system under controlled conditions. It may start the API, worker, database, queue, cache, local service dependencies, and telemetry collector. The goal is to prove behavior across real boundaries while keeping the test environment repeatable.
+
+An end-to-end test runs a complete journey through something closer to the real deployment path. It may use a remote environment, real login flow, sandbox email inbox, payment sandbox, third-party API, feature flag service, or other unmanaged dependency.
+
+Suites Blackbox belongs here. It observes a real run, captures runtime evidence, turns that evidence into effects, and reports what behavior was proven, missing, forbidden, or newly observed.
+
+## Black-Box Vs White-Box Testing
+
+White-box testing uses knowledge of the implementation. A test might care about a class method, branch, provider graph, or internal module boundary. This is useful for fast diagnosis and local refactor safety.
+
+Black-box testing observes behavior from the outside. A test cares that a user was created, an event was published, an email effect was emitted, a database row changed, or a downstream call happened. It should not need to know which private method caused the behavior.
+
+Suites Blackbox is a black-box system and E2E testing tool. It is not just a generic definition of black-box testing. It gives teams a concrete way to collect runtime evidence, build effect coverage, and use the result as a behavioral verification gate.
+
+## How The Pyramid Shifts In The AI Era
+
+The testing pyramid still matters. Fast unit and integration tests should remain the cheapest feedback layer. AI coding agents do not remove that need.
+
+What changes is the cost of producing code and the risk of accepting behavior too early. Agents can generate more code faster, specs can drift faster, and a green unit suite can still miss system behavior at the boundary. The top of the pyramid needs a stronger proof layer.
+
+Blackbox does not flip the pyramid. It adds a clearer system and E2E verification layer:
+
+1. Use unit tests to catch local behavior quickly.
+2. Use integration tests to catch collaborator and provider wiring issues.
+3. Use system tests to prove behavior across controlled runtime boundaries.
+4. Use E2E tests when the full journey and unmanaged dependencies matter.
+5. Use Blackbox evidence to decide whether the observed runtime effects match the intended behavior.
+
+For AI-assisted development, this gives agents and reviewers an external stop condition: the implementation is not done because the diff looks plausible. It is done when the required runtime effects were observed and forbidden effects were absent.
+
+## FAQ
+
+### Is Blackbox only another name for black-box testing?
+
+No. The name comes from black-box testing, but Suites Blackbox is specifically about system and E2E runtime evidence, effects, and coverage artifacts.
+
+### Should every team write E2E tests for everything?
+
+No. E2E tests are useful for critical journeys, but system tests are usually easier to control and gate in CI.
+
+### Where do Suites Unit and Suites Blackbox meet?
+
+Suites Unit catches local behavior and integration slices closer to code. Suites Blackbox catches composed system behavior at runtime boundaries.
+
+## What To Read Next
+
+1. [System Effects](/docs/blackbox/concepts/system-effects)
+2. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
+3. [OMC/DC Coverage](/docs/blackbox/concepts/omc-dc-coverage)
+4. [Writing Scenarios](/docs/blackbox/guides/writing-scenarios)
+
+## Figure Placeholder
+
+**Caption:** The testing pyramid with Suites Unit at the unit/integration layers and Suites Blackbox at the system/E2E boundary.
+
+**Slot:** `<!-- TODO: insert testing pyramid comparison diagram here -->`
diff --git a/src/content/docs/blackbox/guides/ci-behavioral-gates.md b/src/content/docs/blackbox/guides/ci-behavioral-gates.md
new file mode 100644
index 0000000..6428f20
--- /dev/null
+++ b/src/content/docs/blackbox/guides/ci-behavioral-gates.md
@@ -0,0 +1,126 @@
+---
+title: "Configure CI Gates"
+description: "Show how to gate feature drift, catalog changes, forbidden effects, and coverage reports in CI."
+sidebar_position: 7
+keywords: ["ci integration", "behavioral verification gate", "feature drift ci"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "behavioral verification gate"
+ secondary_keywords: ["ci integration", "feature drift ci", "blackbox ci"]
+ search_intent: "CI setup intent from teams gating feature drift, effect coverage, and runtime evidence in pull requests"
+ snippet_angle: "show a practical CI gate using feature checks, project system tests, report artifacts, and Blackbox exit codes"
+---
+
+Developers and platform teams use this page to turn Blackbox from a local proof run into a repeatable pull-request gate.
+
+There are two families of gates:
+
+| Gate family | What it protects |
+| --- | --- |
+| Feature and BDD gates | Scenario grammar, Gherkin syntax, and feature-file drift |
+| Runtime behavior gates | System-test execution, effect catalogs, forbidden effects, effect coverage, OMC/DC, and optional observation comparison |
+
+Use both when feature files are part of the workflow. Use only the runtime gates when the team does not want Gherkin.
+
+## Minimal Gate
+
+A practical first CI gate has two parts:
+
+```bash
+pnpm exec blackbox features lint ./tests --fail-on error
+pnpm exec blackbox features check --features ./features --tests ./tests --json
+pnpm test:system
+```
+
+The first command checks the AAA/Given-When-Then grammar. The second command is read-only and checks Gherkin syntax plus feature-file drift. The third command is your project-owned system-test command. In the showcase repository, `pnpm test:system` runs Playwright through the Blackbox testbed and writes `.blackbox-coverage/` artifacts.
+
+If you do not use feature files, skip the first two commands and start with the system-test command plus effect coverage.
+
+## Feature Gates
+
+Feature gates answer: is the readable behavior artifact still valid and synchronized?
+
+| Command | Blocks on |
+| --- | --- |
+| `blackbox features lint` | Bad behavior grammar: no action, no assertion, `Given` after `When`, opaque generated steps, unresolved placeholders |
+| `blackbox features check` | Gherkin syntax failure or feature-file drift |
+| `blackbox features drift` | Missing, stale, orphaned, or unparseable `.feature` files |
+
+`features check` uses the Cucumber Gherkin parser for syntax validation. It does not require Cucumber step definitions.
+
+## Runtime Behavior Gates
+
+Runtime behavior gates answer: did the running system still do the required things and avoid forbidden things?
+
+The normal project command is still the center:
+
+```bash
+pnpm test:system
+```
+
+That command should run the controlled system or E2E suite and fail when matchers, catalogs, or required/forbidden effects fail.
+
+When you are migrating tests or reshaping Playwright into the BDD DSL, add the experimental observation comparison gate:
+
+```bash
+pnpm exec blackbox features compare-observations --baseline ./baseline-observations --candidate ./candidate-observations --json
+```
+
+This is a behavioral drift gate over `.observation.json` files. It treats step-boundary changes as benign, but fails on meaningful changes such as missing network calls, changed payloads, changed assertions, missing tests, or different outcomes.
+
+## Optional Report Replay
+
+If CI saves `.blackbox-coverage/`, reports can be regenerated without rerunning the system:
+
+```bash
+pnpm exec blackbox coverage replay --coverage-dir .blackbox-coverage --out reports
+```
+
+Use `--no-html` when an agent or script only needs the JSON and Markdown propagation reports:
+
+```bash
+pnpm exec blackbox coverage replay --coverage-dir .blackbox-coverage --out reports --no-html
+```
+
+## What Should Block A Merge
+
+Block on:
+
+1. `features lint` errors when feature files are part of the workflow.
+2. Feature syntax failure or feature-file drift from `features check`.
+3. System-test failure from the project test command.
+4. Missing required effects or observed forbidden effects in the effect coverage gate.
+5. Meaningful observation differences during migration or reshape validation.
+6. OMC/DC findings that your team has decided are blocking, such as `masking-candidate` in critical paths.
+
+Report but do not automatically block on every generated artifact change. Intentional behavior changes should update feature files and effect catalogs through review.
+
+## Artifacts To Upload
+
+Upload `.blackbox-coverage/` when a run fails or when reviewers need evidence.
+
+Useful artifacts include:
+
+1. `omcdc-propagation.md`
+2. `omcdc-propagation.json`
+3. `omcdc.html`
+4. `coverage.json`
+5. `shape-coverage.json`
+6. `html/index.html`
+7. `features/*.feature` diffs when feature files are generated artifacts
+8. `observations/**/*.observation.json` when using observation comparison
+
+## GitHub Actions Sink
+
+When `GITHUB_ACTIONS=true`, the default sink expands to file output plus GitHub Actions annotations. The GitHub Actions sink reads `omcdc-propagation.json` and emits annotations for actionable verdicts:
+
+1. `masking-candidate` becomes a warning.
+2. `coverage-gap` becomes a notice.
+
+## Exit-Code Policy
+
+1. Treat exit `0` as pass.
+2. Treat exit `1` from `features check`, `features drift`, `features lint`, and `features compare-observations` as a useful gate finding.
+3. Treat exit `2` as setup, input, or transform failure that needs investigation.
+
+See [Exit Codes](/docs/blackbox/reference/exit-codes) for command-specific behavior.
diff --git a/src/content/docs/blackbox/guides/generating-feature-files.md b/src/content/docs/blackbox/guides/generating-feature-files.md
new file mode 100644
index 0000000..7cd60e3
--- /dev/null
+++ b/src/content/docs/blackbox/guides/generating-feature-files.md
@@ -0,0 +1,199 @@
+---
+title: "Generating Feature Files"
+description: "Generate Gherkin feature files from Playwright or Blackbox BDD-DSL tests, then gate syntax and feature-file drift."
+sidebar_position: 3
+keywords: ["playwright bdd", "given when then", "gherkin syntax", "feature file generation"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "playwright bdd"
+ secondary_keywords: ["given when then", "gherkin syntax", "feature file generation", "feature-file drift"]
+ search_intent: "practical BDD workflow for Playwright users who want readable behavior artifacts without Cucumber-style maintenance cost"
+ snippet_angle: "generate Given/When/Then feature files from Playwright tests, validate Gherkin syntax, and gate feature-file drift"
+---
+
+Blackbox can generate reviewable `.feature` files from Playwright tests and Blackbox BDD-DSL tests. That gives teams a BDD-style artifact without forcing Cucumber-style step definitions to become the main workflow.
+
+This guide is the practical path: check the test grammar, emit Gherkin, verify syntax, and gate feature-file drift.
+
+## Why Generate Feature Files?
+
+Feature files are useful because they give behavior a shared language. A reviewer can read a scenario without understanding every test helper, fixture, span, or assertion. The failure mode is that hand-written feature files can drift from what the system actually does.
+
+Blackbox uses the opposite flow:
+
+1. Start from a system or E2E test.
+2. Analyze the test into a behavior trace.
+3. Generate or check the `.feature` file.
+4. Review feature-file drift when the artifact changes.
+5. Use runtime evidence and effect coverage for stronger behavior proof.
+
+That keeps the artifact closer to executable behavior.
+
+## Playwright BDD Without The Cucumber Tax
+
+Traditional Playwright BDD often starts with a feature file, binds each step to code, then asks the team to keep the step definitions and feature text synchronized forever.
+
+Blackbox does not require that flow. You can keep Playwright as the runner and use Blackbox to produce BDD-shaped output after the run. The generated feature file helps people read and review behavior, but the runtime evidence remains the source of proof.
+
+| Approach | Source of truth | Maintenance cost | Best fit |
+| --- | --- | --- | --- |
+| Hand-written Gherkin | Feature file and step bindings | High if behavior changes often | Teams committed to BDD as the primary workflow |
+| Plain Playwright | Test code | Lower, but less product-readable | Engineering-only test suites |
+| Blackbox-generated feature files | Test source, plus runtime evidence when effects are enabled | Review feature-file drift instead of maintaining every sentence by hand | System and E2E behavior proof |
+
+## Given, When, Then
+
+Given/When/Then is still a useful shape:
+
+1. **Given** describes the starting state or context.
+2. **When** describes the action or workflow.
+3. **Then** describes the expected externally visible behavior.
+
+Blackbox uses that shape as a readable representation of executable behavior. The difference is that the feature text is checked against test source and can be paired with runtime effects, instead of being trusted as a standalone promise.
+
+The linter enforces the core grammar:
+
+```text
+Given* When+ Then+
+```
+
+`Then` matters. A scenario that never concludes in an observable assertion is not a useful behavior spec.
+
+## Step 1: Lint The Test Shape
+
+Run `features lint` before treating generated Gherkin as review material:
+
+```bash
+pnpm exec blackbox features lint ./tests --fail-on error
+```
+
+For CI or agent workflows:
+
+```bash
+pnpm exec blackbox features lint ./tests --json --fail-on warn
+```
+
+Important findings include:
+
+| Rule | What it catches |
+| --- | --- |
+| `aaa-shape` | `Then` before `When`, `Given` after the action, multiple act blocks after assertions, or no action |
+| `missing-then` | A scenario with no observable assertion |
+| `opaque-step` | A decompiled step that became too generic to review |
+| `placeholder-token` | A generated placeholder that does not resolve to example data |
+| `missing-background` | Repeated setup that should move to `Background` |
+
+## Step 2: Emit Feature Files
+
+Generate feature files from a test directory:
+
+```bash
+pnpm exec blackbox features emit ./tests --out ./features
+```
+
+For the showcase layout:
+
+```bash
+pnpm exec blackbox features emit ./e2e/tests --out ./e2e/features
+```
+
+If you have a step library:
+
+```bash
+pnpm exec blackbox features emit ./tests --steps ./scripts/step-lib.json
+```
+
+Or skip step resolution:
+
+```bash
+pnpm exec blackbox features emit ./tests --no-steps
+```
+
+The command prints the detected style and scope for each source file, then writes one `.feature` file per source file.
+
+## Step 3: Gate Syntax And Feature-File Drift
+
+Run `features check` after emitting:
+
+```bash
+pnpm exec blackbox features check --features ./features --tests ./tests
+```
+
+This performs two checks:
+
+1. Gherkin syntax validation using the Cucumber parser.
+2. Source-vs-feature drift detection.
+
+Use JSON in automation:
+
+```bash
+pnpm exec blackbox features check --features ./features --tests ./tests --json
+```
+
+Use `features drift` when you only want the synchronization check:
+
+```bash
+pnpm exec blackbox features drift --tests ./tests --features ./features
+```
+
+Feature-file drift kinds are `missing`, `stale`, `orphan`, and `unparseable`.
+
+## Step 4: Compare Runtime Observations When Migrating
+
+When reshaping tests or moving from plain Playwright into the BDD DSL, feature-file drift is not enough. You also need to know whether the rewritten test still produces the same meaningful runtime behavior.
+
+The experimental observation comparison gate reads `.observation.json` files from two runs:
+
+```bash
+pnpm exec blackbox features compare-observations --baseline ./baseline-observations --candidate ./candidate-observations --json
+```
+
+It treats step-boundary differences as benign and flags meaningful changes such as missing network calls, changed payloads, changed assertions, missing tests, or different outcomes.
+
+## What Changes In The Project
+
+A generation workflow should make these changes visible:
+
+1. A feature file is created or updated.
+2. Lint findings may point to weak scenario structure.
+3. `features check` can fail when feature files are missing, stale, orphaned, or unparseable.
+4. Runtime effect artifacts may also change if effects are enabled.
+5. Feature-file drift becomes a review event instead of an invisible mismatch.
+
+The exact filenames depend on the configured commands and output paths. The important rule is that generated artifacts should be treated as reviewable outputs, not as decorative documentation.
+
+## Reviewing Feature-File Drift
+
+A feature file change can mean several different things:
+
+1. The product behavior intentionally changed.
+2. The test source was renamed or restructured.
+3. The analyzer recovered clearer or weaker behavior text.
+4. Runtime behavior changed and the tests now express a new outcome.
+
+Do not auto-accept every generated change. Review the feature file beside the effect catalog and coverage report. If the behavior changed intentionally, update the catalog and accept the artifact. If it changed accidentally, fix the system or the test.
+
+## FAQ
+
+### Is this still BDD?
+
+It keeps the readable Given/When/Then artifact, but it does not require feature files to be the primary source of truth.
+
+### Do I need Cucumber?
+
+No. Blackbox uses Gherkin as a format and the Cucumber parser for syntax validation. You do not need Cucumber step definitions to use this workflow.
+
+### Should I write tests in the BDD DSL?
+
+Use the BDD DSL when you want faithful feature generation and explicit `scenario`, `given`, `when`, `then`, `background`, and `given.each` structure. Plain Playwright can work, but decompilation is best-effort.
+
+### Should generated feature files be committed?
+
+Commit them only when your team wants them as durable review artifacts. If they are temporary diagnostics, keep them out of version control.
+
+## What To Read Next
+
+1. [Feature Files, BDD, and Staleness](/docs/blackbox/concepts/feature-files-and-staleness)
+2. [Effects, Runtime, and Specs](/docs/blackbox/concepts/bdd-runtime-and-effects)
+3. [Writing Scenarios](/docs/blackbox/guides/writing-scenarios)
+4. [Files and Artifacts](/docs/blackbox/reference/files-and-artifacts)
diff --git a/src/content/docs/blackbox/guides/reading-coverage-reports.md b/src/content/docs/blackbox/guides/reading-coverage-reports.md
new file mode 100644
index 0000000..a93955a
--- /dev/null
+++ b/src/content/docs/blackbox/guides/reading-coverage-reports.md
@@ -0,0 +1,112 @@
+---
+title: "Reading Coverage Reports"
+description: "Explain coverage.json, shape-coverage.json, and how to read proven versus unasserted behavior."
+sidebar_position: 4
+keywords: ["coverage reports", "coverage json", "shape coverage"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "reading coverage reports"
+ secondary_keywords: ["coverage reports", "coverage json", "omcdc report", "shape coverage"]
+ search_intent: "practical troubleshooting and review intent after a user has generated Blackbox report files"
+ snippet_angle: "teach the reading order for OMC/DC, catalog coverage, shape coverage, HTML reports, and CI annotations"
+---
+
+## Abstract
+
+This page teaches the reading order for Blackbox reports: start with the human summary, inspect the OMC/DC verdicts, then use catalog and shape summaries to decide whether the run is acceptable.
+
+## Audience
+
+These pages are practical workflows for writing scenarios, asserting effects, generating artifacts, and gating behavior.
+
+## Start With The Question
+
+Before opening raw JSON, decide what you are trying to answer:
+
+1. Did a required effect disappear?
+2. Did a forbidden effect happen?
+3. Did a catalog entry remain uncovered?
+4. Did a branch exercise both arms but produce indistinguishable effects?
+5. Did a test run produce no useful runtime evidence?
+
+## Recommended Reading Order
+
+1. Open `omcdc-propagation.md` for a quick human-readable overview.
+2. Open `omcdc.html` when you need branch-level inspection or source snippets.
+3. Check `coverage.json` to see catalog entries that were satisfied, failed, or uncovered.
+4. Check `shape-coverage.json` to see asserted, unasserted, and inline boundary shapes.
+5. Use `omcdc-propagation.json` when automation or an agent needs the full structured result.
+6. Use span and V8 files only when debugging the evidence path itself.
+
+## Example: Subscription Flow
+
+The showcase report includes a `POST /subscriptions` section from the subscription workflow. In one saved run, 7 tests exercised that endpoint.
+
+The report showed:
+
+1. 4 `propagating` branches.
+2. 0 `masking-candidate` branches.
+3. 9 `coverage-gap` branches.
+
+That is a useful first report because it teaches two things at once. Some decisions are already proven by distinguishable runtime effects, while other decisions still need better scenarios before the report can claim stronger proof.
+
+For the same workflow, the effect contract requires the important cross-boundary behavior: Redis read, Postgres user lookup, payment intent HTTP call, subscription insert, Redis cache write, order-service call, and SQS message. It also forbids destructive or wrong effects such as Postgres `DELETE`, `TRUNCATE`, Redis `DEL`, Redis `FLUSHDB`, and refund creation.
+
+Read the report against that contract. The question is not only whether `POST /subscriptions` returned `201`. The question is whether the run produced the behavior the system promised at the boundary.
+
+## Reading OMC/DC Verdicts
+
+The OMC/DC report groups branches by endpoint. Each branch row has a source coordinate, counts for true-arm tests, false-arm tests, not-observed tests, and a verdict.
+
+| Verdict | Meaning | Typical action |
+| --- | --- | --- |
+| `propagating` | The branch arms produced distinguishable observed effects. | Usually good; review whether the effects are the intended ones. |
+| `masking-candidate` | Both arms ran, but their observed effect signatures looked identical. | Add better tests, more distinguishing effects, or enable function spans when appropriate. |
+| `coverage-gap` | One or more arms were not observed enough to make the decision useful. | Add or adjust a scenario. |
+| `undecidable` | The engine could not make a useful decision from the available evidence. | Inspect instrumentation and source mapping. |
+| `multi-arm` | The decision shape is more complex than the simple two-arm case. | Review manually and simplify or split if needed. |
+| `unsupported-mcdc` | The current engine does not support this decision shape. | Treat as an alpha limitation, not a pass. |
+
+## Reading Catalog Coverage
+
+`coverage.json` works at the catalog-entry level. It answers whether each named behavior contract was satisfied by at least one run.
+
+The most important states are:
+
+1. `satisfied`: at least one run matched the entry without missing required effects or observing forbidden effects.
+2. `failed`: the entry was exercised, but required or forbidden behavior failed.
+3. `uncovered`: no passing run satisfied the entry.
+
+Use this file for CI summaries and for tracking whether critical behavior contracts are still exercised.
+
+## Reading Shape Coverage
+
+`shape-coverage.json` works below the catalog-entry level. It tracks individual boundary shapes such as a Redis read, Postgres insert, HTTP call, or SQS message.
+
+The most useful review signal is the difference between:
+
+1. `unasserted`: the catalog declares the shape, but no matcher named it.
+2. `inline`: a test asserted the shape inline, but the catalog does not yet own it.
+
+Those states help teams decide whether the catalog is too large, too stale, or missing behavior that tests already depend on.
+
+## Practical Guidance
+
+1. Start with Markdown or HTML, not raw JSON.
+2. Treat `masking-candidate` as a design smell in the evidence, not automatically as an application bug.
+3. Treat `coverage-gap` as missing proof, not as proof of wrong behavior.
+4. Review catalog and feature changes together when behavior intentionally changes.
+5. Archive the full `.blackbox-coverage/` directory for failed CI runs so the evidence path can be inspected later.
+
+For the subscription example, a reviewer should usually open artifacts in this order:
+
+1. `e2e/features/subscribe-flow.feature` to understand the behavior in product terms.
+2. `e2e/tests/__effects__/00-baseline-subscribe.system.effects.yaml` to see the required and forbidden effects.
+3. `.blackbox-coverage/omcdc-propagation.md` to see branch verdicts and hints.
+4. `.blackbox-coverage/omcdc.html` when the Markdown summary is not enough.
+
+## Figure Placeholder
+
+**Caption:** Reading the subscription-flow report from feature file to effects YAML to OMC/DC verdicts.
+
+**Slot:** `<!-- TODO: insert annotated screenshot of POST /subscriptions in omcdc.html with the matching effects YAML beside it -->`
diff --git a/src/content/docs/blackbox/guides/using-the-testbed.md b/src/content/docs/blackbox/guides/using-the-testbed.md
new file mode 100644
index 0000000..c06ca1c
--- /dev/null
+++ b/src/content/docs/blackbox/guides/using-the-testbed.md
@@ -0,0 +1,145 @@
+---
+title: "Run with the Testbed"
+description: "Run a controlled Playwright and OpenTelemetry testbed so Blackbox can collect system-test evidence."
+sidebar_position: 5
+keywords: ["playwright opentelemetry", "testcontainers playwright", "docker compose testing", "blackbox testbed"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "playwright opentelemetry"
+ secondary_keywords: ["testcontainers playwright", "docker compose testing", "blackbox testbed"]
+ search_intent: "practical setup intent from teams running Playwright against containerized or composed systems"
+ snippet_angle: "show how a controlled testbed collects OpenTelemetry evidence during a Playwright system test"
+---
+
+## Abstract
+
+The Blackbox testbed is the controlled path for running a real system test and collecting runtime evidence. It stands up the system topology, runs the workflow through Playwright or a compatible runner, and routes OpenTelemetry evidence into Blackbox artifacts.
+
+Use this page when you want a repeatable first topology before adapting Blackbox to your own Docker Compose or Testcontainers setup.
+
+## Audience
+
+Developers wiring Blackbox into a local system-test environment, CI job, or sample project.
+
+## What The Testbed Proves
+
+The testbed is not only a demo harness. It teaches the shape Blackbox expects from a useful system test:
+
+1. A running service or service topology.
+2. Managed dependencies such as databases, queues, caches, local services, or containers.
+3. Runtime instrumentation that emits OpenTelemetry spans during the run.
+4. A scenario that exercises a real boundary.
+5. Generated artifacts that can be reviewed after the run.
+
+That is why the testbed is the best first step before trying to wire Blackbox into a larger system.
+
+## Playwright And OpenTelemetry
+
+Playwright is the runner that drives the workflow. OpenTelemetry is the evidence channel that shows what happened across boundaries. Blackbox uses the run and the spans together:
+
+1. Playwright performs the action.
+2. The application emits spans and other observable facts.
+3. Blackbox maps those facts into effects.
+4. Reports and feature artifacts make the result reviewable.
+
+This is the practical meaning of a Playwright OpenTelemetry workflow in Blackbox: the test does not only pass or fail. It leaves behind evidence about the system behavior it caused.
+
+## What Happens During A Run
+
+The important user-facing point is that Blackbox does not ask you to rewrite your service images for observability. It runs your production-shaped containers with a generated test overlay.
+
+1. You run the Blackbox system-test command, usually through the project script that invokes Playwright.
+2. Your system-test setup builds or selects the OpenTelemetry bootstrap image.
+3. Playwright global setup reads the testbed config and the user's Docker Compose topology.
+4. Blackbox generates temporary compose overlays for instrumentation, debug ports, and worker isolation.
+5. An init container copies `/blackbox-otel` from the bootstrap image into a Docker volume.
+6. Each SUT container mounts that volume and shadows its Node binary with `bin/node-wrap`.
+7. The SUT still starts with its normal command, such as `node src/server.js`.
+8. `node-wrap` prepends `--require=/blackbox-otel/bootstrap.cjs` and then execs the real Node binary from the bootstrap volume.
+9. The bootstrap loads before app code and registers OpenTelemetry instrumentations.
+10. The test drives a workflow, spans are captured, and Blackbox writes reports after the run.
+
+The user-owned compose file is not modified on disk. The overlays are generated for the test run and then treated as testbed plumbing.
+
+## Why The Bootstrap Image Exists
+
+The bootstrap travels as a Docker image instead of a host `node_modules` bind mount. That matters because package managers such as pnpm can represent dependencies as symlinks that do not survive cleanly when mounted into another container filesystem.
+
+The image contains real files:
+
+1. `bootstrap.cjs`, the OpenTelemetry preload entrypoint.
+2. `node_modules/`, with the OpenTelemetry SDK and instrumentations.
+3. `bin/node-wrap`, the shell wrapper mounted over the SUT `node` binary.
+4. `bin/real-node`, the Node binary the wrapper delegates to.
+
+This keeps the user's package manager out of the instrumentation path.
+
+## Why Blackbox Shadows `node`
+
+Docker Compose environment merging is key-based. If Blackbox simply set `NODE_OPTIONS=--require=/blackbox-otel/bootstrap.cjs`, it could overwrite a value the user's image, compose file, or env file already set.
+
+Instead, the wrapper composes `NODE_OPTIONS` inside the container after the final environment has already been resolved. It preserves existing flags, prepends the Blackbox bootstrap, and avoids double-prepending when child Node processes start.
+
+Blackbox also avoids overriding the service entrypoint. Overriding entrypoint can drop the image command, which would force the testbed to reconstruct every service command. Shadowing `node` keeps the service startup path closer to what the image already declares.
+
+## Testcontainers And Docker Compose
+
+Blackbox does not require one topology tool. The important distinction is whether the dependencies are managed by the test run.
+
+| Setup | Best for | Blackbox concern |
+| --- | --- | --- |
+| Testbed | Fastest known-good path | Learn the expected topology and artifacts |
+| Testcontainers | Per-test managed dependencies | Keep services isolated and observable |
+| Docker Compose | Existing multi-service local stack | Make sure services, networks, and telemetry are wired consistently |
+| Remote E2E environment | Production-like journey | Expect more unmanaged dependency noise |
+
+System tests usually make better behavioral gates when dependencies are controlled. E2E environments are still useful, but failures may come from auth, email, payment, vendor APIs, or shared infrastructure rather than the behavior under test.
+
+## Minimal Workflow
+
+A good first run should answer four questions:
+
+1. Did the topology start?
+2. Did the scenario exercise the boundary?
+3. Did spans arrive?
+4. Did Blackbox write artifacts?
+
+Do not start by optimizing the whole pipeline. Start with one behavior and one output directory. Once the first proof run works, expand the catalog, reports, and CI gate.
+
+## Expected Artifacts
+
+A successful run should produce some combination of:
+
+1. Runtime evidence from the scenario.
+2. Feature files or observation output.
+3. Effect catalog or catalog coverage output.
+4. OMC/DC coverage artifacts such as `omcdc-propagation.json`, `omcdc-propagation.md`, and `omcdc.html`.
+5. Logs or diagnostics for the run.
+
+The exact filenames depend on the command and configuration. The reference page [Files and Artifacts](/docs/blackbox/reference/files-and-artifacts) owns the complete inventory.
+
+## Common Failure Points
+
+If the first run fails, check these in order:
+
+1. The service did not start or was not reachable from the runner.
+2. The scenario passed through the wrong host, port, or network.
+3. The bootstrap image was not built, pulled, or mounted into the SUT container.
+4. The service did not start through the Node binary path Blackbox shadowed.
+5. The wrapper loaded, but existing tracing configuration conflicted with the Blackbox bootstrap.
+6. Artifacts were written somewhere different from the path you inspected.
+
+## Figure Placeholder
+
+**Caption:** A system-test run from Playwright to Docker Compose overlays, `node-wrap`, OpenTelemetry spans, and `.blackbox-coverage/` artifacts.
+
+**Slot:** `<!-- TODO: insert testbed run-flow diagram or short animated walkthrough here -->`
+
+Use [No Spans Captured](/docs/blackbox/troubleshooting/no-spans-captured) when the test runs but no runtime evidence appears. Use [Docker and Testbed](/docs/blackbox/troubleshooting/docker-and-testbed) when the topology itself fails.
+
+## What To Read Next
+
+1. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
+2. [Writing Scenarios](/docs/blackbox/guides/writing-scenarios)
+3. [Reading Coverage Reports](/docs/blackbox/guides/reading-coverage-reports)
+4. [Files and Artifacts](/docs/blackbox/reference/files-and-artifacts)
diff --git a/src/content/docs/blackbox/guides/writing-scenarios.md b/src/content/docs/blackbox/guides/writing-scenarios.md
new file mode 100644
index 0000000..047c730
--- /dev/null
+++ b/src/content/docs/blackbox/guides/writing-scenarios.md
@@ -0,0 +1,95 @@
+---
+title: "Writing Scenarios"
+description: "Write scenarios and effect assertions that connect system tests to observability testing, span assertions, and Blackbox behavior proof."
+sidebar_position: 1
+keywords: ["observability testing", "span assertions", "trace assertions", "otel testing", "given when then"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "observability testing"
+ secondary_keywords: ["span assertions", "trace assertions", "otel testing", "otel test coverage", "given when then"]
+ search_intent: "practical intent from teams turning observed traces and spans into test assertions"
+ snippet_angle: "observability testing becomes useful when spans and effects are tied to required and forbidden behavior"
+---
+
+## Abstract
+
+A Blackbox scenario is the bridge between a system test and behavioral proof. It names the workflow, exercises the boundary, and gives Blackbox enough structure to compare observed effects against what the team expects.
+
+This page also owns the material that used to sit in a separate asserting-effects guide: how scenarios, span assertions, trace assertions, and required or forbidden effects work together.
+
+## Audience
+
+Developers writing Blackbox scenarios against system tests, Playwright flows, Docker Compose stacks, Testcontainers setups, or other controlled runtime environments.
+
+## Scenario Shape
+
+A useful scenario has three jobs:
+
+1. Establish the starting state.
+2. Exercise a real workflow.
+3. Assert the effects that must or must not appear.
+
+The exact DSL can vary by runner and API surface, but the mental model stays close to Given, When, Then:
+
+1. **Given** the system starts from a known state.
+2. **When** the workflow runs.
+3. **Then** required effects appear and forbidden effects stay absent.
+
+Do not start with every workflow. Start with one behavior whose boundary effects matter.
+
+## Observability Testing Vs Effect Assertions
+
+Observability testing is useful when traces, spans, logs, and runtime facts help explain what happened during a test. By itself, observability does not decide whether the behavior is acceptable.
+
+Blackbox adds the assertion layer:
+
+| Evidence | Useful question | Blackbox layer |
+| --- | --- | --- |
+| Span | Did this operation happen? | Span assertion or effect builder |
+| Trace | Did the workflow cross expected boundaries? | Trace assertion or runtime evidence review |
+| Effect | Did the externally visible behavior happen? | Required effect |
+| Missing effect | Did expected behavior disappear? | Catalog failure |
+| Extra effect | Did forbidden behavior appear? | Forbidden effect |
+
+The goal is not to assert every span. The goal is to assert the effects that represent product or system behavior.
+
+## Requires And Forbids In A Scenario
+
+Required effects are positive assertions. They describe what must happen if the scenario is correct.
+
+Forbidden effects are negative assertions. They describe what must not happen, even if the main path succeeds.
+
+Good examples:
+
+1. Require an event publication after a successful order.
+2. Require a database write after a user update.
+3. Forbid a deprecated downstream API call.
+4. Forbid duplicate queue messages during retry.
+
+Weak examples:
+
+1. Assert every internal helper span.
+2. Assert private implementation details that do not matter to the boundary.
+3. Treat every observed span as a required behavior without review.
+
+## Working With OpenTelemetry
+
+OpenTelemetry gives Blackbox the runtime facts. The scenario gives those facts meaning.
+
+A practical OTEL testing workflow is:
+
+1. Instrument the system under test.
+2. Run one system or E2E scenario.
+3. Capture spans and related runtime evidence.
+4. Map the evidence into effects.
+5. Promote important effects into required or forbidden behavior.
+6. Let future runs fail when the behavior drifts.
+
+This is where span assertions and trace assertions become behavior assertions. They are not only debugging tools; they become part of the verification gate.
+
+## What To Read Next
+
+1. [Requires and Forbids](/docs/blackbox/concepts/requires-and-forbids)
+2. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
+3. [System Effects](/docs/blackbox/concepts/system-effects)
+4. [Scenario DSL](/docs/blackbox/reference/scenario-dsl)
diff --git a/src/content/docs/blackbox/lifecycle/agentic-workflow.md b/src/content/docs/blackbox/lifecycle/agentic-workflow.md
new file mode 100644
index 0000000..339e23f
--- /dev/null
+++ b/src/content/docs/blackbox/lifecycle/agentic-workflow.md
@@ -0,0 +1,97 @@
+---
+title: "AI-Assisted Workflow"
+description: "Explain how Blackbox gives coding agents an external behavioral checker without making the docs depend on AI."
+sidebar_position: 3
+keywords: ["agentic workflow", "agentic output verification", "ai behavioral testing", "verification gate"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "agentic workflow"
+ secondary_keywords: ["agentic output verification", "ai behavioral testing", "ai coding agents"]
+ search_intent: "teams designing agentic development loops with deterministic verification gates"
+ snippet_angle: "an agentic workflow needs a checker outside the agent, based on runtime behavior rather than prose"
+---
+
+## Abstract
+
+Blackbox gives AI-assisted development a stable verification loop: implement, exercise the system, observe runtime effects, compare them to the catalog, and hand evidence back to the developer for review.
+
+The same loop also helps ordinary scripts, CI jobs, and human developers. Keep this page AI-aware, but not AI-dependent.
+
+## Audience
+
+Teams using coding agents or automation while keeping a deterministic behavioral gate outside the implementation loop.
+
+## The Agent Problem
+
+Agents need stop conditions. If the only stop condition is "tests are green" or "the task list is checked," the agent can miss behavior the tests did not assert, drift from the spec, or declare completion without runtime proof.
+
+Blackbox does not make the agent trustworthy by itself. It gives the workflow an external checker that is tied to observed behavior.
+
+## Recommended Loop
+
+1. The agent reads the task, existing tests, catalog, and reports.
+2. The agent makes one reviewable implementation change.
+3. The system test or E2E suite runs against the real boundary.
+4. Blackbox collects spans and produces effect coverage artifacts.
+5. The agent reads the report and fixes missing or forbidden effects.
+6. The agent hands the diff, report, and remaining uncertainty to a human reviewer.
+
+## Agent Command Loop
+
+Agents should prefer read-only checks before state-changing commands:
+
+```bash
+pnpm exec blackbox features check --features ./features --tests ./tests --json
+pnpm test:system
+pnpm exec blackbox coverage replay --coverage-dir .blackbox-coverage --no-html
+```
+
+When an agent needs to reshape tests, it should run the dry-run path first:
+
+```bash
+pnpm exec blackbox features reshape ./tests/my.spec.ts --dry-run
+```
+
+State-changing commands such as `features emit`, `features reshape --write`, `features experimental wrap --write`, and `features experimental scaffold --write` should produce a reviewable diff. They should not be treated as automatic truth.
+
+## Agentic Output Verification
+
+Agentic output verification means the agent's work is checked against evidence outside the agent. In Blackbox, that evidence comes from runtime effects, catalogs, reports, and exit codes.
+
+The workflow should not ask the same agent to be the sole author and final judge. It should give the agent a behavioral report it can react to, then leave merge decisions to a human or CI policy.
+
+## Maker And Checker Split
+
+For higher-risk work, separate the implementation role from the verification role:
+
+1. The maker changes code.
+2. The checker runs Blackbox and reads artifacts from disk.
+3. The checker reports pass, fail, or uncertain against explicit criteria.
+4. The human decides whether the behavioral evidence is enough to merge.
+
+This matches the direction shown by loop-engineering discussions in the Spec Kit ecosystem, but the page should not depend on any specific agent, model, IDE, or prompt system.
+
+## What Blackbox Provides
+
+1. Stable artifacts an agent can parse: reports, catalogs, generated feature files, and exit codes.
+2. A behavioral signal outside the agent's prose reasoning.
+3. A way to detect missing required effects and forbidden effects.
+4. A review artifact that humans can inspect without trusting the agent's summary.
+
+## Useful Structured Outputs
+
+1. `features check --json` reports feature syntax and source/feature drift.
+2. `features lint --json` reports structural findings.
+3. `features compare-observations --json` reports experimental observation drift.
+4. `omcdc-propagation.json`, `coverage.json`, and `shape-coverage.json` report runtime coverage evidence.
+
+## What This Loop Does Not Prove
+
+1. It does not replace a human owner for product intent.
+2. It does not prove every requirement in a written spec.
+3. It does not remove the need for instrumentation, scenario design, or system tests.
+4. It should not be documented as a direct Spec Kit command until that integration exists.
+
+## Command Safety
+
+Agents should treat exit code `1` from drift, check, lint, or compare commands as a useful finding, not a crash. Exit code `2` usually means the command could not produce a trustworthy result because inputs, directories, or transforms failed.
diff --git a/src/content/docs/blackbox/lifecycle/developer-workflow.md b/src/content/docs/blackbox/lifecycle/developer-workflow.md
new file mode 100644
index 0000000..488a9bf
--- /dev/null
+++ b/src/content/docs/blackbox/lifecycle/developer-workflow.md
@@ -0,0 +1,72 @@
+---
+title: "Developer Workflow"
+description: "Explain the human workflow: edit a scenario, run Playwright, inspect evidence, update the catalog, commit, and gate CI."
+sidebar_position: 2
+keywords: ["developer workflow", "playwright system tests", "blackbox developer lifecycle"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "developer workflow"
+ secondary_keywords: ["playwright system tests", "blackbox developer lifecycle", "feature drift"]
+ search_intent: "workflow intent from developers using Blackbox during local implementation and review"
+ snippet_angle: "show the local loop: edit, emit/check feature files, run system tests, read reports, and review catalog changes"
+---
+
+## Abstract
+
+This page focuses on the person doing the work locally: edit a scenario, run the system test, inspect evidence, update the catalog when behavior intentionally changes, and decide whether the change is ready.
+
+## Audience
+
+Developers adding Blackbox to daily local work without changing their main runner or editor habits.
+
+## The Human Loop
+
+1. Edit a scenario, system test, or effect catalog entry.
+2. Generate or check feature files when they are part of the workflow.
+3. Run the project-owned system-test command.
+4. Inspect the OMC/DC, catalog, shape, and feature artifacts.
+5. Decide whether implementation, tests, feature files, or effect contracts should change.
+6. Commit only the durable artifacts that belong in review.
+
+## Local Commands
+
+```bash
+pnpm exec blackbox features emit ./tests --out ./features
+pnpm exec blackbox features check --features ./features --tests ./tests
+pnpm test:system
+```
+
+Use `features emit` when executable tests changed and feature artifacts should be refreshed. Use `features check` when you want a read-only syntax and drift gate. Use the project script, such as `pnpm test:system`, to actually run the system and produce runtime evidence.
+
+For reshaping existing Playwright tests into the Blackbox closure DSL, preview first:
+
+```bash
+pnpm exec blackbox features reshape ./tests/my.spec.ts --dry-run
+```
+
+Only write after reviewing the preview:
+
+```bash
+pnpm exec blackbox features reshape ./tests/my.spec.ts --write
+```
+
+## What The Developer Reviews
+
+1. The behavior that was observed.
+2. The required and forbidden effects.
+3. Whether the feature file still matches the run.
+4. Whether the catalog should change or the implementation should change.
+
+Generated reports usually stay out of git. Feature files and effect catalogs are committed only when they are part of the durable behavior contract.
+
+## Workflow Boundaries
+
+1. CI gate policy belongs in The Blackbox Lifecycle.
+2. Agent-specific workflows belong in AI-Assisted Workflow.
+3. CLI syntax belongs in Reference.
+
+## Figure Placeholder
+
+**Caption:** A developer using Blackbox to verify a change before merge.
+
+**Slot:** `<!-- TODO: insert editor-to-report workflow screenshot or GIF here -->`
diff --git a/src/content/docs/blackbox/lifecycle/the-blackbox-lifecycle.md b/src/content/docs/blackbox/lifecycle/the-blackbox-lifecycle.md
new file mode 100644
index 0000000..2a8c852
--- /dev/null
+++ b/src/content/docs/blackbox/lifecycle/the-blackbox-lifecycle.md
@@ -0,0 +1,81 @@
+---
+title: "The Blackbox Lifecycle"
+description: "Show the full cycle from intent to system scenario, runtime effects, feature file, catalog, report, and CI gate."
+sidebar_position: 1
+keywords: ["continuous verification", "blackbox lifecycle", "verification at runtime", "behavioral verification loop"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "continuous verification"
+ secondary_keywords: ["verification at runtime", "blackbox lifecycle", "behavioral verification loop"]
+ search_intent: "teams looking for a repeatable verification loop across local development, CI, and release decisions"
+ snippet_angle: "continuous verification is useful when every change can produce runtime evidence before it is trusted"
+---
+
+## Abstract
+
+Show the full cycle from intent to system scenario, runtime effects, feature file, catalog, report, verification, and decision.
+
+This page should be the map for the whole workflow: what happens, what artifacts appear, and where humans, scripts, CI, and agents each enter.
+
+## Audience
+
+Readers who need the whole mental model before choosing a guide or reference page.
+
+## The Cycle
+
+1. Intent: the team names the behavior they care about.
+2. Scenario: the system test or feature describes the run.
+3. Run: the boundary is exercised.
+4. Capture: runtime evidence is collected.
+5. Shape: Blackbox turns evidence into effects, catalog entries, and reports.
+6. Verify: the evidence is compared to required and forbidden behavior.
+7. Decide: the result becomes a local fix, a review artifact, or a CI gate.
+
+## Why This Loop Exists
+
+The loop exists so specs, tests, and runtime behavior do not drift apart without anyone noticing. The point is not to create more artifacts. The point is to make behavior visible enough to trust.
+
+This is Blackbox's version of continuous verification: verification at runtime, attached to the development loop, CI gate, and release decision. It is not a replacement for observability or deployment monitoring. It is a way to turn selected system-test runs into repeatable behavioral evidence.
+
+## Who Uses The Loop
+
+1. Developers, in the editor and terminal.
+2. Scripts, in CI or local automation.
+3. Agents, as one consumer of the same artifacts.
+4. Reviewers, who read the report before trusting the change.
+
+## What Each Actor Does
+
+1. Developers shape the scenario and interpret the result.
+2. Scripts move the proof through the pipeline.
+3. Agents can propose or update changes, but they do not become the source of truth.
+4. Reviewers decide whether the observed behavior is good enough to accept.
+
+## The Operational Loop
+
+1. Initialize or load configuration.
+2. Run the scenario or system test.
+3. Collect and normalize spans.
+4. Generate or compare the effect catalog.
+5. Emit reports and exit codes.
+6. Route the artifacts to files, stdout, or CI systems.
+
+This is the material that used to live in separate lifecycle pages. Keeping it here makes the workflow easier to scan.
+
+## What Belongs Later
+
+1. Exact command syntax belongs in Reference.
+2. Artifact destination details belong in Files and Artifacts.
+3. Testbed setup details belong in Guides and Quickstart.
+
+## Evidence To Add
+
+- A simple lifecycle diagram.
+- A concrete example of one run moving through the loop.
+- Links to developer workflow, AI-assisted workflow, and CI gate lifecycle.
+
+## Figure Placeholder
+
+**Caption:** The Blackbox lifecycle from intent to proof to decision.
+
+**Slot:** `<!-- TODO: insert lifecycle diagram or step-through animation here -->`
diff --git a/src/content/docs/blackbox/overview/system-test-effect-coverage.mdx b/src/content/docs/blackbox/overview/system-test-effect-coverage.mdx
new file mode 100644
index 0000000..796f9a6
--- /dev/null
+++ b/src/content/docs/blackbox/overview/system-test-effect-coverage.mdx
@@ -0,0 +1,133 @@
+---
+title: "System Test Effect Coverage"
+description: "Understand effect coverage as a system-test signal: runtime evidence of required, forbidden, and decision-sensitive behavior."
+sidebar_position: 3
+keywords: ["system test coverage", "effect coverage", "runtime evidence", "OMC/DC coverage", "code coverage"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "system test coverage"
+ secondary_keywords: ["effect coverage", "runtime evidence", "OMC/DC coverage", "behavioral verification", "code coverage"]
+ search_intent: "informational intent from teams comparing code coverage with runtime evidence from system tests"
+ snippet_angle: "system test effect coverage shows whether real test runs produced the required observable behavior, not only which code executed"
+---
+
+import OverviewDiagram from '@/components/blackbox/OverviewDiagram.astro';
+
+System test effect coverage asks a different question from traditional code coverage: when the system ran, did it produce the observable behavior the workflow depends on?
+
+Line coverage and branch coverage are useful inside a codebase. They tell you which statements and branches executed. Blackbox looks at the system from the outside-in. It records runtime evidence from system and E2E runs, then reports whether the important effects were observed, missed, forbidden, or not yet covered.
+
+That makes effect coverage a coverage model for system behavior. It is designed for the places where regressions are often visible only through outcomes: database writes, emitted events, downstream HTTP calls, cache changes, emails, queue messages, and other boundary effects.
+
+## The Input/Output Gap
+
+Traditional E2E tests usually prove that a workflow accepts the expected input and returns the expected output. They are weaker at proving the behavioral path between those two points.
+
+For system behavior, that middle path often matters most. A correct response can still hide a missing event, a skipped persistence step, a wrong cache mutation, a duplicate notification, or an unexpected downstream call.
+
+Effect coverage adds evidence for that middle path.
+
+## Why Code Coverage Is Not Enough
+
+A test can execute the right lines and still miss the behavior that matters.
+
+For example, a subscription endpoint might return `201 Created` while silently skipping the queue message that activates fulfillment. A refactor might keep the response body stable while changing a payment call. A generated implementation might satisfy the visible assertion while sending an extra email, omitting an audit record, or writing to the wrong table.
+
+Traditional coverage helps you see execution. It does not tell you whether the running system produced the effects the product, contract, or scenario requires.
+
+Blackbox treats those effects as first-class coverage targets. The goal is not to replace unit-level metrics. The goal is to add a system-level signal for behavior that only appears when services, storage, queues, caches, and APIs interact.
+
+<OverviewDiagram kind="coverage" />
+
+| Coverage signal | Main question | Common blind spot |
+| --- | --- | --- |
+| Line coverage | Which source lines ran? | Whether running those lines produced the required outcome |
+| Branch coverage | Which branches ran? | Whether each branch changed observable behavior |
+| Trace observability | What did the system emit? | Which emitted facts matter for the tested behavior |
+| System test effect coverage | Which required, forbidden, and decision-sensitive effects appeared? | It cannot prove every possible behavior outside the evidence collected |
+
+## Effects And Feature Files Are Different
+
+Effect coverage and feature files solve different problems.
+
+Effect coverage is runtime proof. It asks whether the system actually produced the required effects, avoided forbidden effects, and exposed decision-sensitive behavior during the run.
+
+Feature files are a readable behavior surface. They help humans and agents review the scenario in Gherkin, and Blackbox can check whether the `.feature` file drifted from the test source.
+
+Use effects when you need to prove runtime behavior. Use feature files when readable behavior matters. Use both when the team wants executable tests, runtime evidence, and readable scenarios to move together.
+
+The combined model is described in [Tests, Effects, and Feature Files](/docs/blackbox/overview/tests-effects-and-feature-files).
+
+## What Counts As An Effect
+
+An effect is an observable action the system performs while a workflow runs. In Blackbox, effects are usually captured from runtime evidence such as OpenTelemetry spans and classified into reviewable shapes.
+
+Common effect types include:
+
+1. Database reads and writes.
+2. HTTP calls to internal or external services.
+3. Queue messages and published events.
+4. Cache reads, writes, invalidations, and flushes.
+5. Email, notification, or webhook intents.
+6. File, object-storage, or other infrastructure-facing operations.
+
+The important point is not the transport. The important point is that the effect is something a system test can observe from the running system and a reviewer can connect to intended behavior.
+
+## Required And Forbidden Effects
+
+Effect coverage is both positive and negative.
+
+A checkout or subscription flow may require a user lookup, a payment intent, a subscription insert, a cache update, and an activation event. If a test passes without one of those effects, Blackbox can surface the missing behavior instead of leaving it hidden behind a response assertion.
+
+The same flow may forbid destructive or unexpected effects: refund creation, database deletes, table truncation, cache flushes, duplicate messages, or calls to a deprecated service. These forbidden effects matter during refactors because many regressions are not omissions. They are extra actions that should not have happened.
+
+Required and forbidden effects turn system tests into behavioral gates. A test is no longer only “the endpoint returned the expected response.” It also says “the system produced the effects this workflow requires, and avoided the effects this workflow must not produce.”
+
+## Runtime Evidence, Not Formal Proof
+
+Blackbox reports evidence from real executions. That distinction matters.
+
+The reports can show that a specific system run produced a required effect, missed one, violated a forbidden effect, or failed to distinguish an observable decision. They do not prove that every possible input, environment, or timing condition is correct.
+
+This is why effect coverage works best as a practical engineering gate. It gives reviewers concrete facts from the running system, then lets the team decide whether to add scenarios, adjust the effect catalog, improve instrumentation, or accept a known boundary.
+
+## How OMC/DC Relates
+
+Blackbox also reports OMC/DC-style coverage for system behavior. In this context, the useful question is: when a decision condition changes, does the system produce a distinguishable observable effect?
+
+Traditional MC/DC is usually discussed as a code-level coverage criterion for decisions and conditions. Blackbox applies a related idea at the system boundary. It looks for whether decision-sensitive behavior is visible in the runtime evidence collected from the test run.
+
+That can reveal several useful cases:
+
+1. A condition changed and produced a distinct observable effect.
+2. A branch executed but its effect was masked by later behavior.
+3. A decision appears important in code but is not distinguished by the current system evidence.
+4. A scenario needs better inputs or assertions because the current run cannot show the behavioral difference.
+
+OMC/DC is therefore a companion to effect coverage. Effect coverage asks whether required and forbidden effects appeared. OMC/DC asks whether meaningful decision changes are visible through the effects the system produced.
+
+## Why It Matters Now
+
+Modern development creates behavior faster than teams can manually inspect it. Refactors can move logic across services. Legacy modernization can preserve API shape while changing side effects. Spec-driven development can keep intent visible, but specs and feature files can still drift from the running system. AI-assisted development can generate plausible code that satisfies local assertions while missing a boundary effect.
+
+System test effect coverage gives those workflows a runtime checkpoint. It connects specs, scenarios, tests, and implementation back to evidence from the system that actually ran.
+
+That is useful before a refactor, because it captures the behavior you need to preserve. It is useful during a refactor, because it shows whether important effects changed. It is useful after a refactor, because it leaves behind reviewable artifacts that explain what the system now does.
+
+## What This Complements
+
+Effect coverage complements existing testing and observability practices:
+
+1. Unit tests still protect small pieces of logic quickly.
+2. Integration tests still validate direct collaboration between modules or managed dependencies.
+3. System and E2E tests still exercise real workflows.
+4. Tracing and logs still help debug production and test runs.
+5. Specs, BDD scenarios, and feature files still express intent.
+
+Blackbox adds the missing bridge between those layers: runtime evidence that the system-level behavior described by the tests and specs actually appeared during execution.
+
+## What To Read Next
+
+1. [Tests, Effects, and Feature Files](/docs/blackbox/overview/tests-effects-and-feature-files)
+2. [OMC/DC Coverage](/docs/blackbox/concepts/omc-dc-coverage)
+3. [Reading Coverage Reports](/docs/blackbox/guides/reading-coverage-reports)
diff --git a/src/content/docs/blackbox/overview/tests-effects-and-feature-files.mdx b/src/content/docs/blackbox/overview/tests-effects-and-feature-files.mdx
new file mode 100644
index 0000000..6c244b1
--- /dev/null
+++ b/src/content/docs/blackbox/overview/tests-effects-and-feature-files.mdx
@@ -0,0 +1,137 @@
+---
+title: "Tests, Effects, and Feature Files"
+description: "Understand the combined Blackbox loop: tests execute behavior, effects prove runtime boundaries, feature files make behavior readable, and gates keep them synchronized."
+sidebar_position: 2
+keywords: ["blackbox feature files", "effect coverage", "gherkin drift", "behavioral verification gate", "AI testing"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "behavioral verification gate"
+ secondary_keywords: ["effect coverage", "blackbox feature files", "gherkin drift", "AI testing"]
+ search_intent: "evaluating how Blackbox combines tests, runtime effects, feature files, and gates"
+ snippet_angle: "tests execute the workflow, effects prove runtime behavior, feature files make it readable, and gates keep the artifacts synchronized"
+---
+
+import OverviewDiagram from '@/components/blackbox/OverviewDiagram.astro';
+import BddReverseDemo from '@/components/blackbox/BddReverseDemo.astro';
+
+Blackbox is strongest when three artifacts stay connected:
+
+1. A system or E2E test that executes the behavior.
+2. Runtime effects that prove what the system actually did.
+3. A readable feature file when the team wants behavior expressed in Gherkin.
+
+You can use these layers separately. Effects are the core Blackbox layer. Feature files are optional. The combination matters because it turns a green test into a reviewable behavioral proof trail.
+
+<OverviewDiagram kind="proof-loop" />
+
+## The Three Artifacts
+
+Each artifact answers a different question.
+
+| Artifact | What it gives you | Question it answers |
+| --- | --- | --- |
+| System or E2E test | Executable behavior | Can we run the workflow again? |
+| Runtime effects | Evidence from the running system | What did the system actually do and avoid? |
+| Feature file | Human-readable behavior | Can reviewers, product people, and agents understand the intended behavior? |
+
+The mistake is treating one of them as a replacement for the others.
+
+A test without effects can pass while missing a required queue message, audit write, cache update, or downstream call. A feature file without a test can become stale documentation. Runtime evidence without a readable behavior surface can be hard to review outside the engineering team.
+
+Blackbox lets the layers reinforce each other.
+
+## Why The Combination Changes The Process
+
+Without this loop, many reviews stop at “the test is green.” That is often too thin for a refactor, migration, incident regression, or AI-generated change.
+
+With the loop, a behavior change has more surfaces:
+
+1. The test shows the workflow still executes.
+2. The effect catalog shows the required and forbidden runtime behavior.
+3. Effect coverage shows which effects were observed, missing, failed, or uncovered.
+4. The feature file shows the behavior in a readable scenario format.
+5. Drift checks show whether the readable behavior is still aligned with the test source.
+
+This changes the review from “does the assertion pass?” to “does the system still prove the behavior we care about?”
+
+That is the core Blackbox category: runtime-backed behavioral verification for system and E2E tests.
+
+## The Verification Gates
+
+The gates are deliberately layered. A team can start with only the runtime effect layer, then add feature-file gates when readable behavior specs become valuable.
+
+| Gate | Layer | What it protects |
+| --- | --- | --- |
+| Project system test | Test | The workflow still runs and assertions still pass |
+| Effect catalog matchers | Runtime effects | Required effects happened and forbidden effects stayed absent |
+| Effect coverage report | Runtime effects | The cataloged effects were actually covered by the run |
+| OMC/DC report | Runtime effects | Decision-sensitive behavior is distinguishable in observed effects |
+| `features lint` | Feature files | The scenario has a useful Given/When/Then shape |
+| `features check` / `features drift` | Feature files | The `.feature` file did not drift from the test source |
+| `features compare-observations` | Optional semantic comparison | Runtime observations did not change meaningfully during a reshape |
+
+These gates do not all need to block on day one. The important choice is to make the gate match the risk.
+
+For a first adoption, effect catalog matchers and effect coverage usually matter most. For a BDD-heavy or spec-driven team, feature-file drift becomes a useful second gate. For a large refactor, migration, or AI-assisted change, observation comparison can add another review surface.
+
+## You Can Adopt The Layers Separately
+
+Blackbox does not force a single methodology.
+
+| Adoption path | What you use | Best when |
+| --- | --- | --- |
+| Effects only | Runtime evidence, catalog, matchers, coverage | You already have system tests and want stronger behavioral proof |
+| Feature files only | `features emit`, lint, check, drift | You want readable scenarios generated from tests, even before effect gates |
+| Combined loop | Tests, effects, coverage, feature files, drift gates | You want executable behavior, runtime proof, and readable specs to move together |
+
+Effects are the must-have layer because they capture the missing middle of many E2E and system tests: what happened between input and output.
+
+Feature files add a different kind of value. They make behavior easier to review, discuss, and compare over time. They are especially useful when the team already uses BDD language, wants Gherkin artifacts, or is moving toward spec-driven development.
+
+## Why This Increases Confidence
+
+Confidence improves because the same behavior is checked from multiple angles.
+
+A system test proves the workflow can execute. The effect catalog proves the runtime boundaries that matter. The coverage report shows whether those effects were exercised. The feature file gives the behavior a readable form. The gates keep the artifacts synchronized.
+
+This is not formal proof. It is practical engineering evidence from a real run.
+
+That evidence is useful before a refactor because it records what the current system does. It is useful during a refactor because it shows exactly which behavior changed. It is useful after a refactor because it leaves behind artifacts future reviewers can inspect.
+
+## Why This Matters For AI-Assisted Development
+
+AI coding agents make implementation changes quickly. They can also update tests, prose, and feature files quickly. That speed makes external verification more important, not less.
+
+Blackbox gives the agentic workflow stop conditions outside the generated code:
+
+1. If the source test changed, feature-file drift exposes it.
+2. If the implementation changed behavior, runtime effects expose it.
+3. If required effects disappeared, coverage exposes it.
+4. If the readable scenario changed, the feature diff exposes it.
+5. If a refactor changes the runtime shape, observation comparison can expose it.
+
+This gives reviewers a better question to ask an agent: not “did you say the task is done?” but “which tests, effects, feature files, and gates prove the behavior?”
+
+## Where Gherkin And BDD Fit
+
+Blackbox uses Gherkin as a readable behavior format. It does not require Cucumber as the test runner, and it does not require teams to adopt classic BDD ceremony before getting value.
+
+The feature-file track is about keeping readable behavior close to executable behavior:
+
+1. Analyze existing Playwright or Blackbox scenario tests.
+2. Emit `.feature` files from the test source.
+3. Lint the Given/When/Then shape.
+4. Check whether the feature file drifted from the test.
+5. Optionally compare runtime observations across baseline and candidate runs.
+
+The result is not a promise that feature files will never go stale. It is a way to make staleness detectable.
+
+<BddReverseDemo />
+
+## What To Read Next
+
+1. [5-Minute Quickstart](/docs/blackbox/quickstart/first-proven-feature)
+2. [Feature Files From Tests](/docs/blackbox/quickstart/feature-files-from-tests)
+3. [System Test Effect Coverage](/docs/blackbox/overview/system-test-effect-coverage)
+4. [Feature Files, BDD, and Staleness](/docs/blackbox/concepts/feature-files-and-staleness)
+5. [Configure CI Gates](/docs/blackbox/guides/ci-behavioral-gates)
diff --git a/src/content/docs/blackbox/overview/what-is-blackbox.mdx b/src/content/docs/blackbox/overview/what-is-blackbox.mdx
new file mode 100644
index 0000000..75dc991
--- /dev/null
+++ b/src/content/docs/blackbox/overview/what-is-blackbox.mdx
@@ -0,0 +1,163 @@
+---
+title: "What is Blackbox?"
+description: "Suites Blackbox is runtime behavioral verification for controlled system tests, with E2E support."
+sidebar_position: 1
+keywords: ["blackbox overview", "system testing", "effect coverage", "behavioral verification"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "blackbox vs whitebox testing"
+ secondary_keywords: ["what is system testing", "effect coverage", "runtime evidence", "behavioral verification"]
+ search_intent: "top-of-funnel comparison intent from readers trying to place Blackbox in the testing landscape"
+ snippet_angle: "Blackbox is runtime behavioral verification for system tests and E2E tests, turning observed effects into reviewable proof"
+---
+
+import OverviewDiagram from '@/components/blackbox/OverviewDiagram.astro';
+
+Suites Blackbox is runtime behavioral verification for controlled system tests, with E2E support.
+
+It captures what a running system actually did during a real workflow, maps that evidence into effects, and lets reviewers or CI decide whether required behavior happened and forbidden behavior stayed absent.
+
+Use it when a passing response, UI assertion, or green E2E run is not enough proof.
+
+## Why Passing Tests Still Miss Behavior
+
+Most system and E2E tests are strongest at the outside of a workflow:
+
+1. Send this request, command, or click path.
+2. Assert this response, screen state, or final result.
+
+That is necessary. It is not always enough.
+
+A test can return `201 Created` while the system skipped a required queue message, missed an audit write, called the wrong downstream service, forgot a cache update, sent an extra notification, or performed a side effect that should have been forbidden.
+
+Blackbox keeps the test result, then adds behavioral evidence for what happened between input and output.
+
+<OverviewDiagram kind="blind-spot" />
+
+## Best First Fit
+
+Blackbox is system-test-first.
+
+The best first fit is a controlled system test: services, databases, queues, caches, and local or test-managed dependencies running in a repeatable environment. That kind of run is realistic enough to produce meaningful effects and controlled enough to trust as a CI gate.
+
+Blackbox can also observe broader E2E journeys. Those runs can be valuable when you need full-journey realism across auth, email, vendors, shared environments, or other unmanaged dependencies. They are usually noisier, so they are better as evidence first and gates only when the environment is stable enough.
+
+<OverviewDiagram kind="fit" />
+
+## The Core Model
+
+Blackbox is not a pile of unrelated artifacts. The model has an order.
+
+| Layer | What it means |
+| --- | --- |
+| Runtime evidence | Observed facts from the real test run |
+| Effects | The behavior derived from that evidence: writes, calls, messages, cache operations, emitted intents |
+| Effect catalog | The reviewed behavior contract: `requires` and `forbids` |
+| Matchers | The assertions that enforce the catalog during future runs |
+| Effect coverage | The report showing which cataloged effects were satisfied, missing, failed, or uncovered |
+| OMC/DC | An advanced decision-sensitivity report based on observed effects |
+| Feature files | Optional readable Gherkin artifacts derived from tests and checked for drift |
+
+The core path is runtime evidence, effects, effect catalog, matchers, and effect coverage. OMC/DC is deeper coverage. Feature files are optional readable specs.
+
+<OverviewDiagram kind="workflow" />
+
+## The Combined Loop
+
+Blackbox is most coherent when tests, effects, and feature files are understood as separate layers that can reinforce each other.
+
+The test executes the workflow. The effect catalog proves the runtime behavior that matters. The feature file, when used, gives that behavior a readable Gherkin surface. Gates keep the layers synchronized so a review can see whether the workflow still runs, what it actually did, and whether the readable behavior drifted.
+
+Read [Tests, Effects, and Feature Files](/docs/blackbox/overview/tests-effects-and-feature-files) for the full model.
+
+## What Success Looks Like
+
+A useful first Blackbox adoption is small.
+
+Pick one important workflow. Run it. Review the generated effect catalog. Keep the effects that define correct behavior. Add forbids for behavior that must never happen. Run again and let the matcher prove the catalog.
+
+Success after the first useful loop looks like this:
+
+```yaml
+requires:
+ - { boundary: postgres, op: INSERT, key: subscriptions }
+ - { boundary: redis, op: SET, key: "user:*:tier" }
+ - { boundary: sqs, op: SendMessage }
+forbids:
+ - { boundary: postgres, op: DELETE }
+ - { boundary: http, op: POST, key: /v1/refunds }
+```
+
+That catalog gives reviewers a concrete contract. The next run can now answer: did the required effects happen, and did the forbidden effects stay absent?
+
+## A Concrete Example
+
+Consider a subscription workflow.
+
+A normal system test might call `POST /subscriptions` and assert `201 Created`. Blackbox asks what the system did while producing that response:
+
+1. Did it look up the user and tier?
+2. Did it create the payment intent?
+3. Did it insert the subscription?
+4. Did it update the cache?
+5. Did it call the order service?
+6. Did it publish the subscription message?
+7. Did it avoid refunds, deletes, truncates, and destructive cache operations?
+
+The HTTP assertion still matters. Blackbox adds the review surface for the runtime behavior behind it.
+
+## When Not To Start Here
+
+Blackbox is not the first tool for every test problem.
+
+Start somewhere else when:
+
+1. You only need fast feedback on pure local logic.
+2. The behavior has no meaningful runtime boundary.
+3. The only goal is writing Gherkin files, not verifying behavior.
+4. The environment is so flaky that every run produces different dependency behavior.
+5. The team cannot yet run the system or the target workflow in test or CI.
+
+In those cases, unit tests, integration tests, testbed setup, or plain feature-file authoring may come first.
+
+## What Blackbox Complements
+
+Blackbox strengthens existing practices rather than replacing them.
+
+| Practice | How Blackbox relates |
+| --- | --- |
+| Unit tests | Complements them; unit tests remain the fastest check for local logic |
+| Integration tests | Complements them; integration tests still prove narrow collaborator behavior |
+| System tests | Makes their runtime behavior reviewable |
+| E2E tests | Adds evidence beyond pass/fail and input/output checks |
+| Observability | Uses runtime signals as verification inputs, not just inspection data |
+| BDD and specs | Can generate or check readable behavior specs, but does not require them |
+| AI-assisted development | Gives reviewers proof from a real run, outside the generated implementation |
+
+The value is not that Blackbox knows your intent magically. The value is that it turns a real run into artifacts a human or gate can review.
+
+## Why It Matters Now
+
+Teams are changing systems faster than behavioral documentation can keep up.
+
+Refactors are larger. Legacy modernization touches more boundaries. Service graphs are harder to reason about from code alone. Specs and feature files can become stale. AI-assisted development can produce useful code quickly, but it also increases the amount of change reviewers must verify.
+
+Blackbox gives teams a different review question:
+
+> What behavior did the running system prove?
+
+That question is useful before refactors, after incidents, during migrations, in system-test CI gates, and anywhere a green response is not the whole story.
+
+## Start Here
+
+Choose the path that matches your repo:
+
+1. [5-Minute Quickstart: existing tests](/docs/blackbox/quickstart/first-proven-feature?track=existing)
+2. [5-Minute Quickstart: no system tests yet](/docs/blackbox/quickstart/first-proven-feature?track=new)
+3. [Feature Files From Tests](/docs/blackbox/quickstart/feature-files-from-tests)
+
+Then read the concepts behind the first run:
+
+1. [Tests, Effects, and Feature Files](/docs/blackbox/overview/tests-effects-and-feature-files)
+2. [System Effects](/docs/blackbox/concepts/system-effects)
+3. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
diff --git a/src/content/docs/blackbox/overview/when-to-use-blackbox.md b/src/content/docs/blackbox/overview/when-to-use-blackbox.md
new file mode 100644
index 0000000..0f7c988
--- /dev/null
+++ b/src/content/docs/blackbox/overview/when-to-use-blackbox.md
@@ -0,0 +1,79 @@
+---
+title: "When to Use Blackbox"
+description: "Clarify the workflows and adoption paths where Blackbox adds useful runtime evidence."
+sidebar_position: 4
+keywords: ["when to use blackbox", "system testing", "backend verification"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "when to use blackbox"
+ secondary_keywords: ["system testing", "backend verification", "behavioral verification gate"]
+ search_intent: "evaluation intent from teams deciding whether Blackbox fits their workflow"
+ snippet_angle: "use Blackbox when behavior crosses runtime boundaries and runtime evidence would change the review"
+---
+
+Use Blackbox when you need runtime proof that behavior still matches what matters. Do not use it when a lower-level unit test or a local assertion already answers the question.
+
+The best first target is one workflow where a passing response is not enough proof.
+
+If the review would change after seeing the database writes, cache operations, queue messages, HTTP calls, and forbidden effects, Blackbox is probably relevant.
+
+## Good Fits
+
+Blackbox is a good fit when behavior crosses a runtime boundary and that behavior matters enough to review.
+
+Use it for:
+
+1. Covering behavior before a refactor.
+2. Modernizing a legacy system without losing current behavior.
+3. Turning a previous incident into a recurring regression gate.
+4. Verifying microservice workflows across HTTP, queues, caches, and databases.
+5. Checking that a spec-driven implementation actually produces the intended runtime behavior.
+6. Giving AI-assisted development a deterministic checker outside the model's prose.
+7. Strengthening existing system or E2E tests that only assert responses.
+8. Starting from a runnable system when richer tests do not exist yet.
+
+The shared pattern is risk at the boundary. Blackbox is most useful when a change can look correct from the response while still breaking the effects downstream systems, users, or operators rely on.
+
+The goal is not to force Blackbox onto every test. The goal is to spend system-test cost only where runtime evidence improves confidence.
+
+## If You Already Have Tests
+
+You do not need to adopt BDD first. Blackbox can sit on top of existing system or E2E tests.
+
+Start by collecting runtime evidence from one existing workflow. Then decide which observed effects should become required and which effects should be forbidden. This lets you add behavioral verification without rewriting the whole test suite.
+
+This path is often the easiest adoption route because the team already has a runnable workflow and a known test command.
+
+## If You Already Have Specs Or Feature Files
+
+Blackbox does not replace specs or feature files. It can help verify whether the running system still matches the behavior those artifacts describe.
+
+This is useful in spec-driven development and BDD systems because written behavior can drift. Blackbox adds a runtime-backed verification step next to the written spec.
+
+The spec remains the statement of intent. The effect catalog remains the executable behavior contract. When both exist, Blackbox can keep them connected.
+
+## When The Combined Loop Is Strongest
+
+Use tests, effects, and feature files together when the review needs more than one signal.
+
+The combined loop is strongest for refactors, legacy modernization, incident regression, spec-driven development, BDD-heavy teams, and AI-assisted implementation. In those cases, the test proves the workflow still runs, the effects prove what happened at runtime, and the feature file gives reviewers a readable behavior surface.
+
+This is not required for every workflow. If the team only needs runtime proof, start with effects. If the team only needs readable scenarios from tests, start with feature files. If the risk is high, combine them and gate the change from multiple angles.
+
+## If You Are Refactoring
+
+Blackbox is especially useful before a risky refactor. Run the current system, capture the behavior, review the required and forbidden effects, then refactor against that proof trail.
+
+The goal is not to freeze every implementation detail. The goal is to preserve the behavior that matters at the boundary.
+
+## If You Use Coding Agents
+
+AI coding agents can make changes faster than humans can inspect every path manually. Blackbox gives the workflow an external stop condition: the run must produce the required effects and avoid forbidden ones.
+
+That does not make the agent the final judge. It gives the agent and the reviewer a better artifact to inspect.
+
+## What To Read Next
+
+1. [Tests, Effects, and Feature Files](/docs/blackbox/overview/tests-effects-and-feature-files)
+2. [Prove Your First Flow](/docs/blackbox/quickstart/first-proven-feature)
+3. [Covering Before Refactor](/docs/blackbox/use-cases/covering-before-refactor)
diff --git a/src/content/docs/blackbox/overview/where-blackbox-fits.mdx b/src/content/docs/blackbox/overview/where-blackbox-fits.mdx
new file mode 100644
index 0000000..cfdb9ea
--- /dev/null
+++ b/src/content/docs/blackbox/overview/where-blackbox-fits.mdx
@@ -0,0 +1,119 @@
+---
+title: "Where Blackbox Fits"
+description: "Understand where Blackbox belongs: controlled system tests, broader E2E journeys, managed dependencies, unmanaged dependencies, and runtime behavior gates."
+sidebar_position: 2
+keywords: ["system testing", "e2e testing", "blackbox testing", "managed dependencies", "runtime behavior gate"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "system testing"
+ secondary_keywords: ["e2e testing", "blackbox testing", "managed dependencies", "runtime behavior gate"]
+ search_intent: "teams deciding where Blackbox belongs in their test and release workflow"
+ snippet_angle: "Blackbox fits where real system runs cross boundaries and need reviewable runtime evidence"
+---
+
+import OverviewDiagram from '@/components/blackbox/OverviewDiagram.astro';
+
+Blackbox fits where a passing test is not enough by itself. It belongs around real system runs: workflows that cross process, service, database, queue, HTTP, event, file, or other runtime boundaries.
+
+The goal is not to replace smaller tests or production observability. The goal is to add a verification layer that can say: this run produced these effects, this behavior changed, this gap remains, and this release should or should not pass the gate.
+
+That makes Blackbox strongest at the boundary between testing and release confidence. It turns selected system and E2E runs into runtime behavior gates.
+
+## The Best First Fit
+
+The best first fit is usually a controlled system test.
+
+In this context, a system test runs a composed slice of the product in an environment the test mostly controls. It may start real services, databases, queues, caches, local infrastructure, Docker Compose, or Testcontainers. The run is realistic enough to produce meaningful runtime behavior, but controlled enough to make failures useful in CI.
+
+That is where Blackbox has the clearest value:
+
+1. The workflow crosses real boundaries.
+2. The dependencies are known and resettable.
+3. The outputs can be compared between runs.
+4. The evidence can become a merge or release gate.
+
+Examples include signup, subscription, billing-state changes, order placement, webhook handling, job processing, event publishing, and service-to-service flows.
+
+## System Tests And E2E Tests
+
+Blackbox can work with both system tests and E2E tests, but they answer slightly different questions.
+
+<OverviewDiagram kind="fit" />
+
+| Test shape | What it usually proves | Dependency shape | Blackbox role |
+| --- | --- | --- | --- |
+| System test | A composed service or local topology behaves correctly | Mostly managed by the test run | Strong fit for repeatable behavior gates |
+| E2E test | A full journey works through a production-like path | Often includes remote or shared services | Strong fit for broad evidence and smoke coverage |
+
+The distinction matters because Blackbox reports are only as actionable as the run they describe.
+
+If an E2E test depends on a shared staging environment, real auth, external email delivery, a payment sandbox, or a vendor API, Blackbox can still capture what happened. The evidence is valuable. But a failure may come from the product, the environment, a third party, shared state, rate limits, credentials, or network behavior.
+
+If a system test runs the same journey with managed dependencies, the evidence is usually better suited for a deterministic CI gate.
+
+## Managed And Unmanaged Dependencies
+
+A managed dependency is created, configured, reset, and owned by the test run. Examples include a local Postgres container, Redis, SQS through LocalStack, a fake mail server, local services, Docker Compose, or Testcontainers.
+
+An unmanaged dependency sits outside the test's direct control. Examples include a real auth provider, real email delivery, SMS, a payment provider, a vendor API, a shared staging service, or a remote environment owned by another team.
+
+Blackbox can observe both shapes, but the meaning of a failure changes:
+
+1. System tests with managed dependencies are better for deterministic behavioral gates.
+2. E2E tests with unmanaged dependencies are better for full-journey realism.
+3. Failures in managed environments usually point closer to the behavior under test.
+4. Failures in unmanaged environments may come from auth, email, vendors, shared state, or infrastructure noise.
+
+That is why many teams start by taking one important E2E-style journey and running it in a more controlled system-test topology. Blackbox then preserves the behavioral value of that journey while making the result more reviewable and more reliable as a gate.
+
+## Black-Box And White-Box
+
+White-box testing uses knowledge of internals such as classes, functions, branches, providers, and modules. This is useful for local reasoning and fast feedback.
+
+Black-box testing observes behavior from the outside. This is useful when the user, another service, or the business process only cares what the system did at the boundary.
+
+Blackbox is black-box in that second sense, but it is not only a testing philosophy. It provides a concrete evidence pipeline: runtime capture, effect catalogs, coverage reports, optional generated behavior specs, and CI gates.
+
+## Where The Feature-File Track Fits
+
+The feature-file track is useful when the team wants behavior to be readable outside the test implementation.
+
+It can be adopted separately from effect coverage. A team can emit feature files from existing tests, lint the Given/When/Then shape, and check for feature-file drift without making runtime effects the first gate. Another team can start with only effects and never write Gherkin.
+
+The strongest path combines both. System tests execute the behavior, effects prove what happened at runtime, and feature files make the behavior reviewable as scenarios. That combination is covered in [Tests, Effects, and Feature Files](/docs/blackbox/overview/tests-effects-and-feature-files).
+
+## Runtime Behavior Gates
+
+A runtime behavior gate is a test gate based on what the system actually did during execution, not only on whether assertions passed.
+
+Use Blackbox when the review question sounds like this:
+
+1. Did this workflow write the right record?
+2. Did it publish the right message?
+3. Did it call the right downstream service?
+4. Did it avoid a forbidden side effect?
+5. Did a refactor preserve the behavior a real system run proves?
+
+Blackbox starts where local tests stop being enough: the composed system, the service boundary, the workflow, and the evidence left by a real run.
+
+That does not mean every system test needs Blackbox. Use it where the workflow has behavior worth proving and where the resulting artifacts will change a review or release decision.
+
+## What Blackbox Does Not Replace
+
+Blackbox complements several existing layers:
+
+| Existing layer | Keep using it for | Add Blackbox when |
+| --- | --- | --- |
+| Unit tests | Fast feedback on local logic | The important risk crosses a runtime boundary |
+| Integration tests | Component wiring and collaborator behavior | The composed run produces effects worth tracking |
+| E2E tests | Full-journey realism | You want evidence, comparison, or coverage from the run |
+| Observability | Production diagnosis and operations | You want pre-merge verification from controlled test runs |
+| Specs and scenarios | Intended behavior | You want to anchor them to runtime evidence |
+
+The practical rule is simple: keep the fast tests that tell developers where logic broke, and add Blackbox where the team needs proof of what the running system did.
+
+## What To Read Next
+
+1. [Tests, Effects, and Feature Files](/docs/blackbox/overview/tests-effects-and-feature-files)
+2. [System Test Effect Coverage](/docs/blackbox/overview/system-test-effect-coverage)
+3. [Requirements and Supported Stacks](/docs/blackbox/quickstart/requirements)
diff --git a/src/content/docs/blackbox/project/examples-and-sample-project.md b/src/content/docs/blackbox/project/examples-and-sample-project.md
new file mode 100644
index 0000000..eab2fdc
--- /dev/null
+++ b/src/content/docs/blackbox/project/examples-and-sample-project.md
@@ -0,0 +1,102 @@
+---
+title: "Examples and Sample Project"
+description: "Point users to runnable examples that show the fastest path from install to observed effects."
+sidebar_position: 1
+keywords: ["blackbox examples", "blackbox sample project", "effect coverage example"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "blackbox examples"
+ secondary_keywords: ["blackbox sample project", "effect coverage example", "playwright opentelemetry example"]
+ search_intent: "example-seeking intent from developers who want a runnable Blackbox project before wiring their own system"
+ snippet_angle: "use the subscription-service showcase to see Playwright, Docker Compose, OpenTelemetry spans, feature files, effects YAML, and OMC/DC reports together"
+---
+
+## Abstract
+
+The showcase system is the safest place to learn Blackbox before adapting it to a real system. It demonstrates a subscription workflow that crosses HTTP, Postgres, Redis, a Stripe-like downstream API, an order service, SQS, and a fraud-check service.
+
+## Audience
+
+New users, evaluators, and contributors who want a known-good project before wiring Blackbox into their own stack.
+
+## What The Sample Project Teaches
+
+1. How to run one useful system-test workflow.
+2. How a feature file, effect contract, runtime evidence, and OMC/DC report relate to each other.
+3. Which artifacts appear after a successful run.
+4. What a reviewer should inspect before trusting the result.
+
+## The Showcase Story
+
+The canonical story is `subscribe-flow`: an existing user subscribes to the pro tier.
+
+The test does more than assert an HTTP response. It verifies that the system:
+
+1. Reads the user tier from Redis.
+2. Reads user data from Postgres.
+3. Creates a payment intent through a Stripe-like HTTP boundary.
+4. Inserts the subscription into Postgres.
+5. Writes the new tier to Redis.
+6. Calls the order service.
+7. Sends a subscription message to SQS.
+8. Avoids forbidden effects such as refunds, deletes, truncates, and Redis flushes.
+
+## Source Files
+
+| File | What it demonstrates |
+| --- | --- |
+| `e2e/tests/00-baseline-subscribe.system.test.ts` | The baseline Playwright system test using Blackbox matchers and capture fixtures. |
+| `e2e/features/subscribe-flow.feature` | The readable feature artifact for the subscription workflow. |
+| `e2e/tests/__effects__/00-baseline-subscribe.system.effects.yaml` | Required and forbidden runtime effects for the same workflow. |
+| `e2e/services/compose.user.yml` | The production-shaped Docker Compose topology used by the testbed. |
+| `e2e/.blackbox-coverage/` | Existing generated evidence and reports from a run. |
+
+## Run The Example
+
+From the Blackbox repository root:
+
+```bash
+pnpm test:system
+```
+
+That project script delegates to the e2e package, builds Blackbox, builds or selects the local OpenTelemetry bootstrap image, starts the testbed through Playwright, and writes coverage artifacts.
+
+To regenerate reports from existing saved evidence:
+
+```bash
+pnpm exec blackbox coverage replay --coverage-dir e2e/.blackbox-coverage --out reports
+```
+
+## What Makes A Good Sample
+
+1. It is runnable on the supported alpha stack.
+2. It produces real proof artifacts.
+3. It is small enough to inspect without a long setup.
+4. It matches the docs wording closely enough to serve as a sanity check.
+
+## Expected Artifacts
+
+After a successful run, inspect:
+
+1. `.blackbox-coverage/omcdc-propagation.md`
+2. `.blackbox-coverage/omcdc-propagation.json`
+3. `.blackbox-coverage/omcdc.html`
+4. `.blackbox-coverage/coverage-final.json`
+5. `.blackbox-coverage/html/index.html`
+6. `.blackbox-coverage/spans/*.json`
+7. `.blackbox-coverage/v8-per-test/*.json`
+
+Start with the Markdown or HTML OMC/DC report. Use raw spans and V8 files only when debugging the evidence path.
+
+## What To Read Next
+
+1. [Prove Your First Feature](/docs/blackbox/quickstart/first-proven-feature)
+2. [Run with the Testbed](/docs/blackbox/guides/using-the-testbed)
+3. [Reading Coverage Reports](/docs/blackbox/guides/reading-coverage-reports)
+4. [Files and Artifacts](/docs/blackbox/reference/files-and-artifacts)
+
+## Figure Placeholder
+
+**Caption:** The subscription-service showcase: test file, feature file, effects YAML, Docker Compose topology, and OMC/DC report.
+
+**Slot:** `<!-- TODO: insert interactive sample-project file map linked to the subscription flow -->`
diff --git a/src/content/docs/blackbox/project/license-and-support.md b/src/content/docs/blackbox/project/license-and-support.md
new file mode 100644
index 0000000..3bc6cde
--- /dev/null
+++ b/src/content/docs/blackbox/project/license-and-support.md
@@ -0,0 +1,50 @@
+---
+title: "License and Support"
+description: "Explain the license, support boundaries, and how users should ask for help."
+sidebar_position: 6
+keywords: ["blackbox license", "blackbox support", "blackbox open source"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "License and Support"
+ secondary_keywords: ["blackbox license", "blackbox support"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Explain the license, support boundaries, and how users should ask for help.
+
+This page should make the support posture explicit so adopters know what they can rely on and where to file problems.
+
+## Audience
+
+Developers, engineering leads, security reviewers, and open-source contributors.
+
+## Support Policy
+
+1. Report bugs and docs issues in the project issue tracker.
+2. Use the security disclosure process for sensitive vulnerabilities.
+3. Expect best-effort community support in alpha, not a formal SLA.
+4. Expect maintainers to triage, clarify, and close issues that are out of scope or not reproducible.
+5. Do not expect support for unsupported stacks or custom integrations that are not documented.
+
+## License
+
+1. State the project license plainly.
+2. Link to the canonical license file.
+3. Call out whether dependencies or bundled artifacts carry separate terms.
+
+## Content Outline
+
+1. State the project license and link to the license file.
+2. Explain where to ask questions, report bugs, and request features.
+3. Define the support boundary for alpha users.
+4. Link to security disclosure and contribution guidance.
+5. Explain how maintainers triage issues and releases.
+
+## Evidence To Add
+
+- Maintainer-approved license wording.
+- Issue templates and support links.
+- Security disclosure process.
diff --git a/src/content/docs/blackbox/project/supported-platforms-and-integrations.md b/src/content/docs/blackbox/project/supported-platforms-and-integrations.md
new file mode 100644
index 0000000..57c88e6
--- /dev/null
+++ b/src/content/docs/blackbox/project/supported-platforms-and-integrations.md
@@ -0,0 +1,54 @@
+---
+title: "Supported Platforms and Integrations"
+description: "State what Blackbox supports today, what is experimental, and what belongs on the roadmap."
+sidebar_position: 2
+keywords: ["blackbox supported platforms", "blackbox integrations", "blackbox compatibility"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Supported Platforms and Integrations"
+ secondary_keywords: ["blackbox supported platforms", "blackbox integrations"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+State what Blackbox supports today, what is experimental, and what belongs on the roadmap.
+
+This page should prevent users from guessing whether their language, test runner, tracing stack, CI system, or SDD workflow is supported.
+
+## Audience
+
+Teams evaluating whether Blackbox fits their current stack.
+
+## Compatibility Matrix
+
+Document the tested stacks in a matrix with `status`, `version`, and `date checked`.
+
+1. Supported.
+2. Experimental.
+3. Planned.
+4. Unsupported.
+
+Make the wording concrete. If a stack is supported, say what was tested and when. If it is experimental, say what the current limits are. If it is unsupported, say so directly.
+
+## Integration Policy
+
+1. Supported alpha stack: Node, TypeScript, Playwright, Docker, and OpenTelemetry prerequisites.
+2. CI providers: state what is tested and what is only known to work in principle.
+3. SDD tools: distinguish generic SDD workflow compatibility from any direct integration.
+4. Container environments: state what images, volumes, and network assumptions are covered.
+
+## Content Outline
+
+1. List the supported alpha stack: Node, TypeScript, Playwright, Docker, and OpenTelemetry prerequisites.
+2. Separate supported, experimental, planned, and unsupported integrations.
+3. Cover CI providers, SDD tools, package managers, and container environments.
+4. Explain what users can still do with custom wiring when an integration is not first-class.
+5. Link to the configuration reference and release notes only where they help with compatibility decisions.
+
+## Evidence To Add
+
+- A compatibility matrix with tested versions and dates.
+- Integration status labels that distinguish support from experimentation.
+- Notes about direct Spec Kit support versus generic SDD workflow support.
diff --git a/src/content/docs/blackbox/project/upgrade-and-version-compatibility.md b/src/content/docs/blackbox/project/upgrade-and-version-compatibility.md
new file mode 100644
index 0000000..e30a09a
--- /dev/null
+++ b/src/content/docs/blackbox/project/upgrade-and-version-compatibility.md
@@ -0,0 +1,65 @@
+---
+title: "Upgrade and Version Compatibility"
+description: "Document upgrade commands, compatibility guarantees, and breaking-change handling."
+sidebar_position: 3
+keywords: ["blackbox upgrade", "blackbox versions", "blackbox breaking changes"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Upgrade and Version Compatibility"
+ secondary_keywords: ["blackbox upgrade", "blackbox versions"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Document upgrade commands, compatibility guarantees, and breaking-change handling.
+
+This page should explain how users keep CLI behavior, report formats, schemas, and generated artifacts aligned across versions.
+
+## Audience
+
+Users maintaining Blackbox in a long-lived repository or CI workflow.
+
+## What This Page Owns
+
+1. How to check the installed version.
+2. How to upgrade each supported installation path.
+3. Which artifacts or schemas can change across versions.
+4. How to tell whether a change is a breaking one.
+
+## Compatibility Areas
+
+1. CLI flags and command behavior.
+2. Config file parsing and defaults.
+3. Report and artifact formats.
+4. Catalog and effects file schemas.
+5. Package API or import surface where applicable.
+
+## Practical Guidance
+
+1. Read release notes before upgrading.
+2. Check whether the change affects CI or generated artifacts.
+3. Keep a rollback path if the repo depends on a specific format.
+4. Validate the upgrade in the sample project before using it on a production repo.
+
+## Content Outline
+
+1. Show how to check the installed version.
+2. Show the upgrade command for each supported package manager.
+3. Explain compatibility across CLI flags, config files, catalog schema, report schema, and package APIs.
+4. Call out migration steps for breaking changes.
+5. Link release notes to upgrade guidance.
+
+## What To Say Clearly
+
+1. What is backward compatible.
+2. What may require a migration.
+3. What should be pinned in CI.
+4. What users should test after upgrading.
+
+## Evidence To Add
+
+- Version compatibility table.
+- Example upgrade and rollback commands.
+- Migration notes for the first major breaking change.
diff --git a/src/content/docs/blackbox/quickstart/feature-files-from-tests.mdx b/src/content/docs/blackbox/quickstart/feature-files-from-tests.mdx
new file mode 100644
index 0000000..6252903
--- /dev/null
+++ b/src/content/docs/blackbox/quickstart/feature-files-from-tests.mdx
@@ -0,0 +1,227 @@
+---
+title: "Feature Files From Tests"
+description: "Generate Gherkin .feature files from system and E2E tests, then check feature-file drift without making BDD mandatory."
+sidebar_position: 4
+keywords: ["blackbox feature files", "generate feature files from tests", "playwright bdd", "gherkin drift check"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "blackbox feature files"
+ secondary_keywords: ["generate feature files from tests", "playwright bdd", "features emit", "features check", "gherkin drift check"]
+ search_intent: "developers who have system or E2E tests and want to decide whether to generate Gherkin feature files"
+ snippet_angle: "generate feature files from tests, validate Gherkin syntax, and catch feature-file drift without adopting Cucumber as the main workflow"
+---
+
+import QuickstartTrackDiagram from '@/components/blackbox/QuickstartTrackDiagram.astro';
+import BddReverseDemo from '@/components/blackbox/BddReverseDemo.astro';
+
+Feature files are a readable behavior layer on top of tests that already exist.
+
+Use this page after you have at least one system or E2E test. You can skip this layer and still use Blackbox for runtime evidence, effect catalogs, matchers, effect coverage, and OMC/DC. Add feature files when the team wants a Gherkin-shaped artifact for review, product discussion, SDD handoff, or CI checks for feature-file drift.
+
+<QuickstartTrackDiagram kind="specs" />
+
+<BddReverseDemo />
+
+## The BDD Context
+
+BDD and Cucumber made an important idea popular: behavior should be readable by more than the person who wrote the test. Gherkin gave teams the `Given`, `When`, `Then` shape and `.feature` files gave behavior a reviewable home.
+
+The hard part was maintenance. In many teams, hand-written feature files, step definitions, and test code became three things that had to agree. When the system changed, the prose could stay green-looking while the real behavior moved somewhere else.
+
+Blackbox uses the useful part of that movement without requiring the old workflow:
+
+| Workflow | Starts from | What you maintain | Best fit |
+| --- | --- | --- | --- |
+| Cucumber-style BDD | Hand-written `.feature` files | Feature text plus step bindings | Teams that want Gherkin to drive implementation |
+| Plain system tests | Test code | Test code only | Engineering-only suites |
+| Blackbox feature files | Existing system or E2E tests | Test source plus generated/reviewed feature files | Teams that want readable specs without making Gherkin the driver |
+
+Gherkin is the format. Cucumber is not required.
+
+## What Blackbox Actually Does
+
+Blackbox does not just stringify test names into `.feature` files. The feature pipeline has four jobs:
+
+1. Detect the test style: explicit Blackbox BDD DSL when present, otherwise Playwright-style tests.
+2. Analyze the behavior shape into phases: arrange as `Given`, act as `When`, conclude with observable `Then` assertions.
+3. Emit a canonical Gherkin subset: `@flow`, `Feature`, optional `Background`, `Scenario`, `Scenario Outline`, `Rule`, `Examples`, `When`, `Then`, and `And`.
+4. Gate the result with syntax validation, feature-file drift detection, and optional runtime-observation comparison.
+
+The explicit BDD DSL gives Blackbox the strongest signal because the author already wrote `scenario`, `given`, `when`, `then`, `background`, or `given.each`. Plain Playwright tests can still be decompiled, but intent recovery is best-effort. If the test structure is unclear, lint findings are useful feedback rather than something to hide.
+
+## Prerequisite
+
+Start with a test source that describes a real flow:
+
+```text
+tests/
+ checkout.system.test.ts
+```
+
+or, in the showcase layout:
+
+```text
+e2e/tests/
+ 00-baseline-subscribe.system.test.ts
+```
+
+The test should be worth explaining to another human. Feature files are not a replacement for writing the test or proving runtime behavior.
+
+## Choose The Layer
+
+There are three valid paths:
+
+| Path | What you get | What you do not get |
+| --- | --- | --- |
+| Effects only | Runtime evidence, effect catalogs, matchers, effect coverage, and OMC/DC reports | Human-readable Gherkin output |
+| Feature files only | Readable `.feature` files and feature-file drift checks from test source | Runtime effect coverage |
+| Both | Runtime-backed behavior proof plus readable feature files | More artifacts to review |
+
+Use the smallest path that creates value. If the audience is mostly developers and the effect catalog is already clear, effects-only may be enough. If product, QA, platform, or AI-assisted workflows need a readable behavior surface, add feature files.
+
+## Generate A Feature File
+
+Use `features emit` to create `.feature` files from Playwright or Blackbox BDD-DSL test sources:
+
+```bash
+pnpm exec blackbox features emit ./tests --out ./features
+```
+
+For the showcase layout:
+
+```bash
+pnpm exec blackbox features emit ./e2e/tests --out ./e2e/features
+```
+
+The command accepts one or more test files or directories. It can also use a step library, or skip step resolution:
+
+```bash
+pnpm exec blackbox features emit ./tests --steps ./scripts/step-lib.json
+pnpm exec blackbox features emit ./tests --no-steps
+```
+
+The output is a Gherkin `.feature` file:
+
+```gherkin
+@flow:subscribe-flow
+Feature: subscribing as a pro tier user
+
+ Scenario: alice is an existing user with no active subscription
+ When alice POSTs /subscriptions with a valid card
+ Then the response status is 201
+ And the subscription is persisted in postgres
+ And the tier is cached in redis
+ And a subscribe order is queued in SQS
+```
+
+Read this file as a review artifact derived from tests, not as proof by itself. Runtime proof comes from the system run, the effect catalog, and coverage reports.
+
+## Check The Behavior Grammar
+
+Use `features lint` when feature files matter enough to gate. The key rule is `aaa-shape`:
+
+```text
+Given* When+ Then+
+```
+
+That means a scenario may have setup, must exercise at least one action, and must conclude with at least one observable assertion. The linter also catches missing `Then` steps, empty scenarios, unresolved placeholders, overly opaque decompiled steps, and repeated setup that should become a `Background`.
+
+```bash
+pnpm exec blackbox features lint ./tests --fail-on error
+pnpm exec blackbox features lint ./tests --json
+```
+
+Use this before trusting generated feature files in review. A pretty feature file is not enough; the underlying scenario needs a shape that can survive as a verification artifact.
+
+## Check Gherkin Syntax And Feature-File Drift
+
+Use `features check` after generating feature files. It runs two checks by default:
+
+1. Gherkin syntax validation for `.feature` files with the Cucumber parser.
+2. Source-vs-feature consistency between the test sources and generated feature files.
+
+```bash
+pnpm exec blackbox features check --features ./features --tests ./tests
+```
+
+For the showcase layout:
+
+```bash
+pnpm exec blackbox features check --features ./e2e/features --tests ./e2e/tests
+```
+
+Use JSON when a script, CI job, or AI agent needs structured output:
+
+```bash
+pnpm exec blackbox features check --features ./e2e/features --tests ./e2e/tests --json
+```
+
+You can also run only one side of the check:
+
+```bash
+pnpm exec blackbox features check --features ./features --skip-drift
+pnpm exec blackbox features check --features ./features --tests ./tests --skip-syntax
+```
+
+For a dedicated feature-file drift check:
+
+```bash
+pnpm exec blackbox features drift --tests ./tests --features ./features
+```
+
+The feature-file drift kinds are `missing`, `stale`, `orphan`, and `unparseable`.
+
+## Optional Semantic Observation Gate
+
+Feature-file drift is source-to-feature drift. It answers: did the `.feature` file stay synchronized with the test source?
+
+Semantic observation comparison is runtime-to-runtime drift. It answers: did two runs produce the same meaningful observable behavior?
+
+Use it when reshaping tests, migrating toward the BDD DSL, or comparing a baseline run to a candidate run:
+
+```bash
+pnpm exec blackbox features compare-observations --baseline ./baseline-observations --candidate ./candidate-observations --json
+```
+
+This gate is experimental. It compares `.observation.json` files from the observation reporter and treats step-boundary changes as benign, while network-call changes, assertion changes, response differences, missing tests, and different outcomes are meaningful.
+
+## How This Fits Spec-Driven Development
+
+Spec-driven development tools describe intended product behavior. Blackbox feature files describe system behavior as exercised by tests. They can live side by side.
+
+The useful bridge is authored translation: a human, test author, or agent turns a product spec into a system or E2E test. From there, Blackbox can generate feature files from the test source and compare them over time. That adds a verification step to the SDD workflow without claiming that generated Gherkin replaces the original product spec.
+
+## What To Commit
+
+Commit feature files when they are part of the durable review surface:
+
+```text
+features/*.feature
+```
+
+or:
+
+```text
+e2e/features/*.feature
+```
+
+If you are also using effects, commit the reviewed effect catalogs:
+
+```text
+e2e/tests/__effects__/*.effects.yaml
+```
+
+Generated run outputs usually stay out of git unless CI publishes them:
+
+```text
+.blackbox-coverage/
+playwright-report/
+test-results/
+```
+
+## What To Read Next
+
+1. [Feature Files, BDD, and Staleness](/docs/blackbox/concepts/feature-files-and-staleness)
+2. [Generating Feature Files](/docs/blackbox/guides/generating-feature-files)
+3. [Files and Artifacts](/docs/blackbox/reference/files-and-artifacts)
+4. [Spec-Driven Development](/docs/blackbox/use-cases/spec-driven-development)
diff --git a/src/content/docs/blackbox/quickstart/first-proven-feature.mdx b/src/content/docs/blackbox/quickstart/first-proven-feature.mdx
new file mode 100644
index 0000000..d25ea51
--- /dev/null
+++ b/src/content/docs/blackbox/quickstart/first-proven-feature.mdx
@@ -0,0 +1,32 @@
+---
+title: "5-Minute Quickstart"
+description: "Choose a Blackbox quickstart track: add effect coverage to an existing system test, or learn the first proof loop from the showcase."
+sidebar_position: 3
+keywords: ["blackbox quickstart", "effect catalog", "effect coverage tutorial", "system test quickstart"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "blackbox quickstart"
+ secondary_keywords: ["effect catalog", "effect coverage tutorial", "system test quickstart"]
+ search_intent: "quickstart intent from developers choosing how to get first value from Blackbox"
+ snippet_angle: "choose an existing-tests or showcase track, produce one effect catalog, and see one effect coverage signal"
+---
+
+import QuickstartTracks from '@/components/blackbox/QuickstartTracks.astro';
+
+## Choose Your Starting Point
+
+Blackbox has two fast starts. Use `?track=existing` when you already have a system or E2E test. Use `?track=new` when you want to learn from the showcase before wiring your own service.
+
+Both tracks start with runtime behavior. An effect is observable boundary behavior: a database write, queue message, HTTP call, cache change, emitted event, email intent, or forbidden dependency call.
+
+By the end, you should have one flow run with Blackbox, one effect catalog, one reviewed required or forbidden effect, and one effect coverage signal in the terminal.
+
+<QuickstartTracks />
+
+## After Your First Successful Run
+
+After the first effect loop works, choose the next layer deliberately:
+
+- Continue to [Feature Files From Tests](/docs/blackbox/quickstart/feature-files-from-tests) if you want feature files, Gherkin output, or feature-file drift checks.
+- Read [System Effects](/docs/blackbox/concepts/system-effects) to understand catalogs, matchers, effect coverage, and OMC/DC.
+- Use [Troubleshooting First Run](/docs/blackbox/quickstart/troubleshooting-first-run) if the catalog, runner, or coverage output is missing.
diff --git a/src/content/docs/blackbox/quickstart/install.md b/src/content/docs/blackbox/quickstart/install.md
new file mode 100644
index 0000000..895f846
--- /dev/null
+++ b/src/content/docs/blackbox/quickstart/install.md
@@ -0,0 +1,90 @@
+---
+title: "Install Blackbox"
+description: "Show project-local installation, CLI verification, upgrade notes, and uninstall expectations."
+sidebar_position: 2
+keywords: ["install blackbox", "blackbox cli", "typescript package"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "install blackbox"
+ secondary_keywords: ["blackbox cli", "typescript package", "playwright docker testing"]
+ search_intent: "installation intent from developers adding Blackbox to a TypeScript system-test project"
+ snippet_angle: "install the Blackbox runtime/testbed package and optional CLI, then verify the binary and first system-test path"
+---
+
+## Abstract
+
+This page gets a repo from prerequisites to a verifiable install with the fewest moving parts.
+
+## Audience
+
+Developers who want to know the install worked before they try a full proof run.
+
+## What Success Looks Like
+
+1. The package is installed locally.
+2. The CLI is reachable.
+3. The version or help output matches the expected binary.
+4. The project is ready for the first proof run.
+
+## Project-Local Install
+
+Install the runtime/testbed package in the project that owns your system tests:
+
+```bash
+pnpm add -D @suites/blackbox
+```
+
+Add `testcontainers` packages only when your testbed uses the programmatic Testcontainers path. If your project already has Docker Compose, the first Blackbox dependency can stay focused on the kit.
+
+Install the CLI package when you want the `blackbox` binary for feature files, coverage replay, and static instrumentation commands:
+
+```bash
+pnpm add -D @suites/blackbox-cli
+```
+
+The current Blackbox repo uses `pnpm@9.15.4` and Node `>=22`.
+
+## Verify The CLI
+
+```bash
+pnpm exec blackbox --help
+pnpm exec blackbox features check --help
+```
+
+You should see the `features`, `coverage`, and `otel` command topics. If the binary is not found, confirm that `@suites/blackbox-cli` is installed in the same workspace package where you run the command.
+
+## Verify The Testbed Path
+
+The CLI does not replace your system-test command. Your project still owns the command that starts the topology and runs Playwright.
+
+In the Blackbox showcase repository, that command is:
+
+```bash
+pnpm test:system
+```
+
+That script delegates to the e2e package, builds the Blackbox package, builds the local bootstrap image, and runs Playwright.
+
+For your own project, create an equivalent project script once the testbed config and Playwright setup are in place.
+
+## Bootstrap Image
+
+Local development may need the OpenTelemetry bootstrap image:
+
+```bash
+pnpm build:otel-image
+```
+
+That builds `blackbox-otel-bootstrap:local` from the bootstrap Dockerfile. Packaged or CI setups may instead pull a published image or use `BLACKBOX_OTEL_IMAGE`.
+
+You do not need to add `@opentelemetry/*` packages, edit service Dockerfiles, or set `NODE_OPTIONS` by hand for the default testbed path.
+
+## Uninstall
+
+Remove the packages you installed and delete generated artifacts if you no longer need them:
+
+```bash
+pnpm remove @suites/blackbox @suites/blackbox-cli
+```
+
+Generated reports usually live under `.blackbox-coverage/` and can be deleted like other local test output.
diff --git a/src/content/docs/blackbox/quickstart/requirements.md b/src/content/docs/blackbox/quickstart/requirements.md
new file mode 100644
index 0000000..ca9db05
--- /dev/null
+++ b/src/content/docs/blackbox/quickstart/requirements.md
@@ -0,0 +1,63 @@
+---
+title: "Requirements and Supported Stacks"
+description: "List the runtime, OpenTelemetry, Playwright, Docker, and project assumptions before the first run."
+sidebar_position: 1
+keywords: ["blackbox requirements", "opentelemetry requirement", "playwright docker"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "blackbox requirements"
+ secondary_keywords: ["playwright docker testing", "opentelemetry system tests", "blackbox supported stacks"]
+ search_intent: "pre-install evaluation from developers checking whether Blackbox can run in their project"
+ snippet_angle: "list the Node, Docker, Playwright, and container assumptions before the first Blackbox run"
+---
+
+## Abstract
+
+This page is the gate before the first proof run. It explains what Blackbox needs from your system-test environment before it can collect runtime evidence and produce coverage artifacts.
+
+## Audience
+
+Developers who want to know whether Blackbox can run in their repo right now.
+
+## Supported Alpha Stack
+
+The current alpha path is aimed at Node services that can be started as containers and driven by Playwright system tests.
+
+| Requirement | Why Blackbox needs it |
+| --- | --- |
+| Node services | The current bootstrap instruments Node processes by loading a Blackbox OpenTelemetry bootstrap before app code starts. |
+| Docker or Docker Compose | Blackbox layers a generated test overlay on top of your runnable topology. |
+| Playwright system tests | Playwright drives the workflow while Blackbox collects the runtime evidence caused by that workflow. |
+| A service image with a shell | The current node wrapper is a POSIX shell script. Distroless images need a different wrapper and are a known limitation. |
+| A normal service command | Blackbox expects your service to start through `node`, for example `CMD ["node", "src/server.js"]`. |
+| Managed local dependencies | Databases, queues, caches, and local services should be owned by the test topology when possible. |
+
+Remote end-to-end environments can still be valuable, but they usually include unmanaged dependencies such as auth providers, email systems, payment providers, shared queues, or vendor APIs. Blackbox is strongest as a behavioral gate when the system under test and its dependencies are controlled enough for a failure to mean something specific.
+
+## What Blackbox Does Not Require
+
+You do not need to add OpenTelemetry code to production services. You also do not need to create a second test-only Dockerfile for each service in the default path.
+
+At test time, Blackbox uses an OpenTelemetry bootstrap image, a generated Docker Compose overlay, and a `node` wrapper mounted into the SUT container. The production-shaped service image remains the image being tested.
+
+## What Must Be True Before You Continue
+
+1. You can build and start the app or service under test.
+2. You can run at least one system test that reaches a real boundary.
+3. Your service starts through a Node binary path Blackbox can shadow.
+4. Docker can start the topology locally or in CI.
+5. You know which dependencies are managed by the test run and which are external.
+6. You have a writable artifact directory for reports such as `.blackbox-coverage/`.
+
+## Known Alpha Limits
+
+1. The current bootstrap path is Node-focused.
+2. Distroless service images are not the happy path because the wrapper needs a shell.
+3. Services with existing tracing agents such as Datadog or Sentry may need test-environment overrides.
+4. Remote E2E environments with unmanaged dependencies can produce noisy failures and should not be the first proof run.
+
+## What To Read Next
+
+1. [Install Blackbox](/docs/blackbox/quickstart/install)
+2. [Run with the Testbed](/docs/blackbox/guides/using-the-testbed)
+3. [What Blackbox Runs](/docs/blackbox/security-and-trust/what-blackbox-runs)
diff --git a/src/content/docs/blackbox/quickstart/troubleshooting-first-run.md b/src/content/docs/blackbox/quickstart/troubleshooting-first-run.md
new file mode 100644
index 0000000..ffb48ff
--- /dev/null
+++ b/src/content/docs/blackbox/quickstart/troubleshooting-first-run.md
@@ -0,0 +1,69 @@
+---
+title: "Troubleshooting First Run"
+description: "Help users recover from the common first-run failures before they leave the quickstart."
+sidebar_position: 4
+keywords: ["blackbox troubleshooting", "no spans captured", "first run"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Troubleshooting First Run"
+ secondary_keywords: ["blackbox troubleshooting", "no spans captured"]
+ search_intent: "debugging intent from developers whose first Blackbox run did not produce evidence"
+ snippet_angle: "classify first-run failures by install, Docker, Playwright, missing spans, missing catalog entries, and report output"
+---
+
+## Abstract
+
+Use this page when the first proof run does not produce a useful effect catalog or coverage report.
+
+## Audience
+
+Developers who hit a first-run error and need a fast way to classify it.
+
+## Common First-Run Failures
+
+| Symptom | Likely cause | First check |
+| --- | --- | --- |
+| `pnpm exec blackbox --help` fails | CLI package is not installed in the package where you ran it | Install `@suites/blackbox-cli`, or run from the workspace package that owns the dependency |
+| `pnpm test:system` fails before tests start | Docker, image build, or testbed startup failed | Run the app topology without Blackbox, then run `pnpm build:otel-image` in the Blackbox repo or configure the bootstrap image |
+| Playwright cannot find tests | Wrong test directory or config | Check the Playwright config and confirm it matches `*.system.test.ts` files |
+| HTTP assertion passes but no effects appear | The request did not carry trace context or the service process was not instrumented | Use the wrapped Playwright `request` fixture or pass the capture trace headers, then confirm the service starts through `node` |
+| No effect catalog appears | The matcher was not reached or the capture had no label | Confirm the flow is inside `test.system('<slug>', ...)` and the test calls `await expect(capture).toMatchCatalog()` |
+| Catalog exists but the run fails | A required effect disappeared or a forbidden effect appeared | Inspect the failure message before updating the catalog; the app may have regressed |
+| Reports are missing | Reporter/output config did not run or teardown failed | Check `.blackbox-coverage/` and the Playwright reporter configuration |
+
+## Recovery Pattern
+
+1. Confirm the baseline command runs: `pnpm test:system`.
+2. Confirm Docker can build and start the service topology.
+3. Confirm the test enters a `test.system('<slug>', ...)` block.
+4. Confirm the request is connected to the active capture.
+5. Confirm the test reaches `toMatchCatalog()`.
+6. Inspect the generated effects file before changing app code or catalog code.
+7. Inspect `.blackbox-coverage/` for reports and per-test evidence.
+
+## Missing Baseline
+
+On a new flow, `toMatchCatalog()` is allowed to pass when no catalog entry exists. The observation is recorded and materialized at fixture teardown.
+
+If no baseline is written:
+
+1. Make sure the test calls `await expect(capture).toMatchCatalog()`.
+2. Make sure the test is inside `test.system('<slug>', '<description>', () => { ... })`.
+3. Make sure the test completes teardown; a hard process failure can prevent artifact writing.
+4. Check whether the effects file already exists. Existing entries are not silently overwritten.
+
+## Missing Spans
+
+When the HTTP assertion passes but the effect catalog is empty, the system was exercised but the behavior was not captured.
+
+Check these first:
+
+1. The service starts through a `node` command that the wrapper can shadow.
+2. The test uses the Blackbox Playwright runner or fixtures.
+3. The request carries trace context from the active capture.
+4. Each service exposes the debug endpoint expected by the testbed.
+5. The dependency you expected to see is inside the managed test topology.
+
+## When To File An Issue
+
+File an issue when the topology starts, the request carries trace context, the service is instrumented, and Blackbox still fails to write a baseline or report. Include the command, Node version, Docker version, Playwright config, test file, generated effects file if any, and the contents of `.blackbox-coverage/`.
diff --git a/src/content/docs/blackbox/reference/api.md b/src/content/docs/blackbox/reference/api.md
new file mode 100644
index 0000000..261b874
--- /dev/null
+++ b/src/content/docs/blackbox/reference/api.md
@@ -0,0 +1,51 @@
+---
+title: "API Reference"
+description: "Define the public package API surface, stability expectations, and how it maps to the CLI."
+sidebar_position: 2
+keywords: ["blackbox api reference", "blackbox package api", "effect coverage api"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "API Reference"
+ secondary_keywords: ["blackbox api reference", "blackbox package api"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Define the public package API surface, stability expectations, and how it maps to the CLI.
+
+This page is the boundary between supported public APIs and internal implementation details. If a symbol or import path is not described here, treat it as unstable unless the project says otherwise.
+
+## Audience
+
+Developers who want to call Blackbox from code, build wrappers, or understand which exports are supported across releases.
+
+## What This Page Should Contain
+
+1. Stable public imports.
+2. Exported types and helpers.
+3. Async behavior and error shape.
+4. Mapping to the CLI.
+5. Explicit internal boundaries.
+
+## Content Outline
+
+1. State whether a stable public library API ships in the current alpha.
+2. List the supported imports, exported types, async behavior, and error shape.
+3. Map common API calls to their equivalent CLI workflows.
+4. Explain versioning guarantees and which modules are internal.
+5. Link to the Testbed API, Scenario DSL, catalog schema, and report format pages.
+
+## Practical Guidance
+
+1. Show a minimal import and call example.
+2. Explain which exports are safe for external code.
+3. Keep the internal modules clearly labeled.
+4. Call out any alpha-only behavior explicitly.
+
+## Evidence To Add
+
+- Minimal runnable package API examples.
+- Type signatures generated from the published package.
+- Clear alpha disclaimers for any API that is not yet stable.
diff --git a/src/content/docs/blackbox/reference/catalog-schema.md b/src/content/docs/blackbox/reference/catalog-schema.md
new file mode 100644
index 0000000..428a8c5
--- /dev/null
+++ b/src/content/docs/blackbox/reference/catalog-schema.md
@@ -0,0 +1,49 @@
+---
+title: "Catalog Schema"
+description: "Specify the effect catalog format, versioning, requires, forbids, and shape syntax."
+sidebar_position: 4
+keywords: ["catalog schema", "effect catalog v0.1", "yaml schema"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Catalog Schema"
+ secondary_keywords: ["catalog schema", "effect catalog v0.1"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Specify the effect catalog format, versioning, requires, forbids, and shape syntax.
+
+This page should specify the effect catalog format, versioning, requires, forbids, and shape syntax.
+
+## Audience
+
+These pages are complete references for commands, APIs, configuration, files, reports, and exit codes.
+
+## What This Page Should Contain
+
+1. The schema version and envelope.
+2. Required and optional fields.
+3. Requires and forbids structure.
+4. How shapes and catalog entries are represented.
+
+## Content Outline
+
+1. List the complete surface area.
+2. Mark stable public API versus internal or alpha behavior.
+3. Document inputs, outputs, defaults, errors, and versioning.
+4. Point back to guides for examples.
+
+## Practical Guidance
+
+1. Show one complete catalog example.
+2. Explain versioning at the top of the page.
+3. Keep the schema terms aligned with the concept pages.
+4. State what happens when a field is missing or unsupported.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/reference/cli.md b/src/content/docs/blackbox/reference/cli.md
new file mode 100644
index 0000000..b7b7897
--- /dev/null
+++ b/src/content/docs/blackbox/reference/cli.md
@@ -0,0 +1,141 @@
+---
+title: "CLI Reference"
+description: "Catalog all commands, arguments, output, safety level, scripting behavior, and exit codes."
+sidebar_position: 1
+keywords: ["blackbox cli", "cli reference", "blackbox commands"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "blackbox cli"
+ secondary_keywords: ["cli reference", "feature files cli", "omcdc coverage replay"]
+ search_intent: "reference intent from developers scripting Blackbox feature, coverage, and instrumentation commands"
+ snippet_angle: "catalog the Blackbox CLI commands, what they read and write, JSON support, dry-run support, and CI safety"
+---
+
+## Abstract
+
+This page is the machine-facing contract for the `blackbox` CLI. It answers three questions quickly: what command should I run, what does it change, and is it safe to script.
+
+## Audience
+
+Developers and automation authors wiring Blackbox into local scripts, CI gates, and agent workflows.
+
+## Command Shape
+
+The public binary is `blackbox`, provided by `@suites/blackbox-cli`. Commands use a space topic separator:
+
+```bash
+blackbox features emit ./tests --out ./features
+blackbox coverage replay --coverage-dir .blackbox-coverage
+```
+
+Use `blackbox features emit`, not `blackbox features:emit`.
+
+## Command Families
+
+The CLI has three command families:
+
+1. `features`: generate, lint, drift-check, reshape, and compare feature artifacts.
+2. `coverage`: replay OMC/DC reports from saved runtime evidence.
+3. `otel`: build-time static OpenTelemetry instrumentation utilities.
+
+## Command Matrix
+
+| Command | Job | Reads | Writes | JSON | Dry run | Stability |
+| --- | --- | --- | --- | --- | --- | --- |
+| `blackbox features emit [paths...]` | Decompile Playwright or BDD-DSL tests into `.feature` files. | Test source files; optional step library. | `.feature` files under `--out` or `./features`. | No | No | Alpha public |
+| `blackbox features lint [paths...]` | Run structural rules against test sources. | Test source files. | Nothing. | Yes, `--json` | N/A | Alpha public |
+| `blackbox features drift` | Detect generated feature files that drifted from source tests. | `--tests`, `--features`, optional steps. | Nothing. | No | N/A | Alpha public |
+| `blackbox features check` | Validate `.feature` syntax and source/feature drift. | `--features`, `--tests`. | Nothing. | Yes, `--json` | N/A | Alpha public |
+| `blackbox features reshape [paths...]` | Rewrite Playwright system tests into Blackbox closure-DSL shape. | Test source files. | `--write` writes reshaped tests under `--out`; otherwise prints source. | No | Yes, `--dry-run` | Alpha public, state-changing |
+| `blackbox features compare-observations` | Compare observation-reporter outputs from two runs. | `--baseline`, `--candidate` directories with `.observation.json`. | Nothing. | Yes, `--json` | N/A | Experimental |
+| `blackbox features experimental wrap [paths...]` | Annotate Playwright specs so the Gherkin reporter can emit feature files at runtime. | Test source files. | Only with `--write`; otherwise prints what would change. | No | Implicit preview without `--write` | Experimental |
+| `blackbox features experimental scaffold [paths...]` | Generate starter closure-DSL tests from `.feature` files. | `.feature` files. | Only with `--write`; otherwise prints generated source. | No | Implicit preview without `--write` | Experimental |
+| `blackbox coverage replay` | Recompute OMC/DC reports from saved `.blackbox-coverage` evidence. | `--coverage-dir`; optional service source map. | Report files under `--out` or coverage dir. | No | No | Alpha public, state-changing |
+| `blackbox otel instrument` | Transform source files with static OpenTelemetry function-span instrumentation. | `--input` source tree; optional config. | Instrumented source tree under `--output`. | No | No | Advanced/experimental |
+
+## Feature Commands
+
+### `features emit`
+
+```bash
+blackbox features emit ./tests --out ./features
+blackbox features emit ./tests --steps ./scripts/step-lib.json
+blackbox features emit ./tests --no-steps
+```
+
+Defaults to reading `tests` and writing to `features` when no paths or `--out` are supplied. This command writes files and should be reviewed before committing generated feature changes.
+
+### `features lint`
+
+```bash
+blackbox features lint ./tests
+blackbox features lint ./tests --json
+blackbox features lint ./tests --fail-on error --scope backend
+```
+
+Read-only. `--fail-on` accepts `error`, `warn`, or `info`. `--scope` accepts `backend`, `browser-only`, or `all`.
+
+### `features drift`
+
+```bash
+blackbox features drift --tests ./tests --features ./features
+blackbox features drift --no-steps
+```
+
+Read-only. Use it when feature files are generated artifacts that must stay synchronized with source tests.
+
+### `features check`
+
+```bash
+blackbox features check
+blackbox features check --features ./features --tests ./tests
+blackbox features check --skip-drift --json
+```
+
+Read-only. Defaults to `--features ./features` and `--tests ./tests`. Use this as the durable CI gate for feature syntax plus drift.
+
+### `features reshape`
+
+```bash
+blackbox features reshape ./tests/my.spec.ts --dry-run
+blackbox features reshape ./tests/my.spec.ts --write
+blackbox features reshape ./tests/my.spec.ts --out ./reshaped --testbed ./testbed.js
+```
+
+State-changing only with `--write`. `--dry-run` and `--write` are mutually exclusive.
+
+## Coverage Commands
+
+### `coverage replay`
+
+```bash
+blackbox coverage replay --coverage-dir .blackbox-coverage --out reports
+blackbox coverage replay --no-html
+blackbox coverage replay --service bff=/path/to/bff/src --service order=/path/to/order/src
+```
+
+Replays reports from saved runtime evidence. By default it writes OMC/DC JSON, Markdown, HTML, Istanbul `coverage-final.json`, and Istanbul HTML. With `--no-html`, it writes only `omcdc-propagation.json` and `omcdc-propagation.md`.
+
+## Static Instrumentation Commands
+
+### `otel instrument`
+
+```bash
+blackbox otel instrument --input ./src --output ./instrumented --config ./otel.json
+blackbox otel instrument -i ./src -o ./instrumented --include 'services/**/*.ts' --verbose
+```
+
+This is a build-time instrumentation command. It walks `--input`, transforms matching files, and writes the output tree to `--output`. It is separate from the default testbed bootstrap path.
+
+## Practical Defaults
+
+1. Use `features check --json` in automation when you need structured feature syntax and drift output.
+2. Run `features reshape --dry-run` before any `features reshape --write` flow.
+3. Treat `coverage replay` as a report regeneration command over saved evidence, not as the command that runs the system test.
+4. Use project scripts such as `pnpm test:system` to run the actual system test and collect evidence.
+
+## Related Pages
+
+1. [Exit Codes](/docs/blackbox/reference/exit-codes)
+2. [Files and Artifacts](/docs/blackbox/reference/files-and-artifacts)
+3. [Report Formats](/docs/blackbox/reference/report-formats)
diff --git a/src/content/docs/blackbox/reference/configuration.md b/src/content/docs/blackbox/reference/configuration.md
new file mode 100644
index 0000000..65cc3e4
--- /dev/null
+++ b/src/content/docs/blackbox/reference/configuration.md
@@ -0,0 +1,56 @@
+---
+title: "Configuration"
+description: "List configuration locations, defaults, precedence, validation, and environment-specific options."
+sidebar_position: 6
+keywords: ["blackbox configuration", "config reference", "environment config"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Configuration"
+ secondary_keywords: ["blackbox configuration", "config reference"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+List configuration locations, defaults, precedence, validation, and environment-specific options.
+
+This page should answer where configuration lives, how precedence works, and which settings are required for a run to succeed.
+
+## Audience
+
+These pages are complete references for commands, APIs, configuration, files, reports, and exit codes.
+
+## What This Page Should Contain
+
+1. Configuration locations and formats.
+2. Precedence between flags, env vars, and config files.
+3. Defaults and required fields.
+4. Environment-specific overrides and validation rules.
+
+## Practical Sections
+
+1. Testbed configuration.
+2. Reporter configuration.
+3. Runtime and instrumentation configuration.
+4. CI overrides and local overrides.
+
+## Content Outline
+
+1. List the complete surface area.
+2. Mark stable public API versus internal or alpha behavior.
+3. Document inputs, outputs, defaults, errors, and versioning.
+4. Point back to guides for examples.
+
+## Practical Defaults
+
+1. Show a minimal working config first.
+2. Separate required options from optional tuning.
+3. State how to verify that config was applied.
+4. Explain what breaks when a setting is wrong.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/reference/environment-variables.md b/src/content/docs/blackbox/reference/environment-variables.md
new file mode 100644
index 0000000..d0c9461
--- /dev/null
+++ b/src/content/docs/blackbox/reference/environment-variables.md
@@ -0,0 +1,49 @@
+---
+title: "Environment Variables"
+description: "List supported environment variables and how they affect capture, reports, and testbed behavior."
+sidebar_position: 7
+keywords: ["environment variables", "blackbox env vars", "otel config"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Environment Variables"
+ secondary_keywords: ["environment variables", "blackbox env vars"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+List supported environment variables and how they affect capture, reports, and testbed behavior.
+
+This page should explain which variables influence capture, reporting, and the testbed, and how they interact with config files and CLI flags.
+
+## Audience
+
+These pages are complete references for commands, APIs, configuration, files, reports, and exit codes.
+
+## What This Page Should Contain
+
+1. Each supported variable and its purpose.
+2. Whether it affects capture, reporting, or testbed behavior.
+3. Whether it is required, optional, or experimental.
+4. The precedence relative to config files and CLI flags.
+
+## Content Outline
+
+1. List the complete surface area.
+2. Mark stable public API versus internal or alpha behavior.
+3. Document inputs, outputs, defaults, errors, and versioning.
+4. Point back to guides for examples.
+
+## Practical Guidance
+
+1. Group variables by subsystem.
+2. State defaults clearly.
+3. Call out the variables that are only for debugging or CI.
+4. Explain what happens if a variable is missing or conflicting.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/reference/exit-codes.md b/src/content/docs/blackbox/reference/exit-codes.md
new file mode 100644
index 0000000..f5de6df
--- /dev/null
+++ b/src/content/docs/blackbox/reference/exit-codes.md
@@ -0,0 +1,56 @@
+---
+title: "Exit Codes"
+description: "Define CLI exit codes for clean runs, findings, usage errors, fatal errors, and CI scripts."
+sidebar_position: 9
+keywords: ["exit codes", "ci scripting", "blackbox cli errors"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "exit codes"
+ secondary_keywords: ["ci scripting", "blackbox cli errors", "feature drift exit code"]
+ search_intent: "automation reference intent from users wiring Blackbox commands into CI scripts"
+ snippet_angle: "document command-specific Blackbox exit codes for clean runs, drift, findings, write safety, and fatal errors"
+---
+
+## Abstract
+
+This page documents command-specific exit codes that CI and scripts can use without parsing prose.
+
+## Audience
+
+Developers writing shell scripts, CI jobs, and agent loops around the `blackbox` CLI.
+
+## General Rule
+
+`0` means the command completed cleanly. Nonzero codes are command-specific today. Do not assume every command uses the same meaning for `1` and `2` during the alpha.
+
+## Command Exit Codes
+
+| Command | `0` | `1` | `2` |
+| --- | --- | --- | --- |
+| `features emit` | Feature files emitted. | Not used by the command implementation. | Uncaught command/framework errors may exit nonzero. |
+| `features lint` | No findings at or above `--fail-on`. | At least one finding met `--fail-on`. | Uncaught command/framework errors may exit nonzero. |
+| `features drift` | Source tests and feature files are in sync. | Drift detected: missing, stale, orphan, or unparseable feature files. | Missing input directory or analysis failure. |
+| `features check` | Syntax and drift checks passed, or skipped checks passed. | Syntax failure or drift detected. | Framework or unexpected failure. |
+| `features reshape` | Reshape completed, or only skipped/already-BDD/no-test files were found. | Unsafe fallback, parse-error fallback, bad flags, missing paths, or no matched files. | Transform exception while processing a file. |
+| `features compare-observations` | Baseline and candidate observations are semantically equivalent. | Meaningful difference or missing observation pair. | Missing arguments, missing directory, malformed file, or no traces found. |
+| `features experimental wrap` | Completed preview or write. | Not used by the command implementation. | Uncaught command/framework errors may exit nonzero. |
+| `features experimental scaffold` | Completed preview or write. | Not used by the command implementation. | Uncaught command/framework errors may exit nonzero. |
+| `coverage replay` | Reports written, or no artifacts found. | Report generation completed with captured propagation or Istanbul errors. | Framework or unexpected failure. |
+| `otel instrument` | Transform completed. | Parse/config/walk/write error. | Not used by the command implementation. |
+
+## Practical Guidance
+
+1. Treat `features check` exit `1` as a normal CI gate failure, not a tool crash.
+2. Treat `features drift` exit `1` as generated feature files being out of sync.
+3. Treat `features compare-observations` exit `1` as semantic drift between runs.
+4. Treat `features reshape` exit `1` as unsafe or incomplete output that needs review before write/commit.
+5. Treat exit `2` as setup, input, or transform failure where the command could not produce a trustworthy result.
+
+## CI Example
+
+```bash
+blackbox features check --features ./features --tests ./tests --json
+pnpm test:system
+```
+
+The first command gates feature syntax and drift. The second command is the project-owned system-test command that collects runtime evidence and produces reports.
diff --git a/src/content/docs/blackbox/reference/files-and-artifacts.md b/src/content/docs/blackbox/reference/files-and-artifacts.md
new file mode 100644
index 0000000..d6bfb6d
--- /dev/null
+++ b/src/content/docs/blackbox/reference/files-and-artifacts.md
@@ -0,0 +1,120 @@
+---
+title: "Files and Artifacts"
+description: "Document files Blackbox reads, writes, modifies, and expects teams to commit or ignore."
+sidebar_position: 8
+keywords: ["blackbox artifacts", "generated files", "git policy"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "blackbox artifacts"
+ secondary_keywords: ["generated files", "omcdc report", "effect catalog", "feature files"]
+ search_intent: "reference intent from users who need to know which Blackbox files are inputs, outputs, review artifacts, or temporary evidence"
+ snippet_angle: "map feature files, effects YAML, spans, V8 coverage, OMC/DC reports, and CI artifacts to their purpose and git policy"
+---
+
+## Abstract
+
+This page tells you what lives in the workspace, what gets generated, what is ephemeral, and what is likely worth committing.
+
+## Audience
+
+Developers deciding what to commit, what to ignore, what to archive from CI, and what to review when behavior changes.
+
+## Artifact Families
+
+Blackbox has four artifact families:
+
+1. **Behavior specs:** `.feature` files that make scenarios readable and reviewable.
+2. **Effect contracts:** `.effects.yaml` files that declare required and forbidden runtime effects.
+3. **Runtime evidence:** spans and V8 coverage captured from a real system-test run.
+4. **Reports:** OMC/DC, catalog, shape, HTML, Markdown, JSON, XML, and CI-facing outputs.
+
+The first two are usually reviewed like source. The last two are generated evidence and should be treated according to the workflow you choose.
+
+## Files Blackbox Reads
+
+| File or directory | Purpose | Usually committed? |
+| --- | --- | --- |
+| `blackbox-testbed.ts` | Points Blackbox at the runnable topology, services, source directories, ports, and artifact directory. | Yes |
+| `docker-compose.yml` or equivalent topology config | Starts the SUT and managed dependencies. | Yes |
+| `e2e/features/*.feature` | Runtime-backed behavior spec surface. | Yes, if feature artifacts are part of review |
+| `e2e/tests/__effects__/*.effects.yaml` | Effect catalog entries for required and forbidden behavior. | Yes |
+| System-test files | Drive the workflow that creates evidence. | Yes |
+| Service source directories | Used to resolve OMC/DC branch locations and snippets. | Yes, as normal source |
+
+## Files Blackbox Writes
+
+The default artifact directory in the showcase is `.blackbox-coverage/`. Your project may configure a different directory.
+
+| Artifact | What it means | Primary reader | Git policy |
+| --- | --- | --- | --- |
+| `.blackbox-coverage/omcdc-propagation.json` | Machine-readable OMC/DC propagation report. | Tools, CI, agents | Usually ignored; archive in CI when useful |
+| `.blackbox-coverage/omcdc-propagation.md` | Markdown form of the OMC/DC report. | Humans in review or editor | Usually ignored, sometimes attached to PR/CI |
+| `.blackbox-coverage/omcdc.html` | Interactive branch-by-branch OMC/DC report. | Humans debugging coverage | Ignore; publish or attach as CI artifact |
+| `.blackbox-coverage/coverage.json` | Effect catalog coverage summary. | Tools and reviewers | Usually ignored; useful for CI comparison |
+| `.blackbox-coverage/shape-coverage.json` | Boundary-shape coverage summary. | Tools and reviewers | Usually ignored; useful for CI comparison |
+| `.blackbox-coverage/omcdc.junit.xml` | JUnit XML form when the JUnit reporter is enabled. | CI test report UI | Ignore; CI consumes it |
+| `.blackbox-coverage/coverage-final.json` | Istanbul-compatible coverage data. | Coverage tooling | Ignore; archive when needed |
+| `.blackbox-coverage/html/index.html` | Istanbul HTML coverage report. | Humans comparing code coverage | Ignore; publish or attach as CI artifact |
+| `.blackbox-coverage/spans/*.json` | Per-test runtime spans collected from SUT debug endpoints. | Diagnostics, replay, agents | Ignore; archive only for debugging |
+| `.blackbox-coverage/v8-per-test/*.json` | Per-test V8 coverage captured from SUT processes. | OMC/DC engine, replay | Ignore; archive only for debugging |
+
+## Feature And Effect Files
+
+Feature files and effect files are different artifacts and should not be collapsed into one mental bucket.
+
+Feature files are the readable behavior surface. They explain the workflow in Given/When/Then-style language and are useful for review, product discussion, and stale-spec detection.
+
+Effect files are the executable behavior contract. They declare concrete required and forbidden effects such as Redis reads, Postgres writes, HTTP calls, queue messages, or forbidden deletes/refunds.
+
+You can use either layer independently:
+
+1. Existing system tests can produce runtime evidence before feature files exist.
+2. Existing BDD teams can keep feature files and add effect contracts later.
+3. Teams focused on CI gates can start with effect files and reports.
+4. Teams focused on documentation can start by generating feature artifacts.
+
+## Artifact Routing
+
+Blackbox can write artifacts to files, stdout, or CI-facing surfaces. The key question is not where every byte goes; it is which outputs are durable review artifacts and which are transient plumbing.
+
+1. File output is for durable review and later comparison.
+2. Stdout is for quick inspection and scripting.
+3. CI output is for gate signals and annotations.
+4. The same proof can be routed differently without changing what was proven.
+
+## Reporter And Sink Defaults
+
+By default, Blackbox enables these reporters:
+
+```bash
+BLACKBOX_REPORTERS=json,markdown,html,catalog-json,shape-json
+```
+
+JUnit is opt-in:
+
+```bash
+BLACKBOX_REPORTERS=json,markdown,html,catalog-json,shape-json,junit
+```
+
+By default, Blackbox writes files. In GitHub Actions, the default sink expands to files plus GitHub Actions annotations.
+
+```bash
+BLACKBOX_SINKS=file
+BLACKBOX_SINKS=file,stdout,github-actions
+```
+
+The file sink writes artifacts under the configured artifact directory. For backwards compatibility, `BLACKBOX_COVERAGE_OUTPUT` can override the path for `coverage.json` only.
+
+## Practical Defaults
+
+1. Commit testbed config, scenarios, feature files, and effect catalogs when they are part of the durable workflow.
+2. Ignore `.blackbox-coverage/` by default.
+3. Archive `.blackbox-coverage/` in CI when a failure needs investigation.
+4. Attach `omcdc.html` and `omcdc-propagation.md` to CI or PRs when reviewers need branch-level context.
+5. Treat span and V8 files as diagnostic evidence, not hand-edited source.
+
+## Figure Placeholder
+
+**Caption:** The Blackbox artifact map: feature files and effects as durable behavior surfaces; spans, V8 coverage, and reports as generated runtime evidence.
+
+**Slot:** `<!-- TODO: insert artifact map diagram or interactive file tree here -->`
diff --git a/src/content/docs/blackbox/reference/matchers-and-effect-builders.md b/src/content/docs/blackbox/reference/matchers-and-effect-builders.md
new file mode 100644
index 0000000..1f3dccc
--- /dev/null
+++ b/src/content/docs/blackbox/reference/matchers-and-effect-builders.md
@@ -0,0 +1,49 @@
+---
+title: "Matchers and Effect Builders"
+description: "Document matchers, effect builders, shape helpers, and stable public imports."
+sidebar_position: 3
+keywords: ["effect builders", "matchers", "toMatchCatalog"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Matchers and Effect Builders"
+ secondary_keywords: ["effect builders", "matchers"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Document matchers, effect builders, shape helpers, and stable public imports.
+
+This page should explain how tests express effect assertions and how those assertions connect to the catalog and report formats.
+
+## Audience
+
+These pages are complete references for commands, APIs, configuration, files, reports, and exit codes.
+
+## What This Page Should Contain
+
+1. The supported matcher functions.
+2. The supported effect builders or shape helpers.
+3. Examples of asserting required and forbidden effects.
+4. The stable import surface versus internal helpers.
+
+## Content Outline
+
+1. List the complete surface area.
+2. Mark stable public API versus internal or alpha behavior.
+3. Document inputs, outputs, defaults, errors, and versioning.
+4. Point back to guides for examples.
+
+## Practical Guidance
+
+1. Show the simplest matcher first.
+2. Pair each matcher with one effect example.
+3. Keep the output shape consistent with the report pages.
+4. Explain the failure mode when a matcher does not find the expected effect.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/reference/report-formats.md b/src/content/docs/blackbox/reference/report-formats.md
new file mode 100644
index 0000000..e3e5ae8
--- /dev/null
+++ b/src/content/docs/blackbox/reference/report-formats.md
@@ -0,0 +1,111 @@
+---
+title: "Report Formats"
+description: "Describe coverage, shape coverage, and propagation outputs as machine-readable artifacts."
+sidebar_position: 5
+keywords: ["report formats", "coverage json", "shape coverage json"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "report formats"
+ secondary_keywords: ["coverage json", "omcdc json", "shape coverage json", "junit coverage report"]
+ search_intent: "reference intent from users and automation authors consuming Blackbox generated reports"
+ snippet_angle: "explain each Blackbox report file, its producer, format, consumer, and stability expectation"
+---
+
+## Abstract
+
+Blackbox writes several report formats from the same run. This page explains which file belongs to which stage, what each file is for, and how stable each output is.
+
+## Audience
+
+People who need to consume, parse, archive, or compare the artifacts Blackbox produces.
+
+## Artifact Family
+
+| Reporter token | Artifact | Format | Purpose |
+| --- | --- | --- | --- |
+| `json` | `omcdc-propagation.json` | JSON | Machine-readable OMC/DC propagation report. |
+| `markdown` | `omcdc-propagation.md` | Markdown | Human-readable OMC/DC report for reviews and editor inspection. |
+| `html` | `omcdc.html` | HTML | Interactive OMC/DC report with branch-level inspection. |
+| `catalog-json` | `coverage.json` | JSON | Effect catalog coverage summary. |
+| `shape-json` | `shape-coverage.json` | JSON | Boundary-shape coverage summary. |
+| `junit` | `omcdc.junit.xml` | XML | CI-facing test-result view of OMC/DC verdicts. |
+
+## Stability Notes
+
+1. `coverage.json` and `shape-coverage.json` are compact summaries and are the safest starting point for automation.
+2. `omcdc-propagation.json` is machine-readable but carries detailed branch and verdict data that may evolve while the alpha engine evolves.
+3. Markdown and HTML reports are review artifacts. They are meant to be read, attached, and linked, not parsed as stable APIs.
+4. `omcdc.junit.xml` is designed for CI systems that already understand JUnit XML.
+5. Per-test span and V8 files are diagnostic inputs, not public report formats.
+
+## What Each Artifact Is For
+
+### `omcdc-propagation.json`
+
+Contains endpoints, branch coordinates, true-arm test IDs, false-arm test IDs, not-observed test IDs, verdicts, hints, and observed effect shapes. Use it when an agent or tool needs to understand why a branch is propagating, masked, or still a gap.
+
+### `omcdc-propagation.md`
+
+Contains the same OMC/DC story in a reviewable form: endpoint sections, verdict counts, branch tables, hints, and oracle data per branch. Use it when a reviewer needs to understand the result without opening the interactive report.
+
+### `omcdc.html`
+
+The interactive OMC/DC report. Use it when a developer needs to inspect branches, hints, source snippets when available, and the relationship between decisions and observed effects.
+
+### `coverage.json`
+
+Summarizes effect catalog entry coverage. It answers whether catalog entries were seen, satisfied, failed, or uncovered.
+
+The shape is based on:
+
+1. `catalog`: service name, entry count, and catalog API version.
+2. `totals`: seen, satisfied, failed, and uncovered counts.
+3. `perEntry`: per-catalog-entry state, run count, pass count, and failure count.
+
+### `shape-coverage.json`
+
+Summarizes effect shapes, not whole catalog entries. It answers whether declared or inline boundary shapes were asserted and observed.
+
+Shape states are:
+
+1. `asserted`: declared in the catalog and named by a matcher.
+2. `unasserted`: declared in the catalog but never named by a matcher.
+3. `inline`: named by a matcher but not declared in the catalog.
+
+### `omcdc.junit.xml`
+
+Maps OMC/DC verdicts into CI test-result vocabulary:
+
+| OMC/DC verdict | JUnit mapping |
+| --- | --- |
+| `propagating` | pass |
+| `masking-candidate` | failure |
+| `coverage-gap` | skipped |
+| `undecidable` | pass with `system-out` |
+| `multi-arm` | pass with `system-out` |
+| `unsupported-mcdc` | pass with `system-out` |
+
+## Artifact Delivery
+
+Reporters render artifacts. Sinks deliver them.
+
+That separation matters: the same proof can become files, stdout output, GitHub Actions annotations, or CI test results without changing the evidence or the coverage model.
+
+The GitHub Actions sink reads `omcdc-propagation.json` and emits workflow annotations for actionable verdicts:
+
+1. `masking-candidate` becomes a warning.
+2. `coverage-gap` becomes a notice.
+3. Other verdicts are silent.
+
+## Practical Reading Order
+
+1. Start with the filename.
+2. Check whether the output is JSON, Markdown, HTML, or XML.
+3. Check whether it is intended for humans or automation.
+4. Use the related concept pages if you need the model behind it.
+
+## Figure Placeholder
+
+**Caption:** The artifact family Blackbox emits for review and automation.
+
+**Slot:** `<!-- TODO: insert artifact gallery or report-format comparison image here -->`
diff --git a/src/content/docs/blackbox/reference/scenario-dsl.md b/src/content/docs/blackbox/reference/scenario-dsl.md
new file mode 100644
index 0000000..7526e2d
--- /dev/null
+++ b/src/content/docs/blackbox/reference/scenario-dsl.md
@@ -0,0 +1,146 @@
+---
+title: "Scenario DSL"
+description: "Reference the Blackbox BDD scenario DSL, including scenario, background, given, when, then, given.each, outline, shared, and isolated flows."
+sidebar_position: 2
+keywords: ["scenario dsl", "scenario api", "bdd dsl reference", "given when then"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Scenario DSL"
+ secondary_keywords: ["scenario dsl", "scenario api", "given when then", "bdd dsl reference"]
+ search_intent: "developers who want the public Blackbox scenario DSL surface and its mapping to generated feature files"
+ snippet_angle: "document the Blackbox scenario DSL verbs and how they map to AAA, Gherkin, isolation, shared state, outlines, and feature generation"
+---
+
+The Scenario DSL is Blackbox's explicit BDD authoring surface.
+
+Use it when plain Playwright tests are not structured enough for faithful feature generation, or when the team wants scenarios to be readable in code before they become Gherkin.
+
+The DSL gives Blackbox stronger intent than decompiling arbitrary test code because the author names the behavior grammar directly:
+
+```text
+Given* When+ Then+
+```
+
+`Then` is the conclusion of the behavior. A scenario without a `Then` may execute code, but it does not express an observable claim.
+
+## Minimal Scenario
+
+```ts
+import { expect, scenario } from './testbed.js';
+
+scenario('subscribe-flow', 'subscribing to the pro tier', ({ given, background }) => {
+ background('the system is reset', async ({ system }) => {
+ await system.reset();
+ });
+
+ given('alice is an existing user with no active subscription', async ({ request, system, when }) => {
+ await when('alice POSTs /subscriptions with a valid card', async ({ then }) => {
+ const response = await request.post(`${system.bff.hostBaseUrl}/subscriptions`, {
+ data: { userId: 'alice', paymentMethodId: 'pm_card_visa' },
+ });
+
+ await then('the response status is 201', async () => {
+ expect(response.status()).toBe(201);
+ });
+ });
+ });
+});
+```
+
+This maps to:
+
+```gherkin
+@flow:subscribe-flow
+Feature: subscribing to the pro tier
+
+ Background:
+ Given the system is reset
+
+ Scenario: alice is an existing user with no active subscription
+ When alice POSTs /subscriptions with a valid card
+ Then the response status is 201
+```
+
+## Verbs
+
+| Verb | Purpose | Gherkin mapping |
+| --- | --- | --- |
+| `scenario(slug, description, body)` | Define a behavior flow with a stable slug and human description | `@flow:<slug>` and `Feature: <description>` |
+| `background(label, fn)` | Shared setup that runs before each scenario inside the scenario body | `Background: Given <label>` |
+| `given(precondition, fn)` | Define the scenario precondition and arrangement frame | `Scenario: <precondition>` plus arrangement lines |
+| `when(action, fn)` | Define the action being exercised | `When <action>` |
+| `then(expectation, fn)` | Define an observable assertion | `Then <expectation>` or `And <expectation>` |
+| `given.each(rows)(precondition, fn)` | Define a scenario outline from row data | `Scenario Outline` and `Examples` |
+| `outline(slug, description, rows, body)` | Define a parameterized flow directly | `Scenario Outline` and `Examples` |
+| `scenario.isolated(...)` | Mark a scenario that needs a fresh isolation group | Same Gherkin; isolation is runtime metadata |
+| `scenario.shared(parentSlug, slug, description, body)` | Join a serial flow to a parent scenario's isolation group | Same Gherkin; shared-state chain is runtime metadata |
+
+## Isolation Verbs
+
+Use `scenario.isolated` when sibling scenarios must not share system state. This is the shape the reshaper uses for `test.describe.parallel(...)` siblings.
+
+Use `scenario.shared(parentSlug, ...)` when a serial chain intentionally carries state from one scenario to the next. The parent slug must already be registered. This is the shape the reshaper uses for serial describe chains.
+
+Use `outline` or `given.each` when the same behavior should run over rows of examples.
+
+## How The Analyzer Reads The DSL
+
+The `blackbox-features` analyzer detects BDD-DSL files by looking for `scenario(...)` plus BDD verbs such as `given`, `when`, `then`, or `background`.
+
+From there it builds an analyzed feature:
+
+| DSL element | Analyzed feature field |
+| --- | --- |
+| `scenario(slug, description, ...)` | feature description and `@<slug>` tag |
+| `background(label, ...)` | background step with `given` phase |
+| `given(label, ...)` | scenario and first `given` step |
+| `when(label, ...)` | `when` step |
+| `then(label, ...)` | `then` step |
+| `given.each([...])` | scenario examples table |
+
+This is more reliable than decompiling arbitrary Playwright because the behavior phases are explicit.
+
+## Lint Rules That Apply
+
+`features lint` applies to DSL-authored and decompiled scenarios.
+
+The most important rules are:
+
+| Rule | Why it matters |
+| --- | --- |
+| `aaa-shape` | Enforces `Given* When+ Then+` in that order |
+| `missing-then` | Prevents scenarios with no observable conclusion |
+| `opaque-step` | Warns when decompiled text is too generic to review |
+| `placeholder-token` | Warns when generated placeholders are unresolved |
+| `missing-background` | Suggests `Background` when setup repeats |
+| `imperative-scenario` | Flags overly low-level UI action lists |
+| `empty-scenario` | Blocks scenarios with no steps |
+
+## Relationship To Feature Files
+
+The DSL is not a replacement for `.feature` files. It is the source shape that makes feature files more faithful.
+
+The normal path is:
+
+1. Author or reshape a test into the Scenario DSL.
+2. Run `blackbox features lint`.
+3. Run `blackbox features emit`.
+4. Commit the generated `.feature` file if it is part of the review surface.
+5. Run `blackbox features check` in CI to catch syntax failure and feature-file drift.
+
+## Relationship To Runtime Effects
+
+The Scenario DSL names behavior. Effects prove boundary behavior.
+
+A `then(...)` block may contain ordinary response assertions, effect catalog matchers, or both. Feature files remain readable; effect catalogs and coverage reports carry the runtime proof.
+
+## Stability
+
+The DSL surface is alpha. The core grammar is stable enough to document: scenarios should arrange, act, and conclude. Migration helpers such as reshape, scaffold, and wrap may change faster than the hand-authored DSL.
+
+## What To Read Next
+
+1. [Writing Scenarios](/docs/blackbox/guides/writing-scenarios)
+2. [Generating Feature Files](/docs/blackbox/guides/generating-feature-files)
+3. [Feature Files, BDD, and Staleness](/docs/blackbox/concepts/feature-files-and-staleness)
+4. [CLI Reference](/docs/blackbox/reference/cli)
diff --git a/src/content/docs/blackbox/reference/testbed-api.md b/src/content/docs/blackbox/reference/testbed-api.md
new file mode 100644
index 0000000..4ba4083
--- /dev/null
+++ b/src/content/docs/blackbox/reference/testbed-api.md
@@ -0,0 +1,50 @@
+---
+title: "Testbed API"
+description: "Document the supported helpers for running Blackbox against an isolated testbed."
+sidebar_position: 3
+keywords: ["blackbox testbed api", "testbed reference", "blackbox integration testing"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Testbed API"
+ secondary_keywords: ["blackbox testbed api", "testbed reference"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Document the supported helpers for running Blackbox against an isolated testbed.
+
+This page should explain the testbed as an integration boundary and show the supported helpers that manage startup, readiness, evidence, and cleanup.
+
+## Audience
+
+Teams that need repeatable local or CI runs against a controlled system under test.
+
+## What This Page Should Contain
+
+1. The supported testbed helpers.
+2. The lifecycle they own.
+3. The inputs they expect and the outputs they produce.
+4. The difference between a testbed and a plain compose stack.
+
+## Content Outline
+
+1. Define what the testbed owns: process startup, containers, service readiness, trace collection, and cleanup.
+2. List the supported helpers and the lifecycle they participate in.
+3. Show how a scenario starts, exercises, observes, and tears down a testbed.
+4. Explain how the testbed differs from using an existing Docker Compose stack.
+5. Link to troubleshooting pages for Docker, readiness, and missing spans.
+
+## Practical Guidance
+
+1. Show one minimal helper flow.
+2. Call out the supported defaults before customization.
+3. Explain what the testbed cleans up for the user.
+4. State what to do when readiness or trace capture fails.
+
+## Evidence To Add
+
+- Minimal code example from the showcase system.
+- Table of supported options and defaults.
+- Failure examples with the diagnostic output users should expect.
diff --git a/src/content/docs/blackbox/security-and-trust/data-and-telemetry.md b/src/content/docs/blackbox/security-and-trust/data-and-telemetry.md
new file mode 100644
index 0000000..19757d1
--- /dev/null
+++ b/src/content/docs/blackbox/security-and-trust/data-and-telemetry.md
@@ -0,0 +1,65 @@
+---
+title: "Data and Telemetry"
+description: "Explain what Blackbox reads, what it writes, and whether anything leaves the machine."
+sidebar_position: 2
+keywords: ["data handling", "telemetry", "privacy"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Data and Telemetry"
+ secondary_keywords: ["data handling", "telemetry"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Explain what Blackbox reads, what it writes, and whether anything leaves the machine.
+
+This page is about data flow. Users should understand which inputs Blackbox reads, which outputs it writes, and whether anything is transmitted beyond the local machine or CI environment.
+
+## Audience
+
+These pages explain what Blackbox executes, reads, writes, and requires from the local or CI environment.
+
+## Data Blackbox Reads
+
+1. Source files needed for the run.
+2. System-test configuration.
+3. Runtime evidence from the test process and container boundary.
+4. Existing artifacts when comparing or replaying coverage.
+
+## Data Blackbox Writes
+
+1. Coverage and propagation reports.
+2. Feature files and catalog artifacts.
+3. Debug logs and diagnostic outputs when requested.
+4. Exit status and CI-facing annotations.
+
+## Telemetry And Transmission
+
+Blackbox should make it clear whether anything leaves the machine, what is sent, and why. If telemetry exists, the docs need to state:
+
+1. What data is sent.
+2. Where it is sent.
+3. Whether it is optional.
+4. How to disable it, if that is supported.
+
+## Content Outline
+
+1. State what happens locally and in CI.
+2. List data read and written.
+3. Clarify secrets, credentials, network access, and telemetry.
+4. Give safe operating defaults.
+
+## Safe Operating Defaults
+
+1. Prefer local-only collection where possible.
+2. Keep telemetry off unless the feature depends on it.
+3. Do not place secrets in generated artifacts.
+4. Treat debug logs as potentially sensitive if they include payloads or tokens.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/security-and-trust/network-access-and-isolation.md b/src/content/docs/blackbox/security-and-trust/network-access-and-isolation.md
new file mode 100644
index 0000000..e3b6867
--- /dev/null
+++ b/src/content/docs/blackbox/security-and-trust/network-access-and-isolation.md
@@ -0,0 +1,55 @@
+---
+title: "Network Access and Isolation"
+description: "Explain what outbound network access Blackbox needs and how to isolate runs safely."
+sidebar_position: 2
+keywords: ["network access", "isolation", "blackbox security"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Network Access and Isolation"
+ secondary_keywords: ["network access", "isolation"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Explain what outbound network access Blackbox needs and how to isolate runs safely.
+
+This page should make the trust boundary concrete: what can talk to what, when the testbed needs the network, and how to keep a run hermetic when that matters.
+
+## Audience
+
+Teams deciding whether Blackbox can run inside their network or CI constraints.
+
+## Network Model
+
+1. The test runner talks to the SUT and any local dependencies it stands up.
+2. The SUT may talk to its own downstream services if the scenario requires it.
+3. Blackbox should document any external calls that happen during setup, execution, or artifact upload.
+4. Isolation should make it clear which parts of the run are hermetic and which are not.
+
+## Content Outline
+
+1. State the default network assumptions.
+2. Explain which parts of the run need outbound access, if any.
+3. Show how to isolate the testbed and containers.
+4. Note what changes for local development versus CI.
+
+## Safe Operating Defaults
+
+1. Prefer a testbed that does not depend on the public internet.
+2. Allow outbound access only when the scenario depends on it.
+3. Document any proxy, DNS, or firewall assumptions.
+4. Keep the isolation model the same in local development and CI when possible.
+
+## Evidence To Add
+
+- A network diagram showing runner, testbed, SUT, and external services.
+- A table of allowed outbound dependencies by mode.
+- Links to What Blackbox Runs, Data and Telemetry, and Secrets and Containers.
+
+## Figure Placeholder
+
+**Caption:** The network boundary for a Blackbox run.
+
+**Slot:** `<!-- TODO: insert network-isolation diagram or sandbox topology graphic here -->`
diff --git a/src/content/docs/blackbox/security-and-trust/secrets-and-containers.md b/src/content/docs/blackbox/security-and-trust/secrets-and-containers.md
new file mode 100644
index 0000000..2bbcebb
--- /dev/null
+++ b/src/content/docs/blackbox/security-and-trust/secrets-and-containers.md
@@ -0,0 +1,56 @@
+---
+title: "Secrets and Containers"
+description: "Explain credential handling, container environment risks, and safe local/CI usage."
+sidebar_position: 3
+keywords: ["secrets", "containers", "ci security"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Secrets and Containers"
+ secondary_keywords: ["secrets", "containers"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Explain credential handling, container environment risks, and safe local/CI usage.
+
+This page defines the risk boundary around secrets and containerized runs. The goal is to make it obvious what credentials are needed, where they live, and how containers affect isolation.
+
+## Audience
+
+These pages explain what Blackbox executes, reads, writes, and requires from the local or CI environment.
+
+## Secrets
+
+1. Use the narrowest credential scope that allows the test to run.
+2. Prefer injected secrets over committed values.
+3. Do not assume generated artifacts are secret-free.
+4. Make the handling of tokens and credentials explicit in the docs.
+
+## Containers
+
+1. Containers should define the system boundary for the run.
+2. The testbed should be clear about which containers are disposable and which are long-lived.
+3. Volume mounts, ports, and network aliases should be documented where they matter for safety.
+4. State whether the setup expects Docker, Docker Compose, or another topology.
+
+## Content Outline
+
+1. State what happens locally and in CI.
+2. List data read and written.
+3. Clarify secrets, credentials, network access, and telemetry.
+4. Give safe operating defaults.
+
+## Safe Operating Defaults
+
+1. Rotate or scope credentials used in test environments.
+2. Keep test containers separate from production secrets.
+3. Avoid broad host mounts unless the test requires them.
+4. Prefer disposable containers for reproducible runs.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/security-and-trust/what-blackbox-runs.md b/src/content/docs/blackbox/security-and-trust/what-blackbox-runs.md
new file mode 100644
index 0000000..8781499
--- /dev/null
+++ b/src/content/docs/blackbox/security-and-trust/what-blackbox-runs.md
@@ -0,0 +1,81 @@
+---
+title: "What Blackbox Runs"
+description: "Explain local commands, Playwright integration, container interaction, and generated artifacts."
+sidebar_position: 1
+keywords: ["security", "what blackbox runs", "local execution"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "what blackbox runs"
+ secondary_keywords: ["blackbox security", "test container instrumentation", "opentelemetry bootstrap"]
+ search_intent: "trust evaluation from developers who need to know what code executes in their repo and containers"
+ snippet_angle: "explain the local commands, generated compose overlays, bootstrap image, container mounts, and artifacts Blackbox uses"
+---
+
+## Abstract
+
+This page defines the execution boundary. Blackbox runs the commands you ask it to run, usually through Playwright or your chosen system-test entrypoint, and then observes the resulting system behavior.
+
+## Audience
+
+These pages explain what Blackbox executes, reads, writes, and requires from the local or CI environment.
+
+## What Runs
+
+During the default containerized testbed flow, Blackbox may run or generate these pieces:
+
+1. The system-test command you invoked, usually a Playwright command or project script.
+2. Your SUT containers and managed dependencies from Docker Compose or the testbed config.
+3. A generated Docker Compose overlay that adds instrumentation mounts, debug ports, and isolation wiring.
+4. A one-shot init container from the Blackbox OpenTelemetry bootstrap image.
+5. A mounted `node-wrap` script that shadows the SUT Node binary during the test run.
+6. A local debug HTTP endpoint inside each instrumented SUT process for span collection.
+7. Reporters and artifact sinks after the scenario finishes.
+
+The generated overlay is test infrastructure. Your compose file and service Dockerfiles are not rewritten on disk by the default flow.
+
+## What Is Mounted Into Containers
+
+The bootstrap image provides a `/blackbox-otel` directory with the Blackbox preload entrypoint, OpenTelemetry dependencies, a Node wrapper, and a real Node binary for the wrapper to execute.
+
+For each SUT container, the testbed overlay mounts:
+
+1. `/blackbox-otel:ro`, the bootstrap runtime tree.
+2. `bin/node-wrap` over the configured Node binary path, commonly `/usr/local/bin/node`.
+3. A debug port used by the runner to fetch spans for the active trace.
+
+The service still runs its normal command. The difference is that when that command invokes `node`, the wrapper adds the Blackbox preload before app code starts.
+
+## What Blackbox Does Not Run
+
+1. It does not replace your app server.
+2. It does not replace your test framework.
+3. It does not require production code to import OpenTelemetry.
+4. It does not require a second test-only Dockerfile in the default path.
+5. It does not send collected evidence to a hosted service by default.
+
+## What It Reads And Writes
+
+Blackbox reads testbed configuration, the runnable topology, scenarios, effect catalogs, and runtime spans exposed by the instrumented SUTs during the test run.
+
+Blackbox writes generated artifacts such as coverage reports, catalog summaries, OMC/DC reports, diagnostics, and CI annotations depending on the configured reporters and sinks. The default durable output is the local artifact directory, commonly `.blackbox-coverage/`.
+
+See [Files and Artifacts](/docs/blackbox/reference/files-and-artifacts) for the full inventory.
+
+## Trust Boundary
+
+Blackbox is deliberately intrusive inside the test container process: it preloads code before the app starts so it can observe boundaries without production changes. That is why it belongs in local and CI test environments, not in production runtime unless you explicitly choose to experiment there.
+
+The trust tradeoff is the point of the framework: in exchange for a controlled test-only preload, you get runtime evidence about what the system actually did.
+
+## Safe Operating Defaults
+
+1. Keep the testbed isolated from unrelated local services.
+2. Use the least amount of credential scope needed for the run.
+3. Treat generated artifacts as reviewable outputs, not as trusted inputs.
+4. Prefer explicit configuration over environment guesswork.
+
+## Figure Placeholder
+
+**Caption:** What Blackbox adds to the test environment: generated compose overlay, bootstrap volume, Node wrapper, debug spans, and local artifacts.
+
+**Slot:** `<!-- TODO: insert security/trust execution-boundary diagram here -->`
diff --git a/src/content/docs/blackbox/troubleshooting/catalog-failures.md b/src/content/docs/blackbox/troubleshooting/catalog-failures.md
new file mode 100644
index 0000000..dc4a55b
--- /dev/null
+++ b/src/content/docs/blackbox/troubleshooting/catalog-failures.md
@@ -0,0 +1,63 @@
+---
+title: "Catalog Failures"
+description: "Explain missing required effects, forbidden effects, and inline shapes that should be promoted."
+sidebar_position: 3
+keywords: ["catalog failures", "requires forbids", "effect assertion failure"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Catalog Failures"
+ secondary_keywords: ["catalog failures", "requires forbids"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Explain missing required effects, forbidden effects, and inline shapes that should be promoted.
+
+Catalog failures mean the run did not satisfy the effect contract the team wrote down. The system may have behaved differently, omitted a required boundary effect, or emitted something that should have been forbidden.
+
+## Audience
+
+These pages help users recover from common failures without opening an issue.
+
+## Common Causes
+
+1. A required effect did not happen.
+2. A forbidden effect appeared in the run.
+3. The catalog is too narrow for the real behavior.
+4. The catalog is too broad and should be split into smaller shapes.
+
+## First Checks
+
+1. Compare the observed run with the catalog entry.
+2. Decide whether the catalog or the implementation changed.
+3. Confirm whether the missing effect is truly required or just incidental.
+4. Check whether the effect belongs in an inline shape or a promoted catalog entry.
+
+## Recovery
+
+1. Update the catalog if the new behavior is intentional.
+2. Fix the implementation if the old effect is still required.
+3. Promote repeated inline shapes into named catalog entries when they become part of the workflow.
+4. Re-run the scenario to confirm the gate now matches the intended behavior.
+
+## Content Outline
+
+1. Identify the symptom.
+2. List likely causes in order.
+3. Provide diagnostic commands and artifact checks.
+4. Explain when to report a bug and what to include.
+
+## What To Report If It Still Fails
+
+1. The scenario or catalog entry name.
+2. The required or forbidden effect that failed.
+3. The observed output from the run.
+4. Any report or propagation artifact that explains the mismatch.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/troubleshooting/diagnostics-and-debug-logs.md b/src/content/docs/blackbox/troubleshooting/diagnostics-and-debug-logs.md
new file mode 100644
index 0000000..2d55216
--- /dev/null
+++ b/src/content/docs/blackbox/troubleshooting/diagnostics-and-debug-logs.md
@@ -0,0 +1,58 @@
+---
+title: "Diagnostics and Debug Logs"
+description: "Explain how to collect useful logs, debug failed runs, and decide whether the issue is setup, traces, catalog drift, or Blackbox."
+sidebar_position: 5
+keywords: ["blackbox diagnostics", "blackbox debug logs", "effect coverage troubleshooting"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Diagnostics and Debug Logs"
+ secondary_keywords: ["blackbox diagnostics", "blackbox debug logs"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Explain how to collect useful logs, debug failed runs, and decide whether the issue is setup, traces, catalog drift, or Blackbox.
+
+This page is the triage hub. It should show users which logs to look at first, what each failure class looks like, and how to reduce the run to something debuggable.
+
+## Audience
+
+Developers and CI owners investigating failed Blackbox runs.
+
+## Common Failure Classes
+
+1. Setup failures.
+2. No-span failures.
+3. Catalog or feature drift.
+4. Report generation failures.
+5. Integration or environment failures.
+
+## First Checks
+
+1. Re-run with verbose or debug output.
+2. Save the report, logs, and any generated artifacts from the failing run.
+3. Identify whether the failure is in setup, evidence collection, comparison, or rendering.
+4. Reduce the case to a minimal reproduction before filing a bug.
+
+## Content Outline
+
+1. Show the first diagnostic commands to run after a failure.
+2. Separate setup failures, no-span failures, catalog assertion failures, and report generation failures.
+3. Explain verbose or debug output, where logs live, and what files are safe to attach to bug reports.
+4. Describe how to reduce a failing run to a minimal reproduction.
+5. Link to reporting a bug when local diagnostics are not enough.
+
+## What To Keep
+
+1. The command that failed.
+2. The smallest relevant log excerpt.
+3. The artifact or report that proves the failure.
+4. The configuration that reproduces it.
+
+## Evidence To Add
+
+- Real debug command output.
+- A table of common symptoms and likely causes.
+- Redaction guidance for traces, URLs, headers, and secrets.
diff --git a/src/content/docs/blackbox/troubleshooting/docker-and-testbed.md b/src/content/docs/blackbox/troubleshooting/docker-and-testbed.md
new file mode 100644
index 0000000..7a350ff
--- /dev/null
+++ b/src/content/docs/blackbox/troubleshooting/docker-and-testbed.md
@@ -0,0 +1,82 @@
+---
+title: "Docker and Testbed"
+description: "Diagnose container startup, ports, waits, compose overlays, and local environment failures."
+sidebar_position: 4
+keywords: ["docker troubleshooting", "testbed errors", "compose testing"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "docker testbed troubleshooting"
+ secondary_keywords: ["docker troubleshooting", "testbed errors", "docker compose testing"]
+ search_intent: "troubleshooting intent from developers whose Blackbox container topology fails before evidence can be trusted"
+ snippet_angle: "diagnose compose startup, bootstrap image, init container, mounted node wrapper, ports, waits, and stale volumes"
+---
+
+## Abstract
+
+Diagnose container startup, ports, waits, compose overlays, and local environment failures.
+
+This page covers the failures that happen before the run can even be trusted: containers not starting, ports colliding, waits never resolving, or the local testbed not matching the scenario.
+
+## Audience
+
+These pages help users recover from common failures without opening an issue.
+
+## Common Causes
+
+1. The compose stack did not start cleanly.
+2. A port mapping collided with another local process.
+3. A wait condition never became true.
+4. The local environment and the testbed configuration diverged.
+5. The OpenTelemetry bootstrap image was not built or could not be pulled.
+6. The init container did not populate the bootstrap volume.
+7. The SUT image does not have a shell for the current `node-wrap` script.
+8. The configured Node binary path does not match the SUT image.
+
+## First Checks
+
+1. Confirm the containers are healthy before the test starts.
+2. Check for port collisions and stale containers.
+3. Verify the wait conditions and any startup dependencies.
+4. Compare the local configuration with the CI configuration if the failure only appears in one place.
+5. Confirm the bootstrap image exists locally or is reachable from CI.
+6. Confirm the generated overlay mounted `/blackbox-otel` and `bin/node-wrap` into the SUT.
+
+## Bootstrap Image Checks
+
+In local development, the bootstrap image is commonly tagged as `blackbox-otel-bootstrap:local`. In packaged or CI usage, the image may come from a registry or from `BLACKBOX_OTEL_IMAGE`.
+
+The image must contain:
+
+1. `/blackbox-otel/bootstrap.cjs`
+2. `/blackbox-otel/node_modules/`
+3. `/blackbox-otel/bin/node-wrap`
+4. `/blackbox-otel/bin/real-node`
+
+If the image is missing, malformed, or built for the wrong architecture, the SUT may start without instrumentation or fail before it becomes healthy.
+
+## Node Binary Path Checks
+
+The default instrumentation path shadows `/usr/local/bin/node`. That matches common official Node images, but it is still an assumption.
+
+If your image puts Node somewhere else, configure the testbed to shadow the correct path. If your image is distroless, the current shell wrapper is not enough because there is no `/bin/sh` to execute it.
+
+## Recovery
+
+1. Restart the testbed from a clean state.
+2. Remove stale containers or volumes if the setup expects a fresh run.
+3. Rebuild or repull the bootstrap image.
+4. Fix the compose overlay, Node binary path, or port mapping that caused the failure.
+5. Re-run the sample project before trying the full system again.
+
+## What To Report If It Still Fails
+
+1. The compose or testbed command.
+2. The failing container or port.
+3. The wait condition or startup step that timed out.
+4. Any logs that show why the testbed never reached a ready state.
+
+## Figure Placeholder
+
+**Caption:** The generated testbed overlay and the failures that can happen before the first span is captured: image, volume, wrapper, debug port, and wait strategy.
+
+**Slot:** `<!-- TODO: insert Docker/testbed troubleshooting screenshot or compose overlay diagram here -->`
diff --git a/src/content/docs/blackbox/troubleshooting/feature-drift.md b/src/content/docs/blackbox/troubleshooting/feature-drift.md
new file mode 100644
index 0000000..dd146b0
--- /dev/null
+++ b/src/content/docs/blackbox/troubleshooting/feature-drift.md
@@ -0,0 +1,63 @@
+---
+title: "Feature Drift"
+description: "Explain stale, missing, orphan, and unparseable feature files and how to recover."
+sidebar_position: 2
+keywords: ["feature drift", "stale feature files", "gherkin drift"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Feature Drift"
+ secondary_keywords: ["feature drift", "stale feature files"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Explain stale, missing, orphan, and unparseable feature files and how to recover.
+
+Feature drift means the generated or checked feature file no longer matches the run the team expects. The file may be stale, missing, orphaned, or impossible to parse cleanly.
+
+## Audience
+
+These pages help users recover from common failures without opening an issue.
+
+## Common Causes
+
+1. The system behavior changed but the feature file was not regenerated.
+2. The generator produced a file for a run the repo no longer recognizes.
+3. A rename or refactor broke the link between scenario and artifact.
+4. The file format changed enough that the parser or checker no longer accepts it.
+
+## First Checks
+
+1. Compare the generated file with the current scenario or behavior.
+2. Check whether the source of truth is the latest runtime evidence.
+3. Confirm the file name and path match the current page or scenario slug.
+4. Inspect whether the artifact is stale, orphaned, or malformed.
+
+## Recovery
+
+1. Regenerate the feature file from the current run.
+2. Update the catalog or scenario naming if the behavior is intentionally new.
+3. Delete or quarantine orphaned files that no longer correspond to live scenarios.
+4. If the file is unparseable, reduce it to the smallest reproducible example.
+
+## Content Outline
+
+1. Identify the symptom.
+2. List likely causes in order.
+3. Provide diagnostic commands and artifact checks.
+4. Explain when to report a bug and what to include.
+
+## What To Report If It Still Fails
+
+1. The feature file path and scenario name.
+2. The run that produced it.
+3. The expected versus actual behavior.
+4. Any parser or checker error text.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/troubleshooting/no-spans-captured.md b/src/content/docs/blackbox/troubleshooting/no-spans-captured.md
new file mode 100644
index 0000000..1ccd8de
--- /dev/null
+++ b/src/content/docs/blackbox/troubleshooting/no-spans-captured.md
@@ -0,0 +1,77 @@
+---
+title: "No Spans Captured"
+description: "Diagnose uninstrumented systems, missing trace propagation, and empty reports."
+sidebar_position: 1
+keywords: ["no spans captured", "opentelemetry troubleshooting", "empty reports"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "no spans captured"
+ secondary_keywords: ["opentelemetry troubleshooting", "blackbox empty report", "node options require"]
+ search_intent: "troubleshooting intent from users whose system test ran but produced empty Blackbox evidence"
+ snippet_angle: "walk through topology, bootstrap, node wrapper, trace propagation, and artifact checks for empty span reports"
+---
+
+## Abstract
+
+Diagnose uninstrumented systems, missing trace propagation, and empty reports.
+
+If the report is empty, the run may still have happened, but Blackbox did not see the runtime evidence it needed. This page helps you separate "the system did nothing" from "the instrumentation path was missing."
+
+## Audience
+
+These pages help users recover from common failures without opening an issue.
+
+## Common Causes
+
+1. The test hit a code path that never crossed an instrumented boundary.
+2. The bootstrap image was not available to the testbed.
+3. The generated compose overlay did not mount `/blackbox-otel` into the SUT container.
+4. The service did not start through the Node binary path Blackbox shadowed.
+5. `NODE_OPTIONS` was explicitly set empty for the app process, bypassing the wrapper behavior.
+6. Another tracing agent registered first and blocked the Blackbox tracer.
+7. Trace propagation broke before the request reached the service that should emit spans.
+8. The scenario ended before evidence was collected or flushed.
+
+## First Checks
+
+1. Confirm the test actually exercised the boundary you expected.
+2. Confirm the testbed built or pulled the bootstrap image.
+3. Confirm the SUT container has `/blackbox-otel/bootstrap.cjs` and `/blackbox-otel/bin/node-wrap` mounted.
+4. Confirm the service command invokes the Node binary path Blackbox is configured to shadow.
+5. Inspect the debug output or report for trace IDs and span counts.
+6. Compare the empty run with a known-good sample if you have one.
+
+## Wrapper-Specific Checks
+
+The wrapper has one intentional bypass: if `NODE_OPTIONS` is set and its value is empty, it executes the real Node binary without the Blackbox preload. This allows healthchecks such as `NODE_OPTIONS= node -e "..."` to avoid starting a second debug server inside the same container.
+
+That bypass should be used for healthchecks, not for the app process itself. If the main service command or compose environment sets `NODE_OPTIONS` to an explicit empty value, Blackbox will not load.
+
+If your service already uses `NODE_OPTIONS`, Blackbox should preserve it. The wrapper prepends `--require=/blackbox-otel/bootstrap.cjs` to the resolved value rather than replacing it in the compose file.
+
+## Existing Tracing Agents
+
+Production-shaped images sometimes include `dd-trace/init`, Sentry tracing, or another OpenTelemetry provider. In a test environment, those agents can compete with Blackbox for the process tracer.
+
+If spans are empty or startup fails with a tracer-provider error, disable the production tracer for the test topology. Common examples are setting `DD_TRACE_ENABLED=false` or clearing `SENTRY_DSN` in the test compose override.
+
+## Recovery
+
+1. Re-run with debug logging enabled.
+2. Reduce the scenario to the smallest boundary that should emit spans.
+3. Verify the container or testbed config that carries the bootstrap and trace propagation.
+4. Temporarily disable competing tracing agents in the test environment.
+5. If the path is still empty, compare against the showcase system before filing a bug.
+
+## What To Report If It Still Fails
+
+1. The command you ran.
+2. The expected boundary.
+3. The actual output or log excerpt.
+4. The config that controls instrumentation or tracing.
+
+## Figure Placeholder
+
+**Caption:** The empty-report failure mode: request reaches the service, but the bootstrap, wrapper, trace propagation, or debug span collection path is broken.
+
+**Slot:** `<!-- TODO: insert troubleshooting screenshot or debug-log walkthrough here -->`
diff --git a/src/content/docs/blackbox/troubleshooting/reporting-a-bug.md b/src/content/docs/blackbox/troubleshooting/reporting-a-bug.md
new file mode 100644
index 0000000..59ea91f
--- /dev/null
+++ b/src/content/docs/blackbox/troubleshooting/reporting-a-bug.md
@@ -0,0 +1,61 @@
+---
+title: "Reporting a Bug"
+description: "List the command output, config, environment, artifacts, and reproduction details maintainers need."
+sidebar_position: 5
+keywords: ["report bug", "debug blackbox", "issue template"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Reporting a Bug"
+ secondary_keywords: ["report bug", "debug blackbox"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+List the command output, config, environment, artifacts, and reproduction details maintainers need.
+
+This page explains the minimum useful bug report. If maintainers cannot reproduce the issue or understand the run context, the report is not complete enough yet.
+
+## Audience
+
+These pages help users recover from common failures without opening an issue.
+
+## What A Useful Bug Report Includes
+
+1. The command or scenario that failed.
+2. The expected result and the actual result.
+3. The environment and configuration used.
+4. The relevant artifacts, logs, and screenshots.
+5. The exact steps needed to reproduce the issue.
+
+## What To Redact
+
+1. Secrets or tokens.
+2. Private URLs if they are not required to understand the issue.
+3. Sensitive customer data.
+4. Anything else that is not needed to reproduce the failure.
+
+## When To Report
+
+Report the issue after you have reduced it as far as you reasonably can and confirmed it is not just a setup mismatch or a missing local prerequisite.
+
+## Content Outline
+
+1. Identify the symptom.
+2. List likely causes in order.
+3. Provide diagnostic commands and artifact checks.
+4. Explain when to report a bug and what to include.
+
+## What Maintainers Need First
+
+1. The failure mode.
+2. The config and version details.
+3. The artifact or log that shows the issue.
+4. A reproducible path if you have one.
+
+## Evidence To Add
+
+- Real commands, APIs, or artifacts from the Blackbox showcase system.
+- Links to related concept, guide, reference, or troubleshooting pages.
+- Clear limits and prerequisites where the page touches alpha behavior.
diff --git a/src/content/docs/blackbox/use-cases/ai-assisted-development.md b/src/content/docs/blackbox/use-cases/ai-assisted-development.md
new file mode 100644
index 0000000..a775788
--- /dev/null
+++ b/src/content/docs/blackbox/use-cases/ai-assisted-development.md
@@ -0,0 +1,68 @@
+---
+title: "AI-Assisted Development"
+description: "Explain why agent-authored code needs an external behavioral gate without making AI the default path."
+sidebar_position: 5
+keywords: ["agentic coding", "ai output verification", "llm output verification", "verification debt", "behavioral verification"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "agentic coding"
+ secondary_keywords: ["ai output verification", "llm output verification", "agent output verification", "verification debt"]
+ search_intent: "teams adopting AI coding agents and looking for ways to verify their output before merge"
+ snippet_angle: "agentic coding needs runtime behavior verification because plausible code is not the same as proven behavior"
+---
+
+## Abstract
+
+Explain why agent-authored code needs an external behavioral gate without making AI the default path.
+
+Blackbox is useful here because the agent can change code quickly, but the runtime proof still has to come from the real system.
+
+## Audience
+
+Teams using coding agents, copilots, or other assistive loops that still need human review and runtime proof.
+
+## The Problem
+
+Agent-authored changes can look complete before they are actually correct. Tests may pass, but the boundary behavior can still be wrong, missing, or under-asserted.
+
+That creates verification debt: the gap between generated output and proven runtime behavior. AI output verification, LLM output verification, and agent output verification all need an external signal that is not just the model's explanation of its own work.
+
+## When It Helps
+
+1. The agent is making a reviewable change in a real system.
+2. The team wants runtime evidence before merge.
+3. The implementation needs a checker outside the model's prose.
+4. The workflow should stay human-owned even when the code is agent-assisted.
+
+## What Blackbox Adds
+
+1. Observable effects from a real run.
+2. A report the human reviewer can inspect.
+3. A gate that checks behavior, not just an explanation.
+4. A way to stop an agent from declaring success too early.
+
+This is AI behavioral testing in the narrow Blackbox sense: the test does not judge the model. It judges whether the system behavior produced by an agent-assisted change matches required and forbidden runtime effects.
+
+## What Not To Claim
+
+1. Blackbox is not the AI coding tool.
+2. Blackbox does not make an agent correct by itself.
+3. Blackbox does not replace human review or product intent.
+
+## What Success Looks Like
+
+1. The agent finishes a change.
+2. Blackbox verifies the observed behavior against the expected one.
+3. The reviewer can see the proof instead of trusting the prose.
+4. The team keeps the final decision human-owned.
+
+## Evidence To Add
+
+- A small agent-assisted run that produces a report and a reviewer decision.
+- Links to AI-Assisted Workflow and The Blackbox Lifecycle.
+
+## Figure Placeholder
+
+**Caption:** An agent-assisted change being checked by runtime evidence before it is trusted.
+
+**Slot:** `<!-- TODO: insert agent loop screenshot or animated reviewer handoff here -->`
diff --git a/src/content/docs/blackbox/use-cases/covering-before-refactor.md b/src/content/docs/blackbox/use-cases/covering-before-refactor.md
new file mode 100644
index 0000000..8ae64c9
--- /dev/null
+++ b/src/content/docs/blackbox/use-cases/covering-before-refactor.md
@@ -0,0 +1,87 @@
+---
+title: "Covering Before Refactor"
+description: "Use characterization testing and Blackbox runtime evidence to capture behavior before changing internals."
+sidebar_position: 1
+keywords: ["characterization testing", "golden master testing", "refactor safety", "cover before refactor"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "characterization testing"
+ secondary_keywords: ["golden master testing", "refactor safety", "cover before refactor"]
+ search_intent: "legacy and refactor safety intent from teams capturing current behavior before changing internals"
+ snippet_angle: "capture current system behavior before a refactor, then compare runtime effects after the change"
+---
+
+## Abstract
+
+Covering before refactor means capturing current behavior before changing the implementation. This is the classic characterization testing move: when the system is valuable but hard to reason about, first document what it does.
+
+Blackbox applies that idea to system behavior. It records runtime effects before the refactor, then lets the team compare what changed after the implementation moves.
+
+## Audience
+
+Teams about to rewrite, extract, modularize, upgrade, or clean up a system that already has user value and should not accidentally change behavior.
+
+## Why Refactors Need Behavior Proof
+
+Refactors often begin with a risky assumption: if the existing tests are green, behavior is safe. That can be true for local logic and still false for system behavior.
+
+A refactor can keep unit tests green while changing:
+
+1. A downstream HTTP call.
+2. An emitted event.
+3. A database write.
+4. A queue message.
+5. A cache invalidation.
+6. A forbidden side effect that should never happen.
+
+When those effects matter, line coverage and passing tests are not enough. The team needs a behavior baseline.
+
+## Characterization Testing And Golden Masters
+
+Characterization testing captures what a system currently does so future changes can be compared against it. Golden master testing often captures a larger output snapshot and treats it as a baseline.
+
+Blackbox uses the same instinct but produces more reviewable artifacts:
+
+1. Runtime evidence from a real system run.
+2. Effects derived from that evidence.
+3. Feature files that summarize behavior in readable form.
+4. Catalogs and reports that mark required, forbidden, missing, and newly observed effects.
+
+That makes the baseline easier to review than a raw snapshot alone.
+
+## Refactor Workflow
+
+A practical workflow is:
+
+1. Pick one high-risk behavior before changing internals.
+2. Run a system test that exercises the behavior.
+3. Capture the Blackbox artifacts as the baseline.
+4. Perform the refactor.
+5. Run the same scenario again.
+6. Review the effect drift.
+7. Accept intentional behavior changes and reject accidental ones.
+
+This gives reviewers a concrete artifact instead of only a diff and a green test suite.
+
+## What Counts As Success
+
+A good refactor run does not prove that the new design is better. It proves that selected externally visible behavior stayed stable or changed intentionally.
+
+Success looks like:
+
+1. Required effects still appear.
+2. Forbidden effects still stay absent.
+3. Newly observed effects are reviewed.
+4. Missing effects are investigated before merge.
+5. The final artifact explains why behavior is still acceptable.
+
+## What Not To Claim
+
+Blackbox does not make refactors risk-free. It does not replace unit tests for local logic, and it does not prove that every behavior in the system was covered. It gives the team stronger evidence for the workflows it actually exercised.
+
+## What To Read Next
+
+1. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
+2. [System Effects](/docs/blackbox/concepts/system-effects)
+3. [The Blackbox Lifecycle](/docs/blackbox/lifecycle/the-blackbox-lifecycle)
+4. [Feature Drift](/docs/blackbox/troubleshooting/feature-drift)
diff --git a/src/content/docs/blackbox/use-cases/incident-regression.md b/src/content/docs/blackbox/use-cases/incident-regression.md
new file mode 100644
index 0000000..508375b
--- /dev/null
+++ b/src/content/docs/blackbox/use-cases/incident-regression.md
@@ -0,0 +1,62 @@
+---
+title: "Incident Regression"
+description: "Turn an incident into a durable catalog entry and behavioral gate."
+sidebar_position: 4
+keywords: ["incident regression", "semantic regression", "postmortem testing", "forbidden effects"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Incident Regression"
+ secondary_keywords: ["semantic regression", "incident regression", "postmortem testing"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Turn an incident into a durable catalog entry and behavioral gate.
+
+The point is not root-cause analysis. The point is to make the failure visible again if the behavior comes back.
+
+## Audience
+
+Teams that want a known incident to become a recurring behavioral check.
+
+## The Problem
+
+An incident often exposes a missing assertion, a silent boundary change, or a behavior the team never encoded explicitly.
+
+## When It Helps
+
+1. The failure mode is known and repeatable enough to gate.
+2. The team wants to prevent regression, not just discuss the postmortem.
+3. The runtime effect is observable in a real run.
+4. The check should fail before trust is granted.
+
+## What Blackbox Adds
+
+1. The failing effect becomes a catalog entry.
+2. The scenario becomes a regression gate.
+3. The report shows whether the behavior is back or still fixed.
+
+## What Not To Claim
+
+1. Blackbox does not do incident management.
+2. Blackbox does not replace observability, alerting, or root-cause analysis.
+3. Blackbox does not prevent every future incident.
+
+## Semantic Regression
+
+An incident regression is often a semantic regression: the system still runs, but the meaning of the behavior changed. A response may still be successful while the wrong effect was emitted, skipped, duplicated, or no longer forbidden.
+
+Blackbox is useful when the postmortem can name the runtime effect that should become a permanent gate.
+
+## Evidence To Add
+
+- A concrete post-incident regression example.
+- Links to Requires and Forbids, The Blackbox Lifecycle, and Feature Files and Staleness.
+
+## Figure Placeholder
+
+**Caption:** An incident becoming a recurring regression gate.
+
+**Slot:** `<!-- TODO: insert incident-to-gate before/after demo here -->`
diff --git a/src/content/docs/blackbox/use-cases/legacy-modernization.md b/src/content/docs/blackbox/use-cases/legacy-modernization.md
new file mode 100644
index 0000000..69bbeef
--- /dev/null
+++ b/src/content/docs/blackbox/use-cases/legacy-modernization.md
@@ -0,0 +1,63 @@
+---
+title: "Legacy Modernization"
+description: "Show how Blackbox creates the first honest behavior map for an older system."
+sidebar_position: 2
+keywords: ["legacy modernization", "legacy refactor", "brownfield testing"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "Legacy Modernization"
+ secondary_keywords: ["legacy modernization", "legacy refactor"]
+ search_intent: "TODO"
+ snippet_angle: "TODO"
+---
+
+## Abstract
+
+Show how Blackbox creates the first honest behavior map for an older system.
+
+Legacy systems often still make money or keep operations alive, but they are hard to change because the team does not fully trust the behavior boundary anymore. Blackbox makes that boundary visible again.
+
+## Audience
+
+Teams modernizing a brownfield system without rewriting it all at once.
+
+This includes old services, mixed stacks, and systems where the source of truth is partly in code and partly in tribal knowledge.
+
+## The Problem
+
+Legacy systems accumulate invisible behavior. Some behavior is only known because "the old code has always done it that way." That is a weak contract when the team needs to replace pieces, move infrastructure, or decompose a monolith.
+
+You need a map of what the system actually does, not just what the code seems to imply.
+
+## When It Helps
+
+1. The system is important enough that behavior changes are costly.
+2. The team wants to modernize in stages.
+3. The existing tests are incomplete or hard to trust.
+4. The boundary behavior needs to be observed before a migration step.
+
+## What Blackbox Adds
+
+1. A behavioral baseline for the legacy system.
+2. A way to compare the old path and the new path.
+3. A review artifact that can survive incremental modernization.
+4. A practical gate for migration steps and regression checks.
+
+## What Not To Claim
+
+1. Blackbox does not rewrite the legacy system.
+2. Blackbox does not eliminate the need to understand the domain.
+3. Blackbox does not turn a brittle system into a clean one by itself.
+
+## Content Outline
+
+1. Describe the modernization situation.
+2. Show the legacy behavior map.
+3. Show how the map supports incremental change.
+4. Describe the review or CI outcome.
+
+## Evidence To Add
+
+- A legacy-system example that produces a baseline report.
+- A comparison between the old path and a migrated path.
+- Links to Runtime Evidence, Feature Files and Staleness, and The Blackbox Lifecycle.
diff --git a/src/content/docs/blackbox/use-cases/microservices-regression.md b/src/content/docs/blackbox/use-cases/microservices-regression.md
new file mode 100644
index 0000000..680b250
--- /dev/null
+++ b/src/content/docs/blackbox/use-cases/microservices-regression.md
@@ -0,0 +1,102 @@
+---
+title: "Microservices Regression"
+description: "Use Blackbox for microservices testing when behavior crosses HTTP, queues, caches, databases, and downstream service boundaries."
+sidebar_position: 3
+keywords: ["microservices testing", "service testing", "distributed systems testing", "microservices regression testing"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "microservices testing"
+ secondary_keywords: ["service testing", "distributed systems testing", "microservices regression testing"]
+ search_intent: "commercial and educational intent from teams trying to test cross-service behavior safely"
+ snippet_angle: "microservices testing needs evidence across service boundaries, not only a passing response from one service"
+---
+
+## Abstract
+
+Microservices testing is hard because the failure often appears outside the service that changed. One service may still return a valid response while the wrong event is published, a downstream call is skipped, a cache is stale, or a database effect changed.
+
+Blackbox helps when the regression matters at the boundary. It observes a real run and turns cross-service behavior into effects that can be reviewed and gated.
+
+## Audience
+
+Teams running distributed backends, service meshes, event-driven systems, or service-oriented applications where a change can ripple through HTTP calls, queues, caches, and databases.
+
+## Why Microservices Regressions Hide
+
+Microservice regressions often survive ordinary tests because each local check sees only part of the behavior.
+
+A service-level test may prove that one endpoint returned 200. It may not prove that the endpoint also published the right event, updated the right read model, avoided a forbidden downstream call, or preserved an async workflow several steps later.
+
+That is the gap Blackbox targets: behavior that is visible only when the system runs across boundaries.
+
+## What Blackbox Observes
+
+A useful microservices run may include effects such as:
+
+1. HTTP calls between services.
+2. Queue messages and event publications.
+3. Database writes or read-model updates.
+4. Cache changes.
+5. Calls to local stubs, sandboxes, or controlled downstream services.
+6. Forbidden effects that should not happen after a change.
+
+Blackbox does not replace distributed tracing. It uses runtime evidence to create a behavior-facing review layer: what was required, what was observed, what was missing, and what changed.
+
+## Where It Fits
+
+Use Blackbox for microservices regression when:
+
+1. A change touches a service boundary.
+2. A previous incident involved a missing event, wrong downstream call, or unexpected side effect.
+3. The team needs proof before extracting, splitting, merging, or rewriting a service.
+4. Existing tests pass but reviewers still cannot see whether the cross-service behavior stayed stable.
+
+The best first target is one workflow with one critical boundary effect. Do not start by trying to catalog the entire distributed system.
+
+## Example Shape
+
+A service change might look locally safe:
+
+1. The API still accepts the request.
+2. The unit tests still pass.
+3. The endpoint still returns the expected response.
+
+But the behavior can still drift:
+
+1. The order-created event no longer includes a required field.
+2. The billing service is not called.
+3. A retry path emits two messages instead of one.
+4. A cache invalidation was removed during refactor.
+
+Blackbox turns those changes into reviewable effects instead of leaving them hidden in traces and logs.
+
+## Concrete Example: Subscription Flow
+
+The Blackbox showcase uses a subscription workflow because it has the shape of a real microservices regression risk.
+
+One request to `POST /subscriptions` can involve:
+
+1. A BFF HTTP endpoint.
+2. Redis cache reads and writes.
+3. Postgres reads and inserts.
+4. A Stripe-like payment API call.
+5. A fraud-check service call.
+6. An order-service call.
+7. An SQS message.
+
+A normal assertion might stop at "the response is `201` and the tier is `pro`." Blackbox lets the test also ask whether the expected boundary effects happened and whether forbidden effects stayed absent.
+
+For `subscribe-flow`, the effect contract requires the payment intent, subscription insert, cache update, order call, and SQS message. It forbids refunds, deletes, truncates, and Redis destructive operations. That is the regression story: if a refactor keeps the response green but drops the queue message or adds a refund call, the behavior contract can catch it.
+
+## What Not To Claim
+
+Blackbox does not make distributed systems simple. It does not solve every eventual-consistency problem, network failure, or orchestration bug. It also does not replace observability, alerting, or contract tests.
+
+Its job is narrower: prove selected runtime behavior for selected workflows, then make drift visible before merge or release.
+
+## What To Read Next
+
+1. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
+2. [System Effects](/docs/blackbox/concepts/system-effects)
+3. [OMC/DC Coverage](/docs/blackbox/concepts/omc-dc-coverage)
+4. [Report Formats](/docs/blackbox/reference/report-formats)
diff --git a/src/content/docs/blackbox/use-cases/spec-driven-development.md b/src/content/docs/blackbox/use-cases/spec-driven-development.md
new file mode 100644
index 0000000..79d915d
--- /dev/null
+++ b/src/content/docs/blackbox/use-cases/spec-driven-development.md
@@ -0,0 +1,145 @@
+---
+title: "Spec-Driven Development"
+description: "Explain why spec-driven development needs a runtime verification gate, and how Blackbox adds proof after implementation."
+sidebar_position: 6
+keywords: ["spec driven development", "spec driven development tools", "github spec kit", "sdd verification"]
+toc_min_heading_level: 2
+seo:
+ primary_keyword: "spec driven development"
+ secondary_keywords: ["spec driven development tools", "github spec kit", "sdd verification"]
+ search_intent: "educational and tool-comparison intent from teams adopting SDD or Spec Kit-style workflows"
+ snippet_angle: "spec-driven development defines intent, but Blackbox verifies the implemented system with runtime evidence"
+---
+
+## Abstract
+
+Spec-driven development helps teams write intent before code. It turns product decisions into specs, plans, tasks, and implementation work. That improves the front half of development, especially when humans and AI coding agents share the same written context.
+
+Blackbox belongs in the verification half. It does not replace the spec, the plan, or the task list. It runs after implementation, observes the system at runtime, and turns the observed effects into proof a reviewer or CI gate can inspect.
+
+## Audience
+
+Teams using Spec Kit-style workflows, internal RFC/spec processes, AI coding agents, or task-driven implementation loops where "done" needs more than an accepted diff.
+
+## What Is Spec-Driven Development?
+
+Spec-driven development is a workflow where the team writes an explicit behavioral or product spec before implementation. The spec becomes the source for clarification, planning, task breakdown, implementation, and review.
+
+That is valuable because it gives humans and agents a shared intent artifact. The failure mode is that the spec can still drift from the system. A checked task does not prove behavior. A generated implementation does not prove behavior. A green low-level test suite does not prove the system produced the right external effects.
+
+## The Verification Gap
+
+Most SDD workflows are strong at organizing intent and weak at proving runtime behavior. They answer questions like:
+
+1. What did we mean to build?
+2. What tasks should implement it?
+3. Which files probably need to change?
+4. Did the implementation satisfy the written checklist?
+
+Blackbox adds a different question:
+
+> When the implemented system actually ran, which externally visible effects were observed, missing, forbidden, or newly introduced?
+
+That question matters because the system boundary is where many regressions appear: database writes, queues, HTTP calls, emitted events, emails, side effects, and downstream service behavior.
+
+## Where Blackbox Fits
+
+A spec-driven workflow can use Blackbox as a runtime verification gate:
+
+1. A spec captures intended behavior.
+2. A human or agent implements the change.
+3. A system or E2E test exercises the behavior.
+4. Blackbox collects runtime evidence from the run.
+5. Blackbox maps evidence into effects, catalogs, feature files, and coverage reports.
+6. Reviewers or CI decide whether the observed behavior matches the intended behavior.
+
+This makes Blackbox a companion to SDD tools, not another spec generator.
+
+## Planning Specs And Runtime-Backed Feature Files
+
+In a spec-driven workflow, the written spec and the Blackbox feature file do different jobs. A Spec Kit-style spec explains intended behavior, decisions, constraints, and implementation work. A Blackbox feature file is a runtime-backed behavior spec: it summarizes what the system actually did when a scenario ran.
+
+They should live side by side. The planning spec guides implementation. The Blackbox feature file helps verify that the implemented system produced the expected effects.
+
+That distinction is important because Blackbox is not trying to become the product spec, task plan, or design doc. It adds the missing verification step after the implementation exists:
+
+1. Runtime evidence is collected from a system or E2E run.
+2. Effects are derived from that evidence.
+3. Feature files, catalogs, and reports make the observed behavior reviewable.
+4. CI or human review decides whether the observed behavior satisfies the intended spec.
+
+## Spec Tools Vs Blackbox
+
+| Artifact | Job |
+| --- | --- |
+| Product or Spec Kit-style spec | Defines intended behavior, constraints, decisions, and implementation context |
+| Plan and task list | Organizes the implementation work |
+| System or E2E test | Exercises the implemented system |
+| Blackbox feature file | Captures runtime-backed behavior in readable form |
+| Effect catalog and report | Verify required, forbidden, missing, and newly observed effects |
+| CI or review gate | Blocks drift before merge or release |
+
+Blackbox should not claim to prove a written spec automatically. The alpha value is narrower and stronger: given a real run, it makes the observed behavior reviewable.
+
+## Why This Matters In The AI Era
+
+AI coding agents make SDD more attractive because agents need explicit instructions. They also make verification more important because agents can produce plausible implementations quickly. The bottleneck moves from "can we generate code" to "can we trust the behavior."
+
+A useful agent loop needs an external stop condition. Blackbox can provide one:
+
+1. Implement the task.
+2. Run the system test.
+3. Compare observed effects against required and forbidden behavior.
+4. Fix drift.
+5. Stop only when the runtime evidence supports the claim.
+
+That keeps the agent from being both the author and the only judge of success.
+
+## External Signals
+
+The Spec Kit ecosystem already shows demand for a verification phase:
+
+1. [github/spec-kit#1745](https://github.com/github/spec-kit/issues/1745) asks for a verification command after implementation.
+2. [github/spec-kit#1862](https://github.com/github/spec-kit/issues/1862) asks for a structured verification spec so agents can run implement, verify, and fix loops.
+3. [github/spec-kit#2967](https://github.com/github/spec-kit/issues/2967) proposes a lifecycle extension with sync verification and release readiness gates.
+4. [github/spec-kit#2977](https://github.com/github/spec-kit/issues/2977) proposes bounded maker/checker loops, external state, and human signoff.
+
+These issues are research signals, not shipped Blackbox integrations. The point is that SDD is standardizing intent faster than the industry is standardizing proof.
+
+## What Success Looks Like
+
+A good SDD plus Blackbox workflow has three properties:
+
+1. The planning spec still explains the intended behavior.
+2. The system test exercises the implemented behavior.
+3. The Blackbox feature file summarizes the runtime-backed behavior in a readable form.
+4. The effect catalog and report show what runtime effects were observed, required, missing, or forbidden.
+
+The gate is not "a spec exists." The gate is "the running system produced the behavior the team intended."
+
+## FAQ
+
+### Does Blackbox replace Spec Kit or SDD tools?
+
+No. SDD tools organize intent and implementation work. Blackbox verifies observed behavior after the system runs.
+
+### Does Blackbox read a spec and prove it automatically?
+
+No. Blackbox works from runtime evidence. A direct integration with a specific SDD tool would be a separate integration layer.
+
+### Why not just trust the generated tests?
+
+Generated tests can still miss boundary behavior. Blackbox checks the effects that appeared when the system actually ran.
+
+## What To Read Next
+
+1. [Runtime Evidence](/docs/blackbox/concepts/system-tests-and-runtime-evidence)
+2. [Feature Files and Staleness](/docs/blackbox/concepts/feature-files-and-staleness)
+3. [The Blackbox Lifecycle](/docs/blackbox/lifecycle/the-blackbox-lifecycle)
+4. [Configure CI Gates](/docs/blackbox/guides/ci-behavioral-gates)
+
+## Figure Placeholder
+
+**Caption:** SDD intent flowing into implementation, then Blackbox runtime proof before merge.
+
+**Slot:** `<!-- TODO: insert SDD-to-proof workflow diagram or screenshot here -->`
diff --git a/docs/changelog.md b/src/content/docs/changelog.md
similarity index 99%
rename from docs/changelog.md
rename to src/content/docs/changelog.md
index 959169e..8cf8341 100644
--- a/docs/changelog.md
+++ b/src/content/docs/changelog.md
@@ -4,8 +4,6 @@ title: Changelog
description: Version history and release notes for Suites
---
-# Changelog
-
All notable changes to Suites are documented here. For the complete version history, visit our [GitHub Releases](https://github.com/suites-dev/suites/releases).
---
diff --git a/docs/get-started/index.md b/src/content/docs/get-started/index.mdx
similarity index 93%
rename from docs/get-started/index.md
rename to src/content/docs/get-started/index.mdx
index 7142743..c20efcd 100644
--- a/docs/get-started/index.md
+++ b/src/content/docs/get-started/index.mdx
@@ -4,7 +4,8 @@ title: Get Started
description: Everything you need to start using Suites in minutes
---
-# Get Started
+import Aside from '@/components/mdx/Aside.astro';
+
Learn how to install Suites, configure the testing environment, and write the first automated test suite.
<div class="in-this-section">
@@ -22,11 +23,11 @@ The following requirements must be met:
- **Framework** - NestJS, InversifyJS, or plain TypeScript classes with constructor injection
- **Testing library** - Jest, Vitest, or Sinon
-:::tip Framework Flexibility
+<Aside type="tip" title="Framework Flexibility">
Suites supports the IoC principle through multiple implementations.
Currently: dependency injection frameworks (NestJS, InversifyJS) via TestBed, or any TypeScript code via `mock()`/`stub()`.
-:::
+</Aside>
## Recommended Path
@@ -41,4 +42,3 @@ For those new to Suites:
## Resources
- **[Suites Examples Repository](https://github.com/suites-dev/examples)** - Complete working examples for all testing patterns
-
diff --git a/docs/get-started/installation.mdx b/src/content/docs/get-started/installation.mdx
similarity index 95%
rename from docs/get-started/installation.mdx
rename to src/content/docs/get-started/installation.mdx
index 1b8d0b3..ac7d3ce 100644
--- a/docs/get-started/installation.mdx
+++ b/src/content/docs/get-started/installation.mdx
@@ -5,8 +5,9 @@ description: "Step-by-step installation of Suites for NestJS or Inversify with J
keywords: [install suites, nestjs unit testing setup, inversify testing, vitest nestjs, jest nestjs setup, emitDecoratorMetadata nestjs, nestjs tsconfig, experimentalDecorators]
---
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+import Aside from '@/components/mdx/Aside.astro';
+import Tabs from '@/components/mdx/Tabs.astro';
+import TabItem from '@/components/mdx/TabItem.astro';
# Installation
@@ -76,10 +77,10 @@ This installs three packages:
**Suites will automatically detect the installed adapters and configure itself accordingly.**
-:::info Why reflect-metadata?
+<Aside type="info" title="Why reflect-metadata?">
`reflect-metadata` is required as a runtime dependency (not dev dependency) because TypeScript's decorator metadata is only emitted at compile time.
Learn more in the [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/decorators.html#metadata).
-:::
+</Aside>
## Supported Libraries (Adapters)
@@ -110,9 +111,9 @@ This configuration is necessary for Suites to reflect class dependencies and con
}
```
-:::note NodeNext / ESM projects
+<Aside type="note" title="NodeNext / ESM projects">
As of `3.1.0`, projects configured with `moduleResolution: NodeNext` or `"type": "module"` work with Suites out of the box. No additional configuration is required beyond the standard setup shown above.
-:::
+</Aside>
## Type Reference Configuration
@@ -160,10 +161,10 @@ Suites will automatically detect the adapter and configure itself accordingly.
Install the corresponding adapter in each workspace separately. Configure the package manager's hoisting settings
to enable Suites to detect the adapter in each workspace.
-:::note
+<Aside type="note">
Some package managers may have limitations with dependency hoisting that can affect using different DI or mocking libraries
across workspaces. Refer to the package manager's documentation for specific guidance on dependency hoisting.
-:::
+</Aside>
## For Vitest Users
@@ -196,13 +197,13 @@ export default defineConfig({
});
```
-:::note Vitest 4.x
+<Aside type="note" title="Vitest 4.x">
Vitest 4.x uses Oxc by default instead of esbuild. The `esbuild: false` option is a no-op in Vitest 4.x and produces a warning; remove it from any existing config. The configuration above works correctly with both Vitest 3.x and 4.x. Vitest 4.x is supported as of `3.1.0`.
-:::
+</Aside>
<div class="next-steps-section">
## What's Next?
- Check out the [Quick Start](/docs/get-started/quickstart) guide to write the first test
- Explore the [Guides](/docs/guides/) section for testing patterns
- Browse [working examples](https://github.com/suites-dev/examples) for real-world code
-</div>
\ No newline at end of file
+</div>
diff --git a/docs/get-started/quickstart.md b/src/content/docs/get-started/quickstart.mdx
similarity index 97%
rename from docs/get-started/quickstart.md
rename to src/content/docs/get-started/quickstart.mdx
index b0f2dc6..593f91e 100644
--- a/docs/get-started/quickstart.md
+++ b/src/content/docs/get-started/quickstart.mdx
@@ -5,8 +5,9 @@ description: "Write your first Suites unit test in 5 minutes. Walkthrough for Ne
keywords: [suites quickstart, nestjs unit test example, inversify unit test, first nestjs test, vitest nestjs example, typescript unit test tutorial]
---
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+import Aside from '@/components/mdx/Aside.astro';
+import Tabs from '@/components/mdx/Tabs.astro';
+import TabItem from '@/components/mdx/TabItem.astro';
# Quick Start Guide
@@ -17,9 +18,9 @@ Write the first Suites test in 5 minutes. No manual mocks, no dependency injecti
* Sociable tests with real dependencies
* Zero-config testing
-:::info
+<Aside type="info">
Complete source code for this example (and more) is available in the [Suites Examples repository](https://github.com/suites-dev/examples).
-:::
+</Aside>
## Prerequisites
@@ -140,12 +141,12 @@ When `TestBed.solitary(UserService).compile()` is called, Suites automatically:
**What was not required:** Manually creating mocks, configuring dependency injection, or writing test setup boilerplate.
-:::tip Key Terminology
+<Aside type="tip" title="Key Terminology">
- **Solitary Test**: A test where all dependencies are automatically mocked (complete isolation)
- **Mock**: A fake object with stubbed methods (e.g., `Mocked<UserRepository>`)
- **Stub**: A fake method that returns predefined values (e.g., `mockResolvedValue(...)`)
-:::
+</Aside>
## Step 3: Testing with Real Dependencies (Sociable Mode)
@@ -180,11 +181,11 @@ describe('Notification Service Sociable Spec', () => {
});
```
-:::tip
+<Aside type="tip">
Sociable tests verify that components integrate correctly while keeping tests fast by mocking external boundaries (databases, HTTP clients, etc.).
Learn more in the [Sociable Unit Testing guide](/docs/guides/sociable).
-:::
+</Aside>
## How It Works: No Modules, No Bootstrapping
diff --git a/docs/get-started/why-suites.md b/src/content/docs/get-started/why-suites.mdx
similarity index 97%
rename from docs/get-started/why-suites.md
rename to src/content/docs/get-started/why-suites.mdx
index a33e530..6215ada 100644
--- a/docs/get-started/why-suites.md
+++ b/src/content/docs/get-started/why-suites.mdx
@@ -4,10 +4,9 @@ title: Why Suites?
description: Eliminate boilerplate in dependency injection testing. Suites provides type-safe test doubles and automatic mocking for TypeScript applications following the IoC principle.
---
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
-# Why Suites?
+import Aside from '@/components/mdx/Aside.astro';
+import Tabs from '@/components/mdx/Tabs.astro';
+import TabItem from '@/components/mdx/TabItem.astro';
Unit testing TypeScript applications with complex dependencies is **expensive and slow**. Whether using dependency injection containers, plain constructor injection, or functional composition, manual mocking creates brittle tests, cryptic errors, and mountains of boilerplate that bury test intent. Teams waste weeks debugging broken test doubles, onboarding junior developers, and maintaining inconsistent unit testing patterns across projects.
@@ -173,7 +172,7 @@ container.register(Database, { useValue: { query: jest.fn() } });
Suites provides a **declarative API** that removes manual mocking entirely. A single call creates a fully-typed,
isolated unit testing environment with type-safe test doubles. No boilerplate, no cryptic errors, no silent failures.
-:::tip Current Testing Options
+<Aside type="tip" title="Current Testing Options">
**Using dependency injection frameworks?**
`TestBed` provides automatic mock injection and reference tracking - the best testing experience.
@@ -181,7 +180,7 @@ isolated unit testing environment with type-safe test doubles. No boilerplate, n
**Not using dependency injection?**
Use `mock()` and `stub()` for type-safe mocking. Works with any TypeScript code, but requires manual dependency wiring
and reference tracking. See [mock() and stub() utilities](/docs/api-reference/mock).
-:::
+</Aside>
```typescript title="order.service.spec.ts" {1,9,11-13}
import { TestBed, type Mocked } from '@suites/unit';
diff --git a/docs/guides/fundamentals.md b/src/content/docs/guides/fundamentals.mdx
similarity index 98%
rename from docs/guides/fundamentals.md
rename to src/content/docs/guides/fundamentals.mdx
index 456f8a6..a1a52de 100644
--- a/docs/guides/fundamentals.md
+++ b/src/content/docs/guides/fundamentals.mdx
@@ -4,7 +4,7 @@ title: Unit Testing Fundamentals
description: Master unit testing fundamentals with the IoC principle. Learn solitary vs sociable testing, test doubles, and how Suites eliminates mock boilerplate for dependency injection and beyond.
---
-# Unit Testing Fundamentals
+import Aside from '@/components/mdx/Aside.astro';
> **What this covers:** Core principles of unit testing with the IoC principle and how Suites eliminates testing complexity \
> **Time to read:** ~10 minutes \
@@ -67,9 +67,9 @@ function createUserService(repo: UserRepository) {
This principle applies to any architectural choice: dependency injection frameworks, plain constructor injection, functional composition, or factory patterns. The key is that dependencies flow in from outside.
-:::info
+<Aside type="info">
Suites' testing theory builds on Martin Fowler's work on Inversion of Control and test doubles. Read more in his articles: [Inversion of Control](https://martinfowler.com/bliki/InversionOfControl.html) and [Mocks Aren't Stubs](https://martinfowler.com/articles/mocksArentStubs.html).
-:::
+</Aside>
## Prerequisites
@@ -128,11 +128,11 @@ Testing applications with IoC patterns presents several challenges:
const { unit, unitRef } = await TestBed.solitary(UserService).compile();
```
-:::tip 🤖 LLM-Friendly Design
+<Aside type="tip" title="🤖 LLM-Friendly Design">
Suites provides one canonical pattern that teaches the entire API. AI agents need a single
example in context instead of dozens of lines showing different manual mocking approaches. This reduces token
consumption and improves generation accuracy.
-:::
+</Aside>
## Testing Approaches Comparison
diff --git a/docs/guides/index.md b/src/content/docs/guides/index.mdx
similarity index 89%
rename from docs/guides/index.md
rename to src/content/docs/guides/index.mdx
index e0ca6be..1adb371 100644
--- a/docs/guides/index.md
+++ b/src/content/docs/guides/index.mdx
@@ -5,6 +5,8 @@ description: Practical guides for testing with Suites
toc_min_heading_level: 3
---
+import Aside from '@/components/mdx/Aside.astro';
+
# Testing Guides
Practical guides for writing solitary and sociable unit tests with Suites. Learn how to test components in isolation, verify real interactions between classes, and control external dependencies.
@@ -22,12 +24,10 @@ Practical guides for writing solitary and sociable unit tests with Suites. Learn
</div>
-:::tip
+<Aside type="tip">
Start with [Fundamentals](/docs/guides/fundamentals), then [Solitary](/docs/guides/solitary) and [Sociable](/docs/guides/sociable) testing.
-:::
+</Aside>
-:::tip Working Examples
+<Aside type="tip" title="Working Examples">
Browse the [Suites Examples repository](https://github.com/suites-dev/examples) for complete, runnable examples of solitary, sociable, and real-world testing patterns.
-:::
-
-
+</Aside>
diff --git a/docs/guides/sociable.md b/src/content/docs/guides/sociable.mdx
similarity index 96%
rename from docs/guides/sociable.md
rename to src/content/docs/guides/sociable.mdx
index ed7705c..559e207 100644
--- a/docs/guides/sociable.md
+++ b/src/content/docs/guides/sociable.mdx
@@ -4,8 +4,10 @@ title: Testing Components Together (Sociable)
description: Testing real component interactions with Suites
---
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
+import Aside from '@/components/mdx/Aside.astro';
+import Tabs from '@/components/mdx/Tabs.astro';
+import TabItem from '@/components/mdx/TabItem.astro';
+import MermaidDiagram from '@/components/mdx/MermaidDiagram';
# Testing Components Together (Sociable Testing)
@@ -216,9 +218,9 @@ describe('OrderService', () => {
});
```
-:::tip Understanding the Control Boundary
+<Aside type="tip" title="Understanding the Control Boundary">
Suites can only control **explicit dependencies** (passed through constructors). It cannot control implicit dependencies (direct imports). For more, see [Test Doubles](/docs/guides/test-doubles).
-:::
+</Aside>
## Step 4: Choose When to Configure Mocks
@@ -292,14 +294,14 @@ it('handles successful save', async () => {
Use this flowchart to decide how to handle each dependency:
-```mermaid
+<MermaidDiagram chart={`
flowchart LR
A[Dependency] --> B{External I/O?}
B -->|Yes| C[@Inject TOKEN<br/>Auto-mocked]
B -->|No| D{Business logic<br/>to test?}
D -->|Yes| E[.expose Class<br/>Uses real code]
D -->|No| F[Leave mocked<br/>default behavior]
-```
+`} client:visible />
**Rules:**
- **External I/O** (databases, APIs, file systems) → Use token injection → Auto-mocked
diff --git a/docs/guides/solitary.md b/src/content/docs/guides/solitary.mdx
similarity index 98%
rename from docs/guides/solitary.md
rename to src/content/docs/guides/solitary.mdx
index 7a7427c..a636290 100644
--- a/docs/guides/solitary.md
+++ b/src/content/docs/guides/solitary.mdx
@@ -4,6 +4,8 @@ title: Testing in Isolation (Solitary)
description: Testing in isolation with Suites
---
+import Aside from '@/components/mdx/Aside.astro';
+
# Testing Unit In Isolation (Solitary Testing)
> **What this covers:** Writing unit tests that isolate a single component (class) using automatic mocking \
@@ -126,9 +128,9 @@ userApi.getRandom.mockResolvedValue({ id: 1, name: 'John' });
database.saveUser.mockResolvedValue(42);
```
-:::info How This Works
+<Aside type="info" title="How This Works">
See [Virtual Test Container](/docs/guides/virtual-test-container) for how the virtual test container works under the hood.
-:::
+</Aside>
## Step 3: Configure Mock Behavior
@@ -148,9 +150,9 @@ it('test case', () => {
});
```
-:::info
+<Aside type="info">
For advanced configuration options, see [Mock Configuration](/docs/api-reference/mock-configuration).
-:::
+</Aside>
## Summary
diff --git a/docs/guides/test-doubles.md b/src/content/docs/guides/test-doubles.mdx
similarity index 98%
rename from docs/guides/test-doubles.md
rename to src/content/docs/guides/test-doubles.mdx
index 9ead5e1..6064ed3 100644
--- a/docs/guides/test-doubles.md
+++ b/src/content/docs/guides/test-doubles.mdx
@@ -5,6 +5,8 @@ description: "Type-safe test doubles for TypeScript unit tests. Auto-generate mo
keywords: [test doubles, mocks, stubs, spies, fakes, mocks vs stubs, typescript testing, unit testing, mock generation typescript, auto mocks, nestjs testing, vitest mocks, jest mocks]
---
+import Aside from '@/components/mdx/Aside.astro';
+
# Test Doubles: Mocks, Stubs, Spies, and Fakes
> **What this covers:** What test doubles are, the four main types, when to use each, and how Suites generates them
@@ -118,10 +120,10 @@ export class UserService {
When there are implicit dependencies, they always execute the real code during tests because Suites has no way to intercept them.
-:::tip
+<Aside type="tip">
Not all implicit dependencies are a problem. Simple utility functions like `Math.floor()` or `formatDate()` are fine.
But operations that touch the network, database, or file system should be explicit dependencies so you can replace them in tests.
-:::
+</Aside>
## Two Ways to Verify Tests
@@ -146,10 +148,10 @@ expect(repo.save).toHaveBeenCalledWith(userData); // Was save() called correctl
Both approaches work well with Suites. Choose the one that makes sense for what you're testing.
-:::note Common Pitfalls
+<Aside type="note" title="Common Pitfalls">
Using `spyOn()` or manual mocks (`jest.mock()`/`vitest.mock()`) frequently, usually means the code has too many
implicit dependencies. Consider refactoring to use explicit dependencies instead (pass dependencies in through the constructor)
-:::
+</Aside>
## Using Mocks in Suites
@@ -217,4 +219,4 @@ Learn more about using test doubles in practice:
## Additional Resources
- **[Martin Fowler - Mocks Aren't Stubs](https://martinfowler.com/articles/mocksArentStubs.html)**: Classic article
- explaining different testing approaches
\ No newline at end of file
+ explaining different testing approaches
diff --git a/docs/guides/virtual-test-container.md b/src/content/docs/guides/virtual-test-container.md
similarity index 100%
rename from docs/guides/virtual-test-container.md
rename to src/content/docs/guides/virtual-test-container.md
diff --git a/docs/migration-guides/from-automock.md b/src/content/docs/migration-guides/from-automock.mdx
similarity index 98%
rename from docs/migration-guides/from-automock.md
rename to src/content/docs/migration-guides/from-automock.mdx
index f1de56e..ce761cf 100644
--- a/docs/migration-guides/from-automock.md
+++ b/src/content/docs/migration-guides/from-automock.mdx
@@ -5,12 +5,12 @@ description: How to migrate from @automock/jest and @automock/sinon to Suites. C
keywords: [ automock, migrate from automock, automock to suites, "@automock/jest", "@automock/sinon", testbedbuilder, suites migration ]
---
-# Migrating from Automock to Suites
+import Aside from '@/components/mdx/Aside.astro';
-:::danger Automock Deprecation Notice
+<Aside type="danger" title="Automock Deprecation Notice">
**Automock will be fully deprecated on June 30, 2026.** Until then, it receives critical fixes only. All new features
and improvements are released exclusively under Suites 3.x. Please migrate before the deprecation date.
-:::
+</Aside>
## Introduction
@@ -32,7 +32,7 @@ Suites.
## Migration Guide
-:::tip Recommended: run the codemod
+<Aside type="tip" title="Recommended: run the codemod">
The [`@suites/codemod`](https://github.com/suites-dev/codemod) package automates almost everything in this guide: it
rewrites imports, converts `TestBed.create()` to `await TestBed.solitary().compile()`, picks between `.impl()` and
`.final()` for each mock, switches `jest.Mocked<T>` to `Mocked<T>`, and adds `async`/`await` to test hooks where needed.
@@ -48,7 +48,7 @@ npx @suites/codemod automock/2/to-suites-v3 'src/**/*.spec.ts'
After running, you still need to [update your dependencies](#step-1-update-dependencies) (the codemod only rewrites
code, not `package.json`). The remaining steps below describe what the codemod does, in case you want to migrate
manually or understand a specific transformation.
-:::
+</Aside>
### Step 1: Update Dependencies
diff --git a/docs/migration-guides/index.md b/src/content/docs/migration-guides/index.md
similarity index 95%
rename from docs/migration-guides/index.md
rename to src/content/docs/migration-guides/index.md
index 35f0a6a..6c02190 100644
--- a/docs/migration-guides/index.md
+++ b/src/content/docs/migration-guides/index.md
@@ -4,8 +4,6 @@ title: Migration Guides
description: Guides for migrating to Suites or upgrading versions
---
-# Migration Guides
-
Guides for migrating to Suites from other testing frameworks or upgrading between Suites versions.
## Available Guides
diff --git a/src/css/custom.css b/src/css/custom.css
deleted file mode 100644
index 6e9c8b3..0000000
--- a/src/css/custom.css
+++ /dev/null
@@ -1,626 +0,0 @@
-/**
- * Any CSS included here will be global. The classic template
- * bundles Infima by default. Infima is a CSS framework designed to
- * work well for content-centric websites.
- */
-
-/* Import Geist Mono font */
-@import url('https://cdn.jsdelivr.net/npm/geist@1.3.0/dist/mono.css');
-
-/* You can override the default Infima variables here. */
-
-:root {
- /* Font Families - System Font Stack */
- --font-body: system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
- --font-heading: system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
- --font-code: 'Geist Mono', Menlo, Monaco, Lucida Console, Liberation Mono, DejaVu Sans Mono, Bitstream Vera Sans Mono, Courier New, monospace;
-
- /* Override Infima font-size - larger to compensate for system fonts */
- --ifm-font-size-base: 18px;
-
- /* Primary Colors */
- --ifm-color-primary: rgba(239,71,121,1); /* Bright Pink */
- --ifm-color-primary-light: #FF9EBB; /* Light Pink */
- --ifm-color-primary-dark: #750e2d; /* Dark Pink */
-
- /* Complementary and Neutral Shades */
- --ifm-color-accent: #522E38; /* Deep Mauve, works as a darker, neutral complement */
- --ifm-color-secondary: #FFC2D4; /* Soft Pink, lighter and less saturated */
- --ifm-background-color-dark: #602437; /* Deep Reddish Brown, good for dark mode backgrounds or accents */
-
- /* Utility Colors */
- --ifm-color-success: #52c41a; /* A fresh green for success messages, not from pink range but provides contrast */
- --ifm-color-error: #f5222d; /* Vivid red for errors, enhancing visibility */
- --ifm-color-warning: #faad14; /* Bright yellow for warnings, stands out in the pink context */
- --ifm-color-info: #1890ff; /* Blue, for informational messages, contrasts well with pink */
-
- /* Neutral Grays (useful for typography, borders, etc.) */
- --ifm-color-gray: #8A2846; /* This is a grayish pink, quite muted */
- --ifm-color-gray-dark: rgb(86, 90, 98); /* Dark gray, close to charcoal */
- --ifm-color-gray-darker: #262b34ff; /* Even darker, great for high contrast elements */
- --ifm-color-gray-light: #f2f4f4ff; /* Light gray for background contrasts and space */
-
- /* Force dark mode theme colors */
- --theme-background: #1a1a1a;
- --theme-text: #e6e6e6;
- --theme-border: rgba(255, 255, 255, 0.1);
- --theme-section-bg: #2d2d2d;
- --theme-section-border: var(--ifm-color-primary);
- --theme-card-bg: rgba(45, 45, 45, 0.7);
- --theme-card-hover-shadow: rgba(0, 0, 0, 0.2);
- --theme-card-text: #c4c4c4;
-
- /* Override docusaurus colors to force dark mode */
- --ifm-background-color: #1a1a1a;
- --ifm-font-color-base: #e6e6e6;
-
- /* Force dark color scheme only */
- color-scheme: dark;
-}
-
-html {
- font-size: 16px; /* Explicit root size for rem calculations - matches Next.js */
- position: relative;
- min-height: 450px;
- background-color: var(--theme-background);
- color: var(--theme-text);
-}
-
-body {
- font-family: var(--font-body);
- font-size: 18px;
- font-weight: 450;
- line-height: 1.6;
- -webkit-font-smoothing: antialiased;
- background-color: var(--theme-background);
- color: var(--theme-text);
-}
-
-* {
- outline: 0 !important;
-}
-
-/* Link styling - Next.js inspired */
-a {
- font-weight: 500;
- text-decoration: none;
- transition: opacity 0.2s ease;
-}
-
-a:hover {
- text-decoration: underline;
- text-underline-offset: 3.5px;
- text-decoration-thickness: 1.5px;
- opacity: 0.9;
-}
-
-/* Custom link state styling */
-main a {
- color: var(--ifm-color-primary);
-}
-
-/* Fix for the active link state (when clicked) - only for content */
-main a:active {
- color: var(--ifm-color-primary) !important; /* Keep original color */
- text-decoration: underline !important; /* Add underline for visual feedback */
-}
-
-/* Documentation links */
-.markdown a {
- color: var(--ifm-color-primary);
- font-weight: 500;
-}
-
-.markdown h3 {
- font-size: 1.5rem;
- font-weight: 600;
-}
-
-.markdown a:active {
- color: var(--ifm-color-primary) !important;
- text-decoration: underline !important;
-}
-
-/* Table of contents links */
-.table-of-contents__link:active {
- color: var(--ifm-color-primary) !important;
- text-decoration: underline !important;
-}
-
-/* Sidebar menu links - excluding from active state color change */
-.menu__link:active {
- text-decoration: underline !important;
-}
-
-/* Fix admonition/info cube links and borders */
-.alert {
- border: none !important;
- border-radius: 0;
- border-left-width: 6px !important;
- border-left-style: solid !important;
- box-shadow: none;
-}
-
-.alert a {
- color: #ffffff !important;
- font-weight: 600;
- text-decoration: underline;
-}
-
-.alert a:hover {
- opacity: 0.8;
-}
-
-/* Specific alert type styling */
-.alert--info {
- border-left-color: var(--ifm-color-info) !important;
-}
-
-.alert--success {
- border-left-color: var(--ifm-color-success) !important;
-}
-
-.alert--warning {
- border-left-color: var(--ifm-color-warning) !important;
-}
-
-.alert--danger {
- border-left-color: var(--ifm-color-error) !important;
-}
-
-.next-steps-section h2 {
- font-family: var(--font-heading);
- font-weight: 600;
- margin-bottom: 1.5rem;
- color: var(--theme-text);
-}
-
-.next-steps-section ul {
- display: grid;
- grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
- gap: 1rem;
- list-style: none;
- padding: 0;
-}
-
-.next-steps-section ul li {
- background: var(--theme-card-bg);
- border: 1px solid var(--theme-border);
- border-radius: 8px;
- padding: 1.25rem;
- transition: all 0.2s ease;
-}
-
-.next-steps-section ul li:hover {
- border-color: var(--ifm-color-primary-light);
- box-shadow: 0 4px 12px var(--theme-card-hover-shadow);
- transform: translateY(-2px);
-}
-
-.next-steps-section ul li a {
- display: block;
- font-weight: 500;
- font-size: 1.1rem;
- margin-bottom: 0.5rem;
- color: var(--ifm-color-primary);
-}
-
-.next-steps-section ul li p {
- color: var(--theme-card-text);
- font-size: 0.95rem;
- margin: 0;
-}
-
-/* In This Section component for index pages */
-.in-this-section {
- margin: 0.5rem 0 3rem;
- padding: 1.5rem 2rem;
- background-color: var(--theme-section-bg);
- border-radius: 12px;
- border-left: 4px solid var(--theme-section-border);
- box-shadow: 0 4px 8px rgba(0, 0, 0, 0.05);
-}
-
-.in-this-section h3 {
- margin-top: 0;
- margin-bottom: 1.5rem;
- font-size: 1.5rem;
- font-weight: 700;
- color: var(--theme-text);
-}
-
-.in-this-section ul {
- display: grid;
- grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
- gap: 1rem;
- margin: 0;
- padding-left: 0;
- list-style: none;
-}
-
-.in-this-section ul li {
- position: relative;
- padding-left: 1.5rem;
- padding-bottom: 0.5rem;
- color: var(--theme-text);
- font-size: 1.05rem;
-}
-
-.in-this-section ul li::before {
- content: '›';
- position: absolute;
- left: 0;
- top: 0.05em;
- color: var(--ifm-color-primary);
- font-weight: bold;
- font-size: 1.4rem;
- line-height: 1;
-}
-
-.in-this-section strong {
- color: var(--theme-text);
- font-weight: 600;
-}
-
-/* Replace generic h2:last-of-type selector with a specific class */
-.section-divider {
- margin-top: 3rem;
- padding-top: 1.5rem;
- border-top: 1px solid var(--theme-border);
- color: var(--theme-text);
-}
-
-/* Update related selectors to use the new class */
-.section-divider + ul {
- padding-left: 0;
-}
-
-.section-divider + ul li {
- list-style: none;
- margin-bottom: 0.75rem;
- color: var(--theme-text);
-}
-
-.section-divider + ul li a {
- font-weight: 500;
- color: var(--ifm-color-primary);
-}
-
-.container {
- margin-right: auto;
- margin-left: auto;
- padding-left: 10px;
- padding-right: 10px;
-}
-
-@media (min-width: 768px) {
- .container {
- width: 750px;
- }
-}
-
-@media (min-width: 992px) {
- .container {
- width: 970px;
- }
-}
-
-@media (min-width: 1200px) {
- .container {
- width: 1170px;
- }
-}
-
-h1, h2, h3, h4, h5, h6 {
- font-family: var(--font-heading);
- color: var(--theme-text);
-}
-
-h1 {
- font-size: 2.5rem; /* 48px */
- font-weight: 600;
- line-height: 1.2;
- margin-top: 0;
- margin-bottom: 1rem;
-}
-
-h2 {
- font-size: 1.75rem;
- font-weight: 600;
- line-height: 1.333;
- margin-top: 1em;
- margin-bottom: 0.75em;
-}
-
-h3 {
- font-size: 1.25rem; /* 20px */
- font-weight: 500;
- line-height: 1.6;
- margin-top: 1.6em;
- margin-bottom: 0.6em;
-}
-
-h4 {
- font-size: 1rem; /* 16px */
- font-weight: 500;
- line-height: 1.5;
- margin-top: 1.5em;
- margin-bottom: 0.5em;
-}
-
-/* Lead text */
-.lead,
-p.lead {
- font-size: 1.25rem; /* 20px */
- line-height: 1.6;
- margin-top: 1.2em;
- margin-bottom: 1.2em;
-}
-
-/* Paragraph spacing */
-p {
- margin-top: 1.25em;
- margin-bottom: 1.25em;
-}
-
-/* Inline code styling */
-code {
- font-family: var(--font-code), serif;
- font-size: 15px;
- font-weight: 400;
- padding: .12em .25em;
- line-height: 1.2;
- border: 1px solid #3e3c3c;
- border-radius: .375rem;
- background: #2a2828;
- color: #e6e6e6;
-}
-
-/* Code blocks */
-code[class*="language-"],
-pre[class*="language-"] {
- font-family: var(--font-code);
- font-size: 16px;
- font-weight: 400;
- text-align: left;
- word-spacing: normal;
- word-break: normal;
- word-wrap: normal;
- line-height: 1.5;
- -moz-tab-size: 4;
- -o-tab-size: 4;
- tab-size: 4;
-
- -webkit-hyphens: none;
- -moz-hyphens: none;
- -ms-hyphens: none;
- hyphens: none;
-
- @media print {
- text-shadow: none;
- }
-}
-
-pre > code {
- font-family: var(--font-code);
- font-size: 14px;
- border-top-left-radius: unset;
- border-top-right-radius: unset;
- overflow: hidden;
- font-weight: 400;
- border: 1px solid hsla(0,0%,100%,.05);
- padding: 0;
- background: transparent;
-}
-
-/* Keyboard keys */
-kbd {
- font-family: var(--font-code);
- font-size: 14px;
- font-weight: 500;
- padding: 3px 6px;
- border-radius: 5px;
- border: 1px solid #3e3c3c;
- background: #2a2828;
- color: #e6e6e6;
-}
-
-code .theme-code-block-highlighted-line {
- background-color: rgba(255, 255, 255, 0.12);
-}
-
-div[class*="codeBlockTitle_"] {
- font-family: var(--font-body);
- color: rgb(153 161 179/1);
- background-color: rgb(35 39 47/1);
- border: 1px solid hsla(0,0%,100%,.05);
- border-bottom: none;
-}
-
-.theme-doc-breadcrumbs {
- font-family: var(--font-body);
- margin-bottom: 2rem !important;
-}
-
-.breadcrumbsContainer {
- margin-bottom: 2rem !important;
-}
-
-.docs-introduction {
- width: 60%;
- margin: 0 auto;
-}
-
-.header-github-link:hover {
- opacity: 0.6;
-}
-
-.header-github-link:before {
- content: '';
- width: 24px;
- height: 24px;
- display: flex;
- background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
- no-repeat;
-}
-
-html[data-theme='dark'] .header-github-link:before {
- background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='white' d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E")
- no-repeat;
-}
-
-/* Sponsor button styling */
-.header-sponsor-link {
- display: inline-flex !important;
- align-items: center;
- gap: 6px;
- padding: 6px 16px !important;
- background-color: rgba(55, 58, 64, 1) !important;
- color: rgba(230, 230, 230, 1) !important;
- border-radius: 50px;
- font-weight: 600;
- font-size: 1rem;
- transition: all 0.3s ease;
- text-decoration: none !important;
- margin-right: 8px;
- border: none;
- white-space: nowrap;
-}
-
-.header-sponsor-link:hover {
- background-color: rgba(65, 68, 74, 1) !important;
- color: rgba(240, 240, 240, 1) !important;
- text-decoration: none;
-}
-
-.header-sponsor-link:before {
- content: '';
- width: 16px;
- height: 16px;
- display: inline-block;
- background: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath fill='%23EF4779' d='M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z'/%3E%3C/svg%3E")
- no-repeat center;
- background-size: contain;
-}
-
-/* Hide external link icon for sponsor link */
-.header-sponsor-link svg[class*="iconExternalLink"] {
- display: none !important;
-}
-
-@media (max-width: 768px) {
- .header-sponsor-link {
- margin-right: 48px;
- }
-}
-
-/* Move GitHub icon after search */
-.navbar__items--right {
- display: flex;
-}
-
-.header-github-link {
- order: 10 !important;
-}
-
-.navbar__search {
- order: 5 !important;
-}
-
-/* Add a manual theme toggler, add this if you want a button to override system preference */
-.theme-toggle-button {
- margin-left: 0.5rem;
- padding: 0.4rem;
- border-radius: 50%;
- display: flex;
- align-items: center;
- justify-content: center;
- transition: background-color 0.2s;
- background-color: transparent;
- border: none;
- cursor: pointer;
-}
-
-.theme-toggle-button:hover {
- background-color: var(--theme-border);
-}
-
-/* Dark mode is always enabled */
-html[data-theme='dark'] .theme-toggle-button svg {
- fill: #f5f5f5;
-}
-
-/* Dark mode styling (always applied) */
-.in-this-section {
- box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
-}
-
-.alert a {
- color: #ffffff !important;
-}
-
-/* Version Badge Styles */
-.version-badge {
- display: inline-block;
- font-size: 0.75rem;
- font-weight: 600;
- padding: 0.2rem 0.5rem;
- margin-left: 0.5rem;
- border-radius: 4px;
- vertical-align: middle;
- white-space: nowrap;
- font-family: var(--font-body);
- letter-spacing: 0.025em;
-}
-
-.version-badge--new {
- background-color: rgba(239, 71, 121, 0.15);
- color: var(--ifm-color-primary);
- border: 1px solid rgba(239, 71, 121, 0.3);
-}
-
-.version-badge--deprecated {
- background-color: rgba(245, 34, 45, 0.15);
- color: var(--ifm-color-error);
- border: 1px solid rgba(245, 34, 45, 0.3);
-}
-
-h2 .version-badge,
-h3 .version-badge {
- font-size: 0.65em;
- position: relative;
- top: -0.1em;
-}
-
-/* Documentation metadata blockquote - subtle styling for guide page metadata */
-.theme-doc-markdown article > blockquote:first-of-type,
-article.markdown > blockquote:first-of-type,
-.markdown > blockquote:first-of-type {
- background-color: rgba(255, 255, 255, 0.03) !important;
- border-left: 3px solid rgba(239, 71, 121, 0.4) !important;
- border-radius: 2px !important;
- padding: 1.25rem 1.5rem !important;
- margin: 2rem 0 !important;
- font-size: 1rem !important;
- line-height: 1.9 !important;
-}
-
-.theme-doc-markdown article > blockquote:first-of-type p,
-article.markdown > blockquote:first-of-type p,
-.markdown > blockquote:first-of-type p {
- margin: 0 !important;
- color: #c4c4c4 !important;
-}
-
-.theme-doc-markdown article > blockquote:first-of-type strong,
-article.markdown > blockquote:first-of-type strong,
-.markdown > blockquote:first-of-type strong {
- color: var(--ifm-color-gray-light) !important;
- font-weight: 500 !important;
-}
-
-.theme-doc-markdown article > blockquote:first-of-type a,
-article.markdown > blockquote:first-of-type a,
-.markdown > blockquote:first-of-type a {
- color: var(--ifm-color-secondary) !important;
-}
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
new file mode 100644
index 0000000..e11a356
--- /dev/null
+++ b/src/layouts/BaseLayout.astro
@@ -0,0 +1,103 @@
+---
+import DocsHeader from '@/components/site/Header.astro';
+import MarketingHeader from '@/components/site/MarketingHeader.astro';
+import Footer from '@/components/site/Footer.astro';
+import GoogleAnalytics from '@/components/islands/GoogleAnalytics.astro';
+import '@/styles/globals.css';
+
+interface Props {
+ title?: string;
+ description?: string;
+ ogImage?: string;
+ /* Docs pages opt out of the marketing footer; the prev/next pager already
+ terminates the article. Marketing surfaces (homepage, 404, etc.) render
+ it by default. */
+ showFooter?: boolean;
+ /* "docs" renders the docs header (brand "/ docs", DocSearch, product-tab
+ row). "marketing" renders the bare marketing header with the Tools and
+ Community dropdowns. Defaults to marketing so non-docs surfaces don't
+ need to opt in. */
+ header?: 'docs' | 'marketing';
+}
+
+const {
+ title = 'Suites Documentation',
+ description = 'A unit testing framework for TypeScript backends working with inversion of control and dependency injection',
+ ogImage = 'https://suites.dev/img/banner.png',
+ showFooter = true,
+ header = 'marketing',
+} = Astro.props;
+
+const fullTitle = title === 'Suites Documentation' ? title : `${title} | Suites`;
+---
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>{fullTitle}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {/* Theme resolver: runs before first paint to avoid a flash.
+ Order of precedence: explicit user choice in localStorage,
+ otherwise OS preference, otherwise dark (our default). */}
+
+
+
+
+
+ Skip to main content
+ {header === 'docs' ? : }
+
+
+
+ {showFooter && }
+
+
-
-