@dailephd/my-dev-kit-lab 0.4.5 → 0.4.6

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to my-dev-kit-lab are documented here.
 
+## [Unreleased]
+
+## [0.4.6] - 2026-08-29
+
+Installed-package CLI and runtime-boundary correction. `@dailephd/my-dev-kit-lab` now ships a supported, cross-platform installed CLI (`my-dev-kit-lab`) alongside the existing contributor npm scripts.
+
+- Added a compiled, cross-platform installed CLI router (`dist/scripts/cli.js`, `src/cli/runLabCli.ts`) exposing `my-dev-kit-lab --help`/`--version`, `security validate`, `audit`, the `experiment` family (`list`/`describe`/`run`/`controlled`), `report render`, `plots generate`, `gallery build`, and `demo final`, plus the historical direct final-demo invocation form for backward compatibility. A global `--workspace <path>` option is supported before any subcommand.
+- Added a `LabExecutionContext` runtime foundation (`src/runtime/`) distinguishing `invocationCwd`, read-only `packageRoot` (discovered independent of `process.cwd()`), writable `workspaceRoot` (default `<home>/.my-dev-kit-lab`, overridable with `--workspace`), `resourceRoot`, and the separately resolved inspected target root, plus cwd-independent, containment-checked package-resource resolution.
+- `security validate`, `audit`, and `experiment` npm scripts now delegate to shared `src/commands/` owners also used by the installed CLI, so both surfaces run the same implementation. Installed `audit`/`security validate` default implicit report output under the writable workspace instead of the package root; installed `experiment run`'s implicit output is under the workspace's `lab-output/experiments/` tree. Explicit output paths and all target-resolution semantics are unchanged.
+- Added a permanent packed-tarball installation/execution acceptance gate (`npm run verify:packed-package`): builds, runs a real `npm pack`, installs the exact tarball into a clean temporary consumer project, executes the installed binary, and verifies default/explicit workspace output and target/installed-package immutability via recursive SHA-256 snapshot comparison.
+- Fixed an installed-runtime defect the acceptance gate surfaced: the TypeScript/JavaScript audit source-facts analyzer imported the `typescript` devDependency eagerly at module load, so even `--help` required it in a clean install; it now loads lazily, only when a source file is actually analyzed. Detector output is unchanged.
+- Reconciled the npm package `files` allowlist against proven installed-runtime requirements: narrowed `dist/scripts/` to the two files the installed CLI and legacy bin target need, narrowed `examples/` to the one file an installed command reads by default, and removed `tests/fixtures/` (developer/test-only, not read by any installed command). `benchmarks/` and `docs/METRICS.md` remain packaged.
+- Raised `engines.node` to `>=24`. Standardized GitHub Actions CI on Node `24` and `latest` across Ubuntu/macOS/Windows, and switched the pre-release readiness workflow from a hard-coded Node version to Node `latest`; both workflows run the packed-package acceptance gate.
+- Resolved a transitive devDependency vulnerability (nanoid, GHSA-2v37-7h3g-55p8) via a lockfile-only update; the published runtime dependency tree was unaffected throughout.
+- No security check, security verdict rule, audit detector, Android behavior, experiment scoring, report schema, or existing CLI syntax changed.
+
 ## [0.4.5] - 2026-08-01
 
 Context-integrity validation for the published my-dev-kit v1.10.4 and my-dev-kit-orchestrator v1.2.3 contracts.

package/README.md

@@ -4,7 +4,9 @@ my-dev-kit-lab is the experiment, audit, and evidence companion for [my-dev-kit]
 
 my-dev-kit provides local repository indexing and graph-guided retrieval. my-dev-kit-lab supplies the controlled benchmarks, agent adapters, metrics, security checks, and reports needed to evaluate when that retrieval is useful. Results are evidence for a specific target and configuration; they do not guarantee token savings or security.
 
-The latest published release is v0.4.5 (context-integrity validation), compatible with published `@dailephd/my-dev-kit@1.10.4` and `@dailephd/my-dev-kit-orchestrator@1.2.3`. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md).
+The latest published release is v0.4.6 (installed-package CLI and runtime-boundary correction), compatible with published `@dailephd/my-dev-kit@1.10.4` and `@dailephd/my-dev-kit-orchestrator@1.2.3`. See [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md).
+
+v0.4.6 adds a supported `my-dev-kit-lab` installed CLI router (`--help`, `--version`, `security validate`, `audit`, the `experiment` family, `report render`, `plots generate`, `gallery build`, `demo final`, and the historical direct final-demo invocation form), a writable lab workspace model kept separate from the installed package and the inspected target, and a permanent packed-tarball installation/execution acceptance gate (`npm run verify:packed-package`). See [docs/ROADMAP.md](docs/ROADMAP.md) and [docs/CURRENT_STATE.md](docs/CURRENT_STATE.md) for status detail and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the runtime path model. The "Installed CLI" section below documents the shipped command surface; the source-checkout `npm run` workflow in Quickstart remains available for contributors.
 
 ## Current capabilities
 
@@ -17,7 +19,39 @@ The latest published release is v0.4.5 (context-integrity validation), compatibl
 - **Evaluate the producer-readiness bridge (v0.4.4):** optionally extend `combined-bounded-stage-context` with the frozen my-dev-kit-orchestrator supplemental implementation/test-context packet and retrieval-report documents plus an observed readiness result, all supplied programmatically (there is no CLI flag), to measure owner, allocation, truncation-cause, supplemental/raw agreement, readiness-agreement, and criticality-overlay evidence without reimplementing upstream owner-selection, allocation, producer-parity, or readiness policy.
 - **Evaluate context integrity (v0.4.5):** compare condition-aware producer evidence from my-dev-kit v1.10.4 (role condition coverage, allocation/spillover, required-evidence-loss) against my-dev-kit-orchestrator v1.2.3 run-integrity evidence (run-integrity gate, judge integrity, final-report eligibility, artifact lifecycle state), reporting agreement or contradiction between them rather than re-deriving a verdict. Evaluation runs against a frozen, hash-verified regression fixture pair — a byte-exact real historical failed run and a hand-distilled corrected-replay counterpart representing the same validated contracts — and is programmatic/test-driven only. `npm run report:context-integrity-smoke` renders both fixtures' reports for manual inspection; it takes no arguments and is a developer convenience, not a configurable evaluation CLI.
 
-## Quickstart
+## Installed CLI
+
+Installing or invoking the package (for example via `npm install -g @dailephd/my-dev-kit-lab` or `npx @dailephd/my-dev-kit-lab@<version>`) exposes one `my-dev-kit-lab` binary. Users do not need to clone this repository to use these commands. The installed CLI requires Node `>=24`.
+
+```
+my-dev-kit-lab --help
+my-dev-kit-lab --version
+
+my-dev-kit-lab security validate [options]
+my-dev-kit-lab audit [options]
+
+my-dev-kit-lab experiment list
+my-dev-kit-lab experiment describe --experiment <id>
+my-dev-kit-lab experiment run --experiment <id> [options]
+my-dev-kit-lab experiment controlled [options]
+
+my-dev-kit-lab report render [options]
+my-dev-kit-lab plots generate [options]
+my-dev-kit-lab gallery build [options]
+my-dev-kit-lab demo final [options]
+```
+
+A global `--workspace <path>` option, placed before the command, selects the writable lab workspace. The default workspace, used when `--workspace` is omitted, is `<home>/.my-dev-kit-lab`. Generated reports and experiment output are written under the workspace by default, never under the installed package directory or an inspected `--target` project. Explicit output paths (`--out`, and similar flags) keep their existing resolution behavior and are never redirected under the workspace.
+
+The historical direct final-demo invocation form — the same flags `demo final` accepts, without the `demo final` prefix — continues to work for backward compatibility.
+
+Low-level developer helpers (`security:deps`, `security:package`, `security:codeql`, `security:semgrep`, fuzz smoke, visualization demos, build/test/verify) are not part of the installed CLI. They remain source-checkout contributor workflows; see below.
+
+See [docs/COMMANDS.md](docs/COMMANDS.md) for full command syntax and flags.
+
+## Quickstart (contributor / source-checkout workflow)
+
+The commands in this section run from a cloned repository checkout and are the contributor/development workflow. They are not required to use the installed CLI documented above.
 
 ### Install
 
@@ -174,7 +208,7 @@ See [docs/METRICS.md](docs/METRICS.md) for full metric definitions.
 
 ## Security validation
 
-`npm run security:validate` is the standalone security-validation command. It checks local CLI/package boundaries and can inspect another local project with `--target <path>`. The generic audit command can reuse those results through `--types security`, but it does not replace the standalone validator or its reports.
+`npm run security:validate` (contributor/source-checkout) and `my-dev-kit-lab security validate` (installed CLI) both call the same standalone security-validation command owner. It checks local CLI/package boundaries and can inspect another local project with `--target <path>`. The generic audit command can reuse those results through `--types security`, but it does not replace the standalone validator or its reports.
 
 Android validation uses `--profile android`. Its default path is static and non-destructive: it starts zero Gradle processes, zero external tools, and zero network operations. Only confirmed `SecurityFinding` records can become audit issues; Android `CandidateEvidence` remains review-only evidence.
 

package/dist/scripts/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { runLabCli } from "../src/cli/index.js";
+try {
+    process.exitCode = await runLabCli(process.argv.slice(2));
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/src/audits/core/typescriptJavaScriptAnalyzer.js

@@ -1,4 +1,3 @@
-import ts from "typescript";
 // ---------------------------------------------------------------------------
 // v0.3.1 Batch 3 -- TypeScript/JavaScript source analyzer.
 //
@@ -36,7 +35,25 @@ export const TYPESCRIPT_JAVASCRIPT_ANALYZER = {
     supportedExtensions: SUPPORTED_EXTENSIONS,
     analyzeFile,
 };
-function analyzeFile(input) {
+// v0.4.6 Batch 5 -- the `typescript` package is a devDependency, not a
+// runtime dependency: an installed my-dev-kit-lab consumer does not have it.
+// The compiler API is loaded lazily (once, memoized) only when a file is
+// actually analyzed, rather than imported at module scope, so merely
+// loading this module (which happens on every CLI invocation, since the
+// language analyzer registry is wired in unconditionally) never requires
+// `typescript` to be present. Only the *type* import above is needed at the
+// top level -- type-only imports are erased entirely at compile time.
+let cachedTypeScriptModule;
+async function loadTypeScript() {
+    if (!cachedTypeScriptModule) {
+        const imported = await import("typescript");
+        cachedTypeScriptModule =
+            imported.default ??
+                imported;
+    }
+    return cachedTypeScriptModule;
+}
+async function analyzeFile(input) {
     const { relativePath, language, role, content, inventoryEntry } = input;
     if (Buffer.byteLength(content, "utf8") > MAX_ANALYZABLE_BYTES) {
         return {
@@ -61,17 +78,18 @@ function analyzeFile(input) {
             ],
         };
     }
-    const scriptKind = resolveScriptKind(inventoryEntry.extension);
+    const ts = await loadTypeScript();
+    const scriptKind = resolveScriptKind(ts, inventoryEntry.extension);
     const sourceFile = ts.createSourceFile(relativePath, content, ts.ScriptTarget.Latest, true, scriptKind);
-    const diagnostics = getSyntaxDiagnostics(relativePath, sourceFile);
+    const diagnostics = getSyntaxDiagnostics(ts, relativePath, sourceFile);
     const imports = [];
     const exports = [];
     const declarations = [];
     const references = [];
     const lineOf = (node) => sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
     function pushDeclaration(node, name, kind) {
-        const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword);
-        const isDefault = hasModifier(node, ts.SyntaxKind.DefaultKeyword);
+        const isExported = hasModifier(ts, node, ts.SyntaxKind.ExportKeyword);
+        const isDefault = hasModifier(ts, node, ts.SyntaxKind.DefaultKeyword);
         if (name) {
             declarations.push({ name, kind, exported: isExported, line: lineOf(node) });
         }
@@ -141,7 +159,7 @@ function analyzeFile(input) {
         exports.push({ name, kind: "default", line: lineOf(node) });
     }
     function handleVariableStatement(node) {
-        const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword);
+        const isExported = hasModifier(ts, node, ts.SyntaxKind.ExportKeyword);
         const isConst = (node.declarationList.flags & ts.NodeFlags.Const) !== 0;
         for (const decl of node.declarationList.declarations) {
             // Destructuring patterns (`const { a, b } = x`) are conservatively
@@ -247,7 +265,7 @@ function analyzeFile(input) {
         diagnostics,
     };
 }
-function resolveScriptKind(extension) {
+function resolveScriptKind(ts, extension) {
     switch (extension) {
         case ".tsx":
             return ts.ScriptKind.TSX;
@@ -264,7 +282,7 @@ function resolveScriptKind(extension) {
             return ts.ScriptKind.TS;
     }
 }
-function hasModifier(node, kind) {
+function hasModifier(ts, node, kind) {
     if (!ts.canHaveModifiers(node))
         return false;
     const modifiers = ts.getModifiers(node);
@@ -280,11 +298,11 @@ function hasModifier(node, kind) {
 // transpileModule() over this repo's own ~375 TS/JS files, which matters
 // because collectSourceFacts.ts calls this analyzer once per eligible file
 // on every audit run (including this repo's own self-audit).
-function getSyntaxDiagnostics(relativePath, sourceFile) {
+function getSyntaxDiagnostics(ts, relativePath, sourceFile) {
     const parseDiagnostics = sourceFile.parseDiagnostics ?? [];
-    return parseDiagnostics.map((diagnostic) => toSourceFactDiagnostic(relativePath, diagnostic));
+    return parseDiagnostics.map((diagnostic) => toSourceFactDiagnostic(ts, relativePath, diagnostic));
 }
-function toSourceFactDiagnostic(relativePath, diagnostic) {
+function toSourceFactDiagnostic(ts, relativePath, diagnostic) {
     const message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n");
     const line = diagnostic.file && diagnostic.start !== undefined
         ? diagnostic.file.getLineAndCharacterOfPosition(diagnostic.start).line + 1

package/dist/src/cli/help.js

@@ -0,0 +1,300 @@
+export function renderTopLevelHelp() {
+    return [
+        "my-dev-kit-lab - benchmark, evidence, and evaluation companion for my-dev-kit.",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab --help",
+        "  my-dev-kit-lab --version",
+        "  my-dev-kit-lab [--workspace <path>] security validate [options]",
+        "  my-dev-kit-lab [--workspace <path>] audit [options]",
+        "  my-dev-kit-lab [--workspace <path>] experiment list",
+        "  my-dev-kit-lab [--workspace <path>] experiment describe --experiment <id>",
+        "  my-dev-kit-lab [--workspace <path>] experiment run --experiment <id> [options]",
+        "  my-dev-kit-lab [--workspace <path>] experiment controlled --cases <path> --out <dir> [options]",
+        "  my-dev-kit-lab [--workspace <path>] report render --experiment <dir> --out <dir> [options]",
+        "  my-dev-kit-lab [--workspace <path>] plots generate --experiment <dir> --out <dir>",
+        "  my-dev-kit-lab [--workspace <path>] gallery build --out <dir> [options]",
+        "  my-dev-kit-lab demo final --cases <path> --out <dir> --kit-command <command> [options]",
+        "",
+        "Options:",
+        "  -h, --help           Show this help message",
+        "  -V, --version        Show the installed my-dev-kit-lab package version",
+        "  --workspace <path>   Writable my-dev-kit-lab workspace root (default: <home>/.my-dev-kit-lab).",
+        "                       Must appear before the command when used.",
+        "",
+        "Commands:",
+        "  security validate        Run security validation",
+        "  audit                    Run a project audit",
+        "  experiment list           List registered experiment plugins",
+        "  experiment describe       Describe a registered experiment plugin",
+        "  experiment run             Run a registered experiment plugin",
+        "  experiment controlled    Run a controlled context-strategy-comparison experiment",
+        "  report render             Render an experiment report from controlled-experiment artifacts",
+        "  plots generate             Generate experiment plot artifacts",
+        "  gallery build              Build a gallery manifest/index",
+        "  demo final                 Run the full final demo workflow",
+        "",
+        "Run \"my-dev-kit-lab <command> --help\" (or \"my-dev-kit-lab <family> <command> --help\") for details.",
+        "",
+        "Note: the historical direct invocation form (flags without \"demo final\", e.g.",
+        "\"my-dev-kit-lab --cases <path> --out <dir> --kit-command <command>\") remains",
+        "supported for backward compatibility."
+    ].join("\n");
+}
+export function renderDemoHelp() {
+    return [
+        "my-dev-kit-lab demo - demo command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab demo final [options]",
+        "  my-dev-kit-lab demo --help",
+        "",
+        "Commands:",
+        "  final   Run the full final demo. Run \"my-dev-kit-lab demo final --help\" for details."
+    ].join("\n");
+}
+export function renderFinalDemoHelp() {
+    return [
+        "my-dev-kit-lab demo final - run the full final demo workflow",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab demo final --cases <path> --out <dir> --kit-command <command> [options]",
+        "",
+        "Required:",
+        "  --cases <path>            Path to the evaluation cases file",
+        "  --out <dir>               Output directory for demo artifacts",
+        "  --kit-command <command>   Command used to invoke my-dev-kit for the visualization demos",
+        "",
+        "Options:",
+        "  --agents <list>                                    Comma-separated agent ids (default: fake-agent)",
+        "  --strategies <list>                                Comma-separated strategies: raw-full-file,my-dev-kit-guided (default: both)",
+        "  --complexities <list>                               Comma-separated complexity levels: short,medium,long,multi-step (default: short)",
+        "  --case <ids>                                       Comma-separated case ids to run",
+        "  --benchmark-project <ids>                          Comma-separated benchmark project ids to run",
+        "  --max-runs <n>                                     Maximum number of runs",
+        "  --screenshot / --no-screenshot                     Enable/disable report screenshot capture (default: disabled)",
+        "  --include-real-agents                              Allow real agent ids (codex, claude)",
+        "  --continue-on-failure / --no-continue-on-failure   Continue after a failed run (default: continue-on-failure)",
+        "  --timeout-ms <ms>                                  Per-run timeout in milliseconds",
+        "",
+        "The legacy direct invocation form (the same flags without a leading \"demo final\")",
+        "remains supported for backward compatibility."
+    ].join("\n");
+}
+export function renderExperimentHelp() {
+    return [
+        "my-dev-kit-lab experiment - experiment command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment list",
+        "  my-dev-kit-lab experiment describe --experiment <id>",
+        "  my-dev-kit-lab experiment run --experiment <id> [options]",
+        "  my-dev-kit-lab experiment controlled [options]",
+        "  my-dev-kit-lab experiment --help",
+        "",
+        "Commands:",
+        "  list         List registered experiment plugins.",
+        "               Run \"my-dev-kit-lab experiment list --help\" for details.",
+        "  describe     Describe a registered experiment plugin.",
+        "               Run \"my-dev-kit-lab experiment describe --help\" for details.",
+        "  run          Run a registered experiment plugin through the generic runner.",
+        "               Run \"my-dev-kit-lab experiment run --help\" for details.",
+        "  controlled   Run a controlled context-strategy-comparison experiment.",
+        "               Run \"my-dev-kit-lab experiment controlled --help\" for details."
+    ].join("\n");
+}
+export function renderExperimentListHelp() {
+    return [
+        "my-dev-kit-lab experiment list - list registered experiment plugins",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment list [--json]",
+        "",
+        "Options:",
+        "  --json   Print the experiment list as JSON instead of a human-readable summary"
+    ].join("\n");
+}
+export function renderExperimentDescribeHelp() {
+    return [
+        "my-dev-kit-lab experiment describe - describe a registered experiment plugin",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment describe --experiment <id> [--json]",
+        "",
+        "Required:",
+        "  --experiment <id>   Registered experiment plugin id (see \"my-dev-kit-lab experiment list\")",
+        "",
+        "Options:",
+        "  --json   Print the description as JSON instead of a human-readable summary"
+    ].join("\n");
+}
+export function renderExperimentRunHelp() {
+    return [
+        "my-dev-kit-lab experiment run - run a registered experiment plugin through the generic runner",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment run --experiment <id> [options]",
+        "",
+        "Required:",
+        "  --experiment <id>   Registered experiment plugin id (see \"my-dev-kit-lab experiment list\")",
+        "",
+        "Options:",
+        "  --target <path>                                    Local target project path (default: self)",
+        "  --out <dir>                                         Output directory for experiment artifacts",
+        "                                                      (default: beneath the workspace when installed)",
+        "  --cases <path>                                      Path to the evaluation cases file",
+        "                                                      (default: the bundled package resource)",
+        "  --project-profiles <path>                          Path to the benchmark project profiles file",
+        "                                                      (default: the bundled package resource)",
+        "  --case <ids>                                       Comma-separated case ids to run",
+        "  --benchmark-project <ids>                          Comma-separated benchmark project ids to run",
+        "  --agents <list>                                    Comma-separated agent ids (default: fake-agent)",
+        "  --strategies <list>                                Comma-separated strategies: raw-full-file,my-dev-kit-guided",
+        "  --complexities <list>                               Comma-separated complexity levels: short,medium,long,multi-step",
+        "  --timeout-ms <ms>                                  Per-run timeout in milliseconds",
+        "  --max-runs <n>                                     Maximum number of runs",
+        "  --continue-on-failure / --no-continue-on-failure   Continue after a failed run (default: continue-on-failure)",
+        "  --require-agents                                   Fail if no real agent command templates are configured",
+        "  --include-real-agents                              Allow real agent ids (codex, claude)",
+        "  --command-template-codex <template>                Command template used to invoke the codex agent",
+        "  --command-template-claude <template>               Command template used to invoke the claude agent",
+        "  --no-screenshot                                     Accepted for compatibility; the plugin-aware report",
+        "                                                      path does not capture screenshots yet"
+    ].join("\n");
+}
+export function renderExperimentControlledHelp() {
+    return [
+        "my-dev-kit-lab experiment controlled - run a controlled context-strategy-comparison experiment",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab experiment controlled --cases <path> --out <dir> [options]",
+        "",
+        "Required:",
+        "  --cases <path>   Path to the evaluation cases file",
+        "  --out <dir>      Output directory for experiment artifacts",
+        "",
+        "Options:",
+        "  --project-profiles <path>                          Path to the benchmark project profiles file",
+        "                                                      (default: the bundled package resource)",
+        "  --case <ids>                                       Comma-separated case ids to run",
+        "  --benchmark-project <ids>                          Comma-separated benchmark project ids to run",
+        "  --agents <list>                                    Comma-separated agent ids (default: fake-agent)",
+        "  --strategies <list>                                Comma-separated strategies: raw-full-file,my-dev-kit-guided",
+        "  --complexities <list>                               Comma-separated complexity levels: short,medium,long,multi-step",
+        "  --timeout-ms <ms>                                  Per-run timeout in milliseconds",
+        "  --max-runs <n>                                     Maximum number of runs",
+        "  --continue-on-failure / --no-continue-on-failure   Continue after a failed run (default: continue-on-failure)",
+        "  --require-agents                                   Fail if no real agent command templates are configured",
+        "  --include-real-agents                              Allow real agent ids (codex, claude)",
+        "  --command-template-codex <template>                Command template used to invoke the codex agent",
+        "  --command-template-claude <template>               Command template used to invoke the claude agent"
+    ].join("\n");
+}
+export function renderReportHelp() {
+    return [
+        "my-dev-kit-lab report - report command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab report render [options]",
+        "  my-dev-kit-lab report --help",
+        "",
+        "Commands:",
+        "  render   Render an HTML/JSON experiment report from controlled-experiment artifacts.",
+        "           Run \"my-dev-kit-lab report render --help\" for details."
+    ].join("\n");
+}
+export function renderReportRenderHelp() {
+    return [
+        "my-dev-kit-lab report render - render an HTML/JSON experiment report from controlled-experiment artifacts",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab report render --experiment <dir> --out <dir> [options]",
+        "",
+        "Required:",
+        "  --experiment <dir>   Path to a controlled-experiment output directory",
+        "  --out <dir>          Output directory for the rendered report",
+        "",
+        "Options:",
+        "  --title <title>                    Report title",
+        "  --subtitle <subtitle>               Report subtitle",
+        "  --screenshot / --no-screenshot      Enable/disable PNG screenshot capture (default: disabled)",
+        "  --require-screenshot                Fail unless a screenshot was captured (implies --screenshot)",
+        "  --max-prompt-chars <n>              Maximum characters of prompt text to include",
+        "  --max-file-tree-entries <n>         Maximum file tree entries to include",
+        "  --plots <dir>                       Optional plots directory to include in the report",
+        "  --visualizations <dir>              Optional visualization-demos directory to include in the report"
+    ].join("\n");
+}
+export function renderPlotsHelp() {
+    return [
+        "my-dev-kit-lab plots - plots command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab plots generate [options]",
+        "  my-dev-kit-lab plots --help",
+        "",
+        "Commands:",
+        "  generate   Generate experiment plot artifacts from controlled-experiment artifacts.",
+        "             Run \"my-dev-kit-lab plots generate --help\" for details."
+    ].join("\n");
+}
+export function renderPlotsGenerateHelp() {
+    return [
+        "my-dev-kit-lab plots generate - generate chart/plot artifacts from controlled-experiment artifacts",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab plots generate --experiment <dir> --out <dir>",
+        "",
+        "Required:",
+        "  --experiment <dir>   Path to a controlled-experiment output directory",
+        "  --out <dir>          Output directory for plot artifacts"
+    ].join("\n");
+}
+export function renderGalleryHelp() {
+    return [
+        "my-dev-kit-lab gallery - gallery command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab gallery build [options]",
+        "  my-dev-kit-lab gallery --help",
+        "",
+        "Commands:",
+        "  build   Build a gallery manifest/index from report, plots, and visualization artifacts.",
+        "          Run \"my-dev-kit-lab gallery build --help\" for details."
+    ].join("\n");
+}
+export function renderGalleryBuildHelp() {
+    return [
+        "my-dev-kit-lab gallery build - build a gallery manifest/index from existing artifacts",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab gallery build --out <dir> [options]",
+        "",
+        "Required:",
+        "  --out <dir>   Output directory for the gallery manifest and index",
+        "",
+        "Options:",
+        "  --report <dir>           Path to a rendered report directory",
+        "  --plots <dir>            Path to a plots output directory",
+        "  --visualizations <dir>   Path to a visualization-demos output directory",
+        "  --experiment <dir>       Path to a controlled-experiment output directory"
+    ].join("\n");
+}
+export function renderSecurityHelp() {
+    return [
+        "my-dev-kit-lab security - security command family",
+        "",
+        "Usage:",
+        "  my-dev-kit-lab security validate [options]",
+        "  my-dev-kit-lab security --help",
+        "",
+        "Commands:",
+        "  validate   Run security validation. Run \"my-dev-kit-lab security validate --help\" for details."
+    ].join("\n");
+}
+export function renderUnknownCommandError(command) {
+    return [
+        `Unknown command: ${command}`,
+        "Run \"my-dev-kit-lab --help\" for usage."
+    ].join("\n");
+}

package/dist/src/cli/index.js

@@ -0,0 +1,2 @@
+export * from "./runLabCli.js";
+export * from "./help.js";