@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/examples/custom-language/README.md

@@ -0,0 +1,32 @@
+# Custom language highlighting
+
+Register a local TextMate JSON grammar under
+`outputs.html.highlighting.languages`, then use its `id` or an `aliases` entry
+as a fenced-code language. This example adds two illustrative keywords to
+Python's existing syntax-color rules.
+
+From this directory, with the CLI installed in your project:
+
+```sh
+npx --no-install shoalrun build docs.config.yaml site-dist
+npx --no-install shoalrun serve site-dist --port 8770
+```
+
+From the framework repository root:
+
+```sh
+node framework/dist/cli.js build framework/examples/custom-language/docs.config.yaml /tmp/shoalrun-custom-language
+node framework/dist/cli.js serve /tmp/shoalrun-custom-language --port 8770
+```
+
+Grammar paths resolve from the configuration file that declares them. The
+compiler tracks those files as build dependencies; edit the grammar and rebuild,
+or use `dev` for watched editing. Malformed or missing grammars fail the build
+and preserve existing output. IDs and aliases can't replace bundled languages;
+each grammar needs a distinct `scopeName`.
+
+The resulting HTML contains syntax colors without loading the grammar in the
+browser. Markdown keeps the original code and fence label. The grammar doesn't
+validate programs or add autocomplete, filename-based language inference, or
+editor integration. Replace this illustrative grammar with your language's
+grammar and retain its applicable license notices.

package/examples/custom-language/content/start.mdx

@@ -0,0 +1,28 @@
+---
+id: guide.custom-language
+title: Highlight a custom language
+summary: Register a local TextMate grammar and use its language ID or alias in fenced examples.
+type: guide
+slug: /
+channel: production
+version: current
+language: en
+access: { policy: public }
+---
+
+This illustrative Python-like language adds `publish` and `unless`. The grammar
+recognizes these keywords before falling back to the bundled Python grammar.
+
+```custompy title="Language ID"
+def welcome(name):
+    unless name is None:
+        publish "Hello, " + name
+```
+
+The alias selects the same grammar:
+
+```cpy title="Language alias"
+publish "The same syntax colors, with a shorter fence label."
+```
+
+This example only defines syntax colors. It doesn't implement an executable language.

package/examples/custom-language/docs.config.yaml

@@ -0,0 +1,18 @@
+schemaVersion: 1
+site:
+  title: Custom language example
+  contentDir: ./content
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels: { production: {} }
+  versions: { current: {} }
+  enabled: [{ channel: production, version: current, language: en }]
+outputs:
+  html:
+    shareImages: false
+    highlighting:
+      provider: shiki
+      languages:
+        - id: custompy
+          grammar: ./grammars/custompy.tmLanguage.json
+          aliases: [cpy]

package/examples/custom-language/grammars/custompy.tmLanguage.json

@@ -0,0 +1,7 @@
+{
+  "scopeName": "source.custompy",
+  "patterns": [
+    { "name": "keyword.control.custompy", "match": "\\b(?:publish|unless)\\b" },
+    { "include": "source.python" }
+  ]
+}

package/examples/pdf/README.md

@@ -0,0 +1,27 @@
+# Styled PDF export
+
+This project demonstrates browser page printing and optional CLI PDF exports. All configuration values and thresholds are examples.
+
+Build and preview the static site without a browser dependency:
+
+```sh
+shoalrun build docs.config.yaml site-dist
+shoalrun serve site-dist --port 8892
+```
+
+Open `/start` and choose **Print PDF**. The browser fills a separate print view using the shared PDF theme and opens its print dialog. Site builds add shared scripts, styling, settings, and configured print assets; they generate no page PDFs or extra print documents. This works on static hosting, including Vercel. Allow the print view to open if the browser blocks it. Without JavaScript, use the browser's own Print command.
+
+For a downloadable full manual, explicitly run the CLI export with an installed browser:
+
+```sh
+export SHOALRUN_PDF_BROWSER="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+shoalrun export docs.config.yaml --format pdf --out pdf/manual
+```
+
+Use the correct Chrome/Chromium executable path for your operating system. No browser is downloaded automatically. The command writes `pdf/manual/publication.pdf`. Publish that file and a deliberate download link only when wanted; it isn't added to the site automatically. Copy it into the static deployment after the site build, which replaces its output directory. Add `--document guide.start` to generate a single-page PDF explicitly.
+
+Change `print.css` for manual and browser print-view colors, typography, and page breaks. Set `outputs.pdf.fonts` to local licensed font files and reference their registered families in CSS. Use `outputs.pdf.logo` for a local cover image. Print CSS can't import files or load URLs; fonts and logo are registered explicitly. Optional `outputs.html.pdf.style` selects a named export target's PDF styling without changing page selection. Headers and footers accept `{title}`, `{page}`, and `{pages}`; browser views use CSS page-margin support. Use `site.customCss` with `@media print` for the ordinary browser Print fallback, which doesn't open a branded view.
+
+Inspect the actual PDF for spacing, math, long content, links, and bookmarks. The manual's table of contents is linked without printed page numbers. Chromium bookmark/tagging support is experimental; the output isn't certified PDF/UA. The `pdf` export manifest is separate from content REST representations.
+
+Explicit `outputs.html.pdf.mode: endpoint` supports direct page PDF downloads through a Node host with Chromium. It isn't for static hosting. Keep `pdf-runtime.json` and `__shoalrun/pdf-data` behind that server; don't expose them through a generic static host.

package/examples/pdf/content/operations.mdx

@@ -0,0 +1,26 @@
+---
+id: guide.operations
+title: Run daily operations
+summary: Review workspace activity and record an outcome.
+slug: /operations
+---
+
+Start each review by checking the [workspace setup](doc:guide.start). Record the review date and result with your operating notes.
+
+## Review activity
+
+Use these example thresholds to decide whether activity needs investigation:
+
+| Signal | Expected value | Follow-up |
+| --- | --- | --- |
+| Queued work | Below 100 items | Check worker capacity. |
+| Oldest item | Below 10 minutes | Inspect the processing log. |
+| Failed items | Zero | Review the reported failure. |
+
+For a completed-work count of 90 out of 100, the completion ratio is:
+
+<Math display expression="r = \frac{90}{100} = 0.9" />
+
+## Record the outcome
+
+Save a brief report with the observed counts and any follow-up action. Link to [the review section](#review-activity) so the next operator can repeat the checks.

package/examples/pdf/content/start.mdx

@@ -0,0 +1,28 @@
+---
+id: guide.start
+title: Start your workspace
+summary: Configure a workspace and confirm its status.
+slug: /start
+---
+
+Create a workspace before running daily operations. Keep its configuration in your project so another operator can reproduce the setup.
+
+## Configure the workspace
+
+Save the following example configuration:
+
+```yaml
+workspace:
+  name: training
+  retentionDays: 30
+```
+
+## Verify the result
+
+Confirm that the workspace name is `training` and that retention is 30 days. Continue with [daily operations](doc:guide.operations).
+
+<Collapsible title="Configuration checklist">
+
+Record the workspace owner, retention period, and expected data source before adding live data.
+
+</Collapsible>

package/examples/pdf/docs.config.yaml

@@ -0,0 +1,29 @@
+schemaVersion: 1
+site:
+  title: Operations documentation
+  origin: https://docs.example.com
+frontmatter:
+  defaults:
+    type: guide
+    channel: production
+    version: current
+    access: { policy: public }
+publications:
+  defaults: { channel: production, version: current, language: en }
+  channels: { production: {} }
+  versions: { current: {} }
+  enabled: [{ channel: production, version: current }]
+navigation:
+  - { id: start, doc: guide.start }
+  - { id: operations, doc: guide.operations }
+outputs:
+  pdf:
+    stylesheet: ./print.css
+    size: A4
+    footer: "{title} | {page} / {pages}"
+    subtitle: Setup and daily operations
+  html:
+    pdf:
+      mode: print
+      label: Print PDF
+      placement: after

package/examples/pdf/print.css

@@ -0,0 +1,9 @@
+:root {
+  --pdf-accent: #28584b;
+  --pdf-text: #172722;
+  --pdf-muted: #53665e;
+  --pdf-font: Arial, sans-serif;
+}
+.pdf-cover { border-top: 6pt solid var(--pdf-accent); }
+.pdf-cover h1 { max-width: 15ch; }
+th { background: #e5eee9; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoalrun/cli",
-  "version": "0.1.0-alpha.19",
+  "version": "1.0.0",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"
@@ -11,11 +11,13 @@
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
+    "./references": "./dist/code-reference-model.js",
     "./content": "./dist/content-delivery.js",
     "./authoring": "./dist/authoring-api.js",
     "./*": "./*",
     "./components": "./dist/components.js",
-    "./content/server": "./dist/content-rest-server.js"
+    "./content/server": "./dist/content-rest-server.js",
+    "./pdf/server": "./dist/pdf-http.js"
   },
   "files": [
     "dist",
@@ -26,6 +28,7 @@
     "templates",
     "examples",
     "!examples/**/public/**",
+    "!examples/**/site-dist/**",
     "!examples/**/node_modules/**",
     "example-configs",
     "!example-configs/**/.shoalrun/**",
@@ -33,7 +36,12 @@
     "skills",
     "README.md",
     "AUTHORING.md",
+    "CODE-REFERENCES.md",
     "DEPLOYMENT-PROFILES.md",
+    "schemas/code-reference.schema.json",
+    "adapters/python",
+    "!**/__pycache__/**",
+    "!adapters/python/test_*.py",
     "schemas/content-export.schema.json",
     "schemas/content-rest.openapi.json",
     "CHANGELOG.md",
@@ -70,6 +78,7 @@
     "lucide": "1.47.0",
     "parse5": "8.0.1",
     "pele": "1.6.0",
+    "puppeteer-core": "25.16.0",
     "rehype-stringify": "10.0.1",
     "remark-gfm": "4.0.1",
     "remark-mdx": "3.1.1",

package/schemas/code-reference.schema.json

@@ -0,0 +1,306 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "schemaVersion": {
+      "type": "number",
+      "const": 1
+    },
+    "kind": {
+      "type": "string",
+      "const": "shoalrun-code-reference"
+    },
+    "programmingLanguage": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+    },
+    "producer": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "extractorVersion": {
+          "type": "string",
+          "maxLength": 100
+        }
+      },
+      "required": [
+        "name",
+        "version"
+      ],
+      "additionalProperties": false
+    },
+    "sourceDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$"
+    },
+    "symbols": {
+      "minItems": 1,
+      "maxItems": 10000,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": "^[^\\s\\x00-\\x1f]+$"
+          },
+          "name": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "module",
+              "namespace",
+              "class",
+              "interface",
+              "enum",
+              "type",
+              "function",
+              "method",
+              "constructor",
+              "property",
+              "attribute",
+              "constant"
+            ]
+          },
+          "parent": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "pattern": "^[^\\s\\x00-\\x1f]+$"
+          },
+          "visibility": {
+            "default": "public",
+            "type": "string",
+            "enum": [
+              "public",
+              "private"
+            ]
+          },
+          "summary": {
+            "type": "string",
+            "maxLength": 1000
+          },
+          "description": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "annotation": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "default": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "required": {
+            "type": "boolean"
+          },
+          "bases": {
+            "maxItems": 100,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "maxLength": 100000
+            }
+          },
+          "constructorSignature": {
+            "type": "string",
+            "maxLength": 100000
+          },
+          "typeReferences": {
+            "type": "object",
+            "propertyNames": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512
+            },
+            "additionalProperties": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[^\\s\\x00-\\x1f]+$"
+            }
+          },
+          "signatures": {
+            "maxItems": 100,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "maxLength": 100000
+            }
+          },
+          "parameters": {
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                },
+                "type": {
+                  "type": "string",
+                  "maxLength": 100000
+                },
+                "description": {
+                  "type": "string",
+                  "maxLength": 100000
+                },
+                "default": {
+                  "type": "string",
+                  "maxLength": 100000
+                }
+              },
+              "required": [
+                "name"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "returns": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "maxLength": 100000
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 100000
+              }
+            },
+            "additionalProperties": false
+          },
+          "yields": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "maxLength": 100000
+              },
+              "description": {
+                "type": "string",
+                "maxLength": 100000
+              }
+            },
+            "additionalProperties": false
+          },
+          "raises": {
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512
+                },
+                "type": {
+                  "type": "string",
+                  "maxLength": 100000
+                },
+                "description": {
+                  "type": "string",
+                  "maxLength": 100000
+                },
+                "default": {
+                  "type": "string",
+                  "maxLength": 100000
+                }
+              },
+              "required": [
+                "name"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "examples": {
+            "maxItems": 100,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "title": {
+                  "type": "string",
+                  "maxLength": 512
+                },
+                "code": {
+                  "type": "string",
+                  "maxLength": 100000
+                }
+              },
+              "required": [
+                "code"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "seeAlso": {
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "pattern": "^[^\\s\\x00-\\x1f]+$"
+            }
+          },
+          "source": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 1000,
+                "pattern": "^(?!\\/)(?!.*(?:^|\\/)\\.{1,2}(?:\\/|$))[^/\\\\\\x00:]+(?:\\/[^/\\\\\\x00:]+)*$"
+              },
+              "line": {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": [
+              "path"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "kind",
+          "visibility"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "kind",
+    "programmingLanguage",
+    "producer",
+    "symbols"
+  ],
+  "additionalProperties": false,
+  "title": "Shoalrun Code API reference snapshot"
+}

package/skills/shoalrun-author/SKILL.md

@@ -21,6 +21,10 @@ When reading a published site through Markdown, follow topic-index links when pr
 
 Read `reference.authoring-workspace` for tool contracts and `guide.authoring-workspace` for the working-tree procedure. Before unfamiliar syntax, check the relevant component attributes, configuration structure, or asset-handling contract instead of assuming another tool’s conventions. For MDX components, read their canonical reference; `<Step>` belongs inside `<Steps>` for an ordinary titled procedure, while your harness's task plan is separate. Read implementation/specification evidence with your harness's permitted tools; record the sources for changed claims. Bundled guidance does not establish a consumer project's facts.
 
+## Code API references
+
+For source-code library or SDK references, read [references/code-api-references.md](references/code-api-references.md). Keep these separate from OpenAPI endpoint references. Extract explicitly, validate the snapshot, preserve publication and feature scope, and choose symbol, class, module, or optional complete-page presentation deliberately.
+
 ## Products and availability
 
 For independently versioned products, cross-product reuse, product-scoped delivery, or feature availability labels, read [references/publications.md](references/publications.md). Preserve product/channel/version/language identity, distinguish publication membership from feature grants, and check installed-version support before using new fields. Availability labels describe support; they don't filter the published content.
@@ -31,6 +35,8 @@ For SKU-selected or white-label documentation, read [references/customer-edition
 
 ## Record scope and edit
 
+For PDF export or page print/download actions, read [references/pdf-export.md](references/pdf-export.md). Keep PDF selection distinct from reader-view controls. Use browser printing on static sites, optional CLI manual downloads, and explicit Node-hosted generation when needed.
+
 Before editing, capture the current state with `docs baseline --out <new-baseline> --config <config>`. Put baselines inside the project's excluded `.shoalrun` directory or outside the project. This includes earlier dirty/untracked files rather than comparing with Git HEAD. Retain the corresponding before-content/task diff with your harness; a baseline stores digests, not earlier text. For an existing rendering failure, reproduce its located finding before repairing it.
 
 Edit ordinary source files and required companions. Choose a page type and reviewed example for the reader's goal. Preserve stable IDs, routes, original `date` and access policy; set `updated` to the actual edit date. For a new page, use `shoalrun scaffold <template> -n <target> --config <config>` and resolve its prompts. Keep it draft until reviewed; snapshot validation renders affected drafts without changing their publication metadata. API materialization and recipe tasks have focused references/skills when needed.

package/skills/shoalrun-author/references/code-api-references.md

@@ -0,0 +1,15 @@
+# Code API reference authoring
+
+Read `guide.code-api-references` and `reference.code-api-references` from the installed package's bundled docs when present. Check installed-version support; the feature starts in 1.0.0. A source checkout also provides `CODE-REFERENCES.md` and a runnable `examples/code-references` project.
+
+Use `codeReferences` for a language library or SDK, and `apis` for OpenAPI HTTP endpoints. A converter writes the versioned snapshot; normal builds never invoke it. The optional Python adapter requires an explicitly prepared Python 3.11+ environment with its pinned requirements. Keep extraction roots narrow and don't enable runtime inspection or external discovery to make an unsupported package appear to work. Other languages can provide their own converter; don't claim a bundled Kotlin extractor.
+
+Run `shoalrun references check FILE`, inspect the snapshot's public symbols and prose, then configure the catalog. Snapshot descriptions are inert Markdown; MDX, project directives, relative links, and images aren't supported. Preserve exact symbol IDs and use explicit document IDs/slugs when public identities must survive a rename. Keep snapshots in the project and regenerate them after source changes.
+
+Choose `layout: symbols`, `classes`, or `modules` by reading needs. All retain individual symbol URLs. Add `singlePage` only when a complete reference is useful; configure its ID, slug, title, summary, and optional metadata, then link that ID in navigation. Group class or module pages in navigation instead of listing every symbol when a shorter menu is wanted.
+
+Preserve product/channel/version/language source bindings. Catalog and symbol metadata classify their content; a parent's feature requirements aren't inherited by children. Strict source classification also applies to the complete page. Pass the same profile through validation, build, and export. Check that private, restricted, or audience-excluded symbols don't reappear inside grouped or complete pages.
+
+Type links use explicit converter targets and remain within eligible catalog/publication scope. Keep unknown types unlinked. Required fields are distinct from nullable fields; show defaults as unevaluated expressions. Configure repository source links only with a real HTTPS base directory and intended release/commit; never invent a repository location.
+
+Review class/module and complete pages in HTML and Markdown. Check inline symbol links, retained individual URLs, narrow-screen table scrolling and keyboard focus, and content-export/PDF selection by ID where relevant. Reading references doesn't require JavaScript; Copy controls do. Extraction doesn't prove runtime behavior or execute examples.

package/skills/shoalrun-author/references/pdf-export.md

@@ -0,0 +1,15 @@
+# PDF export
+
+For print design, brand styling, and visual verification, read the [PDF skill](../../shoalrun-pdf/SKILL.md). Its print reference and stylesheet starter accompany the instructions; keep the complete skill folder when installing it.
+
+Check the installed CLI's `export --help` and supported output settings before configuring PDFs. Use `export --format pdf --document ID --out DIRECTORY` for one page; omit the document selector for a complete publication. Select exact product/channel/version/language coordinates when more than one publication is enabled. Pass the same customer profile as the site. PDF selection uses the target's contentFilter, otherwise the site's filter; ordinary HTML/Markdown application exports retain their independent filter behavior.
+
+Set shared print settings under outputs.pdf and per-target overrides under exports.<target>.pdf. Local stylesheet/font/logo paths resolve relative to their declaring configuration. Register licensed local fonts explicitly; custom CSS cannot import files or load URLs. Body CSS doesn't style Chromium's separate header/footer templates. Their escaped text supports {title}, {page}, and {pages}. The TOC is linked without printed page numbers. Bookmarks/tagging need actual PDF inspection; don't infer accessibility certification.
+
+The page action is disabled by default. An enabled outputs.html.pdf mapping defaults to mode:print for static sites: the browser creates a separate branded view and opens its print dialog, with no generated page PDFs or extra print documents. Configure its label, placement before/after Markdown actions, include/exclude IDs, and optional named style target. Shared outputs.pdf styling and assets serve all print views; only a target's PDF settings apply, never its content selection. Page frontmatter pdf:false suppresses the action. Native browser printing remains a fallback using website print CSS. Keep full-manual CLI export and its published download optional.
+
+Explicit mode:endpoint prepares private inputs for on-demand generation through a Node host with Chromium. Optional style names an export target's pdf mapping; only its styling applies, never its page/publication/filter selection. Vercel supports browser printing and rejects endpoint mode. Never publish pdf-runtime.json or __shoalrun/pdf-data through a generic static server. A custom handler must use the same authentication boundary as the site. Audience/profile selection isn't visitor authorization.
+
+Generation requires an installed Chrome/Chromium executable through SHOALRUN_PDF_BROWSER or outputs.pdf.executablePath. It runs offline with JavaScript disabled and the browser sandbox retained. Missing assets, remote images, missing browser, or rendering failures must be reported; don't substitute a print dialog for a promised PDF download. Preserve existing exports on failure.
+
+Verify a page and full publication, their selection/order, excluded content, links, fonts, bookmarks, page breaks, long code/tables, and static component fallbacks. Inspect rendered PDF pages as well as extracted text. Keep PDF manifests separate from content REST representation manifests. Enabling an action doesn't authorize deploying internal/customer PDFs publicly.

package/skills/shoalrun-brand/SKILL.md

@@ -45,6 +45,8 @@ Check every requested color mode. Normal text needs at least 4.5:1 contrast; lar
 
 ## Validate and preview
 
+For branded PDF output, read the [PDF skill](../shoalrun-pdf/SKILL.md). Configure print styling separately from website styling, retain the intended publication/profile selection, and inspect actual rendered PDF pages. A passing HTML build doesn't verify PDF appearance.
+
 Validate against the baseline with `shoalrun docs validate --baseline .shoalrun/brand-before.json --config docs.config.yaml`, including the selected profile when applicable. Read the report's findings and coverage. Reuse its captured output with `shoalrun docs preview REPORT --port 0`, or follow the project's required build workflow and serve that output. Rebuild when styles, configuration, or assets change.
 
 Inspect a landing page and a representative article at desktop and mobile widths. Check font and image loading, overflow, keyboard navigation, dropdown destinations, and search interactions. Confirm HTML navigation and Markdown twins retain the documentation's meaning. A successful build doesn't establish visual correctness; state any browser checks that couldn't run.