@eightmedia/flightcheck 0.1.0 → 1.0.1

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog
 
-## [0.1.0] — 2026-10-27
+## [1.0.1] — 2026-10-28
+
+### Added
+
+- Reports record `flightcheckVersion` and CLI `flags` in `*-report.json` and the Markdown header
+
+## [1.0.0] — 2026-10-27
 
 ### Added
 
@@ -9,6 +15,7 @@
   Markdown rendered from the same model
 - Crawl + Tier 1 checks: security headers, DNS, robots.txt, sitemap, agent readiness
 - CLI binaries: `flightcheck`, `flightcheck-analyze`
+- README guidance for installing and running inside a Node.js project
 
 ### Changed
 

package/README.md

@@ -12,18 +12,77 @@ mismatches, exposed secrets, and more. Every run produces:
 
 ## Install
 
+In a Node.js project (recommended):
+
 ```bash
-pnpm add -g @eightmedia/flightcheck
-# or: npm install -g @eightmedia/flightcheck
+npm install @eightmedia/flightcheck
+# or: pnpm add @eightmedia/flightcheck
+# or: yarn add @eightmedia/flightcheck
+```
+
+Requires Node.js 22+. The package is ESM-only (`"type": "module"`).
+
+## Use in a Node project
+
+### CLI via npm scripts
+
+Add scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "flightcheck": "flightcheck",
+    "flightcheck:analyze": "flightcheck-analyze"
+  }
+}
 ```
 
-Or run without installing:
+Then:
 
 ```bash
-pnpm dlx @eightmedia/flightcheck https://example.com
-# or: npx @eightmedia/flightcheck https://example.com
+npm run flightcheck -- https://example.com
+npm run flightcheck:analyze -- ./flightcheck/20260618.1413-example.com-raw.json
+```
+
+Or call the binaries directly after install:
+
+```bash
+npx flightcheck https://example.com
+npx flightcheck-analyze ./flightcheck/20260618.1413-example.com-raw.json
+```
+
+Without adding it to a project:
+
+```bash
+npx @eightmedia/flightcheck https://example.com
+```
+
+### Programmatic API
+
+```js
+import { runChecks } from "@eightmedia/flightcheck";
+
+const { outputs, results } = await runChecks({
+  startUrl: "https://example.com",
+});
+
+const report = outputs.analyze?.report;
+console.log(report?.analysis.pagesAnalyzed, report?.findings.length);
+
+// Write paths (when analyze ran):
+console.log(outputs.analyze?.reportPath);
+console.log(outputs.analyze?.reportJsonPath);
 ```
 
+Lower-level entry points:
+
+```js
+import { runCrawlCheck, runAnalyzeCheck } from "@eightmedia/flightcheck";
+import { listChecks } from "@eightmedia/flightcheck/checks";
+```
+
+See [docs/check-api.md](docs/check-api.md) for the modular check API.
+
 ## How it works
 
 1. **Crawl & checks** — pages are scanned and modular checks run (SEO, a11y, security,
@@ -45,8 +104,8 @@ See [docs/analyze.md](docs/analyze.md) for the report schema.
 ## Quick start
 
 ```bash
-pnpm add -D @eightmedia/flightcheck
-pnpm exec flightcheck https://example.com
+npm install @eightmedia/flightcheck
+npx flightcheck https://example.com
 ```
 
 This writes timestamped files in `./flightcheck/`, for example:
@@ -63,7 +122,7 @@ redirect domains. Use `--checks` for a subset, or `--json-only` for crawl JSON o
 Re-analyze an existing crawl without re-crawling:
 
 ```bash
-pnpm exec flightcheck-analyze ./flightcheck/20260618.1413-example.com-raw.json
+npx flightcheck-analyze ./flightcheck/20260618.1413-example.com-raw.json
 ```
 
 ## Documentation
@@ -77,19 +136,6 @@ pnpm exec flightcheck-analyze ./flightcheck/20260618.1413-example.com-raw.json
 - [QC checks plan](docs/qc-checks-plan.md) — roadmap
 - [Docs index](docs/index.md) · [Changelog](CHANGELOG.md)
 
-## Programmatic API
-
-```typescript
-import { runChecks } from "@eightmedia/flightcheck";
-
-const { outputs } = await runChecks({
-  startUrl: "https://example.com",
-});
-
-const report = outputs.analyze?.report;
-// report.analysis.stack, report.findings, …
-```
-
 ## Development
 
 ```bash

package/dist/analyze/structuredReport.d.ts

@@ -46,7 +46,12 @@ export type FlightcheckReportAnalysis = {
     reviewPages: ReportReviewPage[];
 };
 export type FlightcheckReport = {
+    /** Report JSON schema version (not the npm package version). */
     version: typeof FLIGHTCHECK_REPORT_VERSION;
+    /** npm package version of Flightcheck that produced this report. */
+    flightcheckVersion: string;
+    /** CLI argv flags used for this run (after node/script); empty when programmatic without flags. */
+    flags: string[];
     generatedAt: string;
     source: string;
     redirectOnly: boolean;
@@ -55,6 +60,8 @@ export type FlightcheckReport = {
 };
 export type BuildStructuredReportOptions = BuildMarkdownOptions & {
     generatedAt?: string;
+    flightcheckVersion?: string;
+    flags?: string[];
 };
 export declare function buildStructuredReport(sourcePath: string, records: ReportRecord[], tier1?: Tier1ReportData, options?: BuildStructuredReportOptions): Promise<FlightcheckReport>;
 /** Human-friendly Markdown rendered from the structured report (single source of truth). */

package/dist/analyze/structuredReport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"structuredReport.d.ts","sourceRoot":"","sources":["../../src/analyze/structuredReport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAEL,KAAK,oBAAoB,EAEzB,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,eAAO,MAAM,0BAA0B,EAAG,CAAU,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG,kBAAkB,CAAC;AACjD,MAAM,MAAM,eAAe,GACvB,OAAO,GACP,KAAK,GACL,MAAM,GACN,gBAAgB,GAChB,UAAU,GACV,aAAa,CAAC;AAClB,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,eAAe,CAAC;IAC1B,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAC/C,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,GAAG,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAC9C,QAAQ,CAAC,EAAE;QACT,GAAG,EAAE,MAAM,CAAC;QACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,WAAW,EAAE,gBAAgB,EAAE,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,EAAE,OAAO,0BAA0B,CAAC;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,yBAAyB,CAAC;IACpC,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B,CAAC;AAidF,MAAM,MAAM,4BAA4B,GAAG,oBAAoB,GAAG;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAsB,qBAAqB,CACzC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,YAAY,EAAE,EACvB,KAAK,GAAE,eAAoB,EAC3B,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,iBAAiB,CAAC,CAW5B;AAgCD,4FAA4F;AAC5F,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAqFtE"}
+{"version":3,"file":"structuredReport.d.ts","sourceRoot":"","sources":["../../src/analyze/structuredReport.ts"],"names":[],"mappings":"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"}

package/dist/analyze/structuredReport.js

@@ -1,3 +1,4 @@
+import { formatCliFlags, getPackageVersion } from "../version.js";
 import { buildReportAnalysis, } from "./report.js";
 export const FLIGHTCHECK_REPORT_VERSION = 1;
 const A11Y_IDS = new Set([
@@ -409,6 +410,8 @@ export async function buildStructuredReport(sourcePath, records, tier1 = {}, opt
     const findings = buildFindings(analysis, tier1);
     return {
         version: FLIGHTCHECK_REPORT_VERSION,
+        flightcheckVersion: options.flightcheckVersion ?? getPackageVersion(),
+        flags: options.flags ?? [],
         generatedAt: options.generatedAt ?? new Date().toISOString(),
         source: sourcePath,
         redirectOnly: analysis.redirectOnly,
@@ -457,6 +460,8 @@ export function renderReportMarkdown(report) {
         "# Flightcheck report",
         "",
         `Generated: ${report.generatedAt}`,
+        `Flightcheck: ${report.flightcheckVersion}`,
+        `Flags: \`${formatCliFlags(report.flags)}\``,
         `Source: \`${report.source}\``,
         "",
         "## At a glance",

package/dist/analyze.js

@@ -3,15 +3,19 @@ import { basename, resolve } from "node:path";
 import { Command } from "commander";
 import { runAnalyzeCheck } from "./checks/analyze.js";
 import { defaultReportPathForInput } from "./crawler/outputPaths.js";
+import { cliFlagsFromArgv, getPackageVersion } from "./version.js";
 async function main() {
     const sanitizedArgv = [...process.argv];
     const separatorIndex = sanitizedArgv.indexOf("--");
     if (separatorIndex >= 2) {
         sanitizedArgv.splice(separatorIndex, 1);
     }
+    const runFlags = cliFlagsFromArgv(sanitizedArgv);
+    const flightcheckVersion = getPackageVersion();
     const program = new Command();
     program
         .name("flightcheck-analyze")
+        .version(flightcheckVersion)
         .description("Analyze crawl JSON and generate structured JSON + Markdown reports.")
         .argument("<input>", "Input JSON report file path")
         .option("--output <file>", "Output Markdown file path")
@@ -22,6 +26,8 @@ async function main() {
             inputPath,
             reportPath: resolve(options.output ?? defaultReportPathForInput(inputPath)),
             errorsOnly: options.errorsOnly,
+            flightcheckVersion,
+            flags: runFlags,
         });
         process.stdout.write(`${JSON.stringify({
             message: "Report generated",

package/dist/checks/analyze.d.ts

@@ -10,6 +10,10 @@ export type AnalyzeCheckOptions = {
     writeReport?: boolean;
     redirectOnly?: boolean;
     tier1?: Tier1ReportData;
+    /** npm package version recorded in the report (defaults to installed package). */
+    flightcheckVersion?: string;
+    /** CLI flags recorded in the report. */
+    flags?: string[];
 };
 export declare function runAnalyzeCheck(options: AnalyzeCheckOptions): Promise<AnalyzeCheckResult>;
 //# sourceMappingURL=analyze.d.ts.map

package/dist/checks/analyze.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/checks/analyze.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAW5F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB,CAAC;AAuBF,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA4C/F"}
+{"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../../src/checks/analyze.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAW5F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AAuBF,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA8C/F"}

package/dist/checks/analyze.js

@@ -37,6 +37,8 @@ export async function runAnalyzeCheck(options) {
     const report = await buildStructuredReport(inputPath, records, options.tier1, {
         redirectOnly,
         stackProfile,
+        flightcheckVersion: options.flightcheckVersion,
+        flags: options.flags,
     });
     // errorsOnly currently filters only the Markdown presentation of page-level noise;
     // the structured JSON keeps the full finding set for machine consumers.

package/dist/cli.js

@@ -5,15 +5,19 @@ import { DEFAULT_CHECK_IDS } from "./checks/types.js";
 import { DEFAULT_BURST_DELAY_MS, DEFAULT_CONCURRENCY, DEFAULT_DELAY_MS, DEFAULT_MAX_PAGES, DEFAULT_TIMEOUT_MS, } from "./crawler/defaults.js";
 import { buildDefaultOutputPaths } from "./crawler/outputPaths.js";
 import { isHttpUrl, normalizeUrl, parseExcludePatterns } from "./crawler/urlUtils.js";
+import { cliFlagsFromArgv, getPackageVersion } from "./version.js";
 async function main() {
     const sanitizedArgv = [...process.argv];
     const separatorIndex = sanitizedArgv.indexOf("--");
     if (separatorIndex >= 2) {
         sanitizedArgv.splice(separatorIndex, 1);
     }
+    const runFlags = cliFlagsFromArgv(sanitizedArgv);
+    const flightcheckVersion = getPackageVersion();
     const program = new Command();
     program
         .name("flightcheck")
+        .version(flightcheckVersion)
         .description("Crawl a website and generate crawl JSON plus structured report JSON/Markdown.")
         .argument("<startUrl>", "Start URL for the crawl")
         .option("--output <file>", "Output crawl JSON file path")
@@ -79,6 +83,8 @@ async function main() {
                 reportJsonPath: defaultPaths.reportJson,
                 errorsOnly,
                 siteUrl: normalizedStartUrl,
+                flightcheckVersion,
+                flags: runFlags,
             },
         });
         const crawlResult = outputs.crawl;

package/dist/version.d.ts

@@ -0,0 +1,9 @@
+/** Installed package version from package.json (works from src/ and dist/). */
+export declare function getPackageVersion(): string;
+/**
+ * CLI flags as passed on the command line (everything after node + script path).
+ * Example: `["https://example.com", "--quiet", "--max-pages", "50"]`
+ */
+export declare function cliFlagsFromArgv(argv?: string[]): string[];
+export declare function formatCliFlags(flags: string[]): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,wBAAgB,iBAAiB,IAAI,MAAM,CAO1C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,MAAM,EAAE,CAExE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAGtD"}

package/dist/version.js

@@ -0,0 +1,24 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+/** Installed package version from package.json (works from src/ and dist/). */
+export function getPackageVersion() {
+    try {
+        const pkg = require("../package.json");
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * CLI flags as passed on the command line (everything after node + script path).
+ * Example: `["https://example.com", "--quiet", "--max-pages", "50"]`
+ */
+export function cliFlagsFromArgv(argv = process.argv) {
+    return argv.slice(2);
+}
+export function formatCliFlags(flags) {
+    if (flags.length === 0)
+        return "(defaults)";
+    return flags.map((flag) => (/\s/.test(flag) ? JSON.stringify(flag) : flag)).join(" ");
+}

package/docs/agent-fixes.md

@@ -3,15 +3,13 @@
 **Status:** deprecated. Analyze no longer writes `*-fix-manifest.json` or
 `*-agent-jobs/`.
 
-Use the structured report instead:
-
-- [Analyze reports](./analyze.md) — `*-report.json` + `*-report.md`
-- [Design](./superpowers/specs/2026-10-27-structured-report-design.md)
+Use the structured report instead: [Analyze reports](./analyze.md)
+(`*-report.json` + `*-report.md`).
 
 The previous agent-jobs / fix-manifest workflow (work packages, `prompt.md` per
-package, `flightcheck-orchestrate`) remains in the repo for transitional imports
-but is not part of the default output. Prefer building any new agent automation
-on `findings[]` in `*-report.json`.
+package, orchestrate helpers) may still exist in the source tree for reference, but
+it is not part of the published package or default CLI output. Prefer building any
+new agent automation on `findings[]` in `*-report.json`.
 
 Stack detection still feeds the report `analysis.stack` block. See
 [stack.md](./stack.md).

package/docs/agent-ready.md

@@ -25,8 +25,8 @@ robots.txt existence and sitemaps remain in the existing `robots-txt` and `sitem
 - Network runner: `runAgentReadyCheck()` — parallel fetches of robots, llms.txt, homepage
   (HTML + markdown Accept), and well-known endpoints
 - Wave 1 (parallel with crawl / DNS / headers / robots)
-- Report section: `## Agent readiness` via `buildAgentReadySection()` in `reportTier1.ts`
-- Fix package: `agent-ready` → `prompts/fix/agent-ready.md`
+- Report: issues land in `findings[]` (`category: "infra"`) in `*-report.json`; the
+  Markdown report lists them under **Findings**
 
 ## CLI
 

package/docs/analyze.md

@@ -36,6 +36,8 @@ Without `--output`, paths are derived from the input: `-raw.json` becomes
 ```json
 {
   "version": 1,
+  "flightcheckVersion": "1.0.1",
+  "flags": ["https://example.com", "--quiet"],
   "generatedAt": "2026-10-27T12:00:00.000Z",
   "source": "./flightcheck/example-raw.json",
   "redirectOnly": false,
@@ -86,18 +88,26 @@ includes metadata so consumers can filter or regroup.
 | `template` | Present when `scope` is `template` |
 | `urls` / `count` | Affected pages when relevant |
 
+Header fields:
+
+| Field | Meaning |
+| --- | --- |
+| `version` | Report JSON schema version |
+| `flightcheckVersion` | npm package version that produced the report |
+| `flags` | CLI arguments used for this run (empty when not invoked via CLI) |
+
 ### `*-report.md`
 
 Generated from the JSON. Structure:
 
-1. **At a glance** — page counts and finding totals
-2. **Stack / DNS / redirect** — factual context when available
-3. **Findings** — grouped by severity for reading order, with plain-language titles
+1. Header — generated time, Flightcheck version, flags, source path
+2. **At a glance** — page counts and finding totals
+3. **Stack / DNS / redirect** — factual context when available
+4. **Findings** — grouped by severity for reading order, with plain-language titles
 
 ## Notes
 
 - The script validates crawl input against the expected flightcheck report schema.
 - On schema errors, the script stops with a clear error message.
 - Fix-manifest and agent-jobs output are no longer generated. Prefer `*-report.json`
-  for machine consumers. See the design note in
-  [superpowers/specs/2026-10-27-structured-report-design.md](./superpowers/specs/2026-10-27-structured-report-design.md).
+  for machine consumers.

package/docs/index.md

@@ -11,14 +11,11 @@
 - [QC checks plan](./qc-checks-plan.md)
 - [Agent fixes (deprecated)](./agent-fixes.md)
 
-## Specs
-
-- [Structured report](./superpowers/specs/2026-10-27-structured-report-design.md)
-
 ## Changelog
 
 - Package releases: [CHANGELOG.md](../CHANGELOG.md)
 - Branch notes: [changelog/](./changelog/)
+  - [2026-10-28 — report-version-flags](./changelog/2026-10-28--report-version-flags.md)
   - [2026-10-27 — npm-public-package](./changelog/2026-10-27--npm-public-package.md)
   - [2026-10-27 — structured-report-json](./changelog/2026-10-27--structured-report-json.md)
   - [2026-09-28 — agent-ready-check](./changelog/2026-09-28--agent-ready-check.md)

package/docs/qc-checks-plan.md

@@ -6,7 +6,7 @@ image alt text, broken links, accessibility, security headers, DNS, and optional
 performance auditing.
 
 **Status:** in progress — Phase 1 shipped, Phase 2 mostly shipped  
-**Last updated:** 2026-09-28
+**Last updated:** 2026-10-27
 
 ---
 
@@ -18,8 +18,9 @@ Add the checks below as modular, exportable functions (see `docs/check-api.md`)
 - Run independently via API endpoints in a consuming project
 - Execute in parallel where dependencies allow
 
-Each check produces structured JSON output and feeds into the Markdown TODO report via
-`analyze`.
+Each check produces structured JSON output and feeds into analyze, which writes
+`*-report.json` (`analysis` + `findings[]`) and a plain-language `*-report.md` from that
+model.
 
 ---
 
@@ -126,7 +127,7 @@ Wave 3 (optional, after crawl):
   performance (Lighthouse or PageSpeed API on same URL sample)
 
 Wave 4:
-  analyze (merges all check outputs into TODO report)
+  analyze (merges check outputs into *-report.json + *-report.md)
 ```
 
 Wave 2 and 3 share a URL sampler (`src/checks/sampleUrls.ts`):

package/docs/stack.md

@@ -1,7 +1,7 @@
 # Stack detection
 
-Flightcheck fingerprints the technology stack of a crawled site for handover docs and agent
-routing. Results appear in `analysis.stack` in `*-report.json` and under **Stack** in the Markdown report.
+Flightcheck fingerprints the technology stack of a crawled site for handover docs and tooling.
+Results appear in `analysis.stack` in `*-report.json` and under **Stack** in the Markdown report.
 
 Detection uses **curated flightcheck rules** in `src/crawler/stackDetect.ts` — not the full
 Wappalyzer / webappanalyzer database. Rules only fire on strong signals (script URLs, distinctive
@@ -49,26 +49,19 @@ during analyze.
 
 ## Analyze output
 
-```markdown
-## Stack
-
-### Platform
-- **Node.js** (medium, site-wide)
-  - implied by Next.js
-
-### Framework
-- **Next.js** (high, site-wide)
-  - html: `data-next-head`
+In `*-report.json`, stack detections live under `analysis.stack` (name, categories,
+confidence, evidence, pageCount). The Markdown report renders them as:
 
-### Hosting
-- **Vercel** (high, origin)
-  - header: x-vercel-id
+```markdown
+### Stack
 
-### Tracking (flightcheck crawl)
-- Tag managers:
-  - Google Tag Manager: `GTM-XXXX`
+- **Next.js** (JavaScript frameworks, high) — Next.js runtime markers in HTML
+- **Vercel** (Hosting, high) — header: x-vercel-id
 ```
 
+Tracking IDs from the crawl are still aggregated in the stack profile for tooling; the
+human Markdown report focuses on stack detections in the **At a glance** section.
+
 Run with infra checks for the fullest picture:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eightmedia/flightcheck",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Pre-launch website audit: crawl SEO/a11y/security checks and emit structured JSON + Markdown reports.",
   "license": "GPL-3.0",
   "type": "module",