delivery-friction-analyzer 0.18.0 → 0.20.0

package/README.md

@@ -9,25 +9,44 @@ Use it when you want to answer questions like:
 - Which files, surfaces, or PR classes create the most back-and-forth?
 - Which issues look preventable with better local checks, repo-specific AI instructions, skills, hooks, or smaller delivery slices?
 
-The analyzer runs locally with your GitHub credentials. Generated artifacts preserve source evidence, coverage caveats, and interpretation limits so reports can be inspected before they are shared.
+For live GitHub analysis, the analyzer runs locally with your GitHub credentials. Generated artifacts preserve source evidence, coverage caveats, and interpretation limits so reports can be inspected before they are shared.
 
 ## Requirements
 
 - Node.js 20 or newer.
-- GitHub CLI (`gh`) installed and authenticated with access to the target repository.
-- A repository profile JSON for the repository you want to analyze. Interactive setup can create a starter profile for you.
+- GitHub CLI (`gh`) installed and authenticated with access to the target repository for live GitHub analysis.
+- A repository profile JSON for the repository you want to analyze in live GitHub mode. Interactive setup can create a starter profile for you.
 
 For public repositories, ordinary read access is usually enough. Private repositories need a `gh` token with enough read access for the requested source families. With a classic PAT, that usually means the `repo` scope. With a fine-grained token or GitHub App, grant read permissions for repository metadata and contents, pull requests, Actions, and checks where available. Missing or partial source coverage is recorded in the generated methodology and coverage artifacts instead of being treated as complete data.
 
 ## Quickstart
 
+### Run the bundled sample
+
+Start with the synthetic tutorial sample. It runs locally without GitHub credentials and writes the same artifact family as live analysis:
+
+```sh
+npx delivery-friction-analyzer --source sample --out reports/tutorial
+```
+
+Open `reports/tutorial/friction-report.md` first. The sample output is labeled `Bundled synthetic sample, not live GitHub data` in the CLI completion, report, methodology, and source bundle.
+
+Short excerpt from the generated sample report context:
+
+> Source: Bundled synthetic sample, not live GitHub data.
+>
+> The generated sample report opens by pointing readers to Change scope, Review churn, and Repo guidance gap. It also shows why the first findings should not be overgeneralized: PR #104 is intentionally broad and outlier-sensitive, PR-open diff coverage is partial, and one PR has unavailable workflow-run history.
+
+Screenshots are intentionally deferred until the project has a visual report surface worth capturing.
+
 ### Guided setup
 
-From this repository, install dependencies and let interactive setup create or confirm the repository profile for a GitHub repository you want to measure:
+After reading the sample report, analyze a repository you own or can read. From this repository, install dependencies and let interactive setup create or confirm the repository profile for a GitHub repository you want to measure:
 
 ```sh
 npm install
 npm run analyze:github -- \
+  --source github \
   --repo owner/name \
   --limit 30 \
   --profile profiles/owner-name.json \
@@ -44,6 +63,7 @@ After you have a repository profile, run the analyzer against the target reposit
 
 ```sh
 npm run analyze:github -- \
+  --source github \
   --repo owner/name \
   --limit 30 \
   --profile profiles/owner-name.json \
@@ -56,6 +76,7 @@ To run the CLI from another project with the npm package, pass the same choices
 
 ```sh
 npx delivery-friction-analyzer \
+  --source github \
   --repo owner/name \
   --limit 30 \
   --profile path/to/repository-profile.json \
@@ -108,6 +129,8 @@ Each ranked bottleneck example includes source references, workflow-run conclusi
 
 ## Common Options
 
+Use `--source sample` for the bundled synthetic tutorial data. Use `--source github` for live repository analysis. Existing live commands that pass `--repo`, `--profile`, or `--limit` without `--source` still run as GitHub analysis, but new users should prefer the explicit source flag.
+
 Use `--dry-run` or `--metadata-only` to validate repository access, profile JSON, output directory writability, and sampled API coverage without writing full report artifacts. The output directory may be created during this check, and a temporary probe file may be written and removed.
 
 Use `--no-csv` when you want the Markdown, JSON, source, normalized, metrics, and methodology artifacts without spreadsheet-friendly CSV exports.

package/docs/contracts/target-repository.md

@@ -19,7 +19,13 @@ Schema: `schemas/target-repository.schema.json`. Live analysis selection is late
 
 The validator rejects a target repository that exactly matches the configured product repository. For this repository, the product repository is `hannasdev/delivery-friction-analyzer`; `hannasdev/mcp-writing` is an internal validation target and fixture source.
 
-Live GitHub analysis enforces this separation before GitHub collection starts. If `--repo` names this tool's product repository, the command fails before provider calls, explains that the guard prevents accidental self-analysis during normal live runs rather than protecting already readable GitHub data, tells you to choose the repository you want to measure with `--repo owner/name`, and confirms that no GitHub data was collected. `--validation-target` only marks output metadata and does not bypass this guard. The product repository identity is repo-local implementation configuration, not a public CLI option.
+Live GitHub analysis enforces this separation before GitHub collection starts. If `--repo` names this tool's product repository, the command fails before provider calls, explains that the guard prevents accidental self-analysis during normal live runs rather than protecting already readable GitHub data, recommends the bundled sample or another repository first, and confirms that no GitHub data was collected.
+
+`--validation-target` only marks output metadata for internal validation or fixture-source runs. It does not bypass product-repository validation and does not change which repository may be analyzed.
+
+`--allow-product-repository` is an explicit live-analysis override for intentional self-analysis of this product repository. It is not the tutorial path and is rejected in sample mode. When the override is present for the product repository, the CLI must prove required GitHub data is readable before collection or artifact writes. Required preflight reads are repository metadata, pull request inventory, and pull request details for at least one selected merged pull request. Review threads, workflow runs, languages, contributor source, and PR-open diff remain normal coverage families; partial or unavailable optional coverage should be reported as caveats after the required assertion succeeds rather than failing the preflight.
+
+The product repository identity is repo-local implementation configuration, not a general public CLI setting.
 
 ## Degraded Behavior
 

package/docs/reference/release-automation.md

@@ -7,6 +7,7 @@ Delivery Friction Analyzer publishes the unbundled source package to npm. This r
 The npm package allowlist includes:
 
 - runtime source in `src`;
+- bundled tutorial sample runtime data in `examples/tutorial`;
 - JSON schemas in `schemas`;
 - public contract and reference docs in `docs/contracts` and `docs/reference`;
 - the internal validation repository profile at `fixtures/github/mcp-writing/profile.json`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Local GitHub pull request analytics for delivery friction reports.",
   "license": "MIT",
   "type": "module",

package/release-log.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+### 2026-06-27 — Product Repository Override
+
+- What changed: Added the explicit `--allow-product-repository` live-analysis override for intentional analysis of this tool's own repository, with required read-access checks before collection or artifact writes.
+- Why it matters: Maintainers can deliberately validate the analyzer against its public product repository without weakening the normal guardrail that steers first-time users toward the bundled sample or another target repository.
+- Who is affected: Maintainers intentionally running self-analysis, and users who hit the product-repository guard during live GitHub setup.
+- Action needed: Use the bundled sample or another repository for normal first-run analysis; add `--allow-product-repository` only for intentional self-analysis after confirming GitHub access.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/63
+
+### 2026-06-27 — Explicit Sample CLI Source
+
+- What changed: Added explicit `--source sample` CLI routing for the bundled tutorial sample, with sample-first README guidance and live-only option rejection before GitHub collection.
+- Why it matters: New users can generate a deterministic local report without GitHub credentials, while existing live GitHub runs keep their source boundary and required target-option validation.
+- Who is affected: First-time users trying the tutorial sample, maintainers reviewing CLI source routing, and users passing live-only flags such as repository targets, dry-run checks, or PR class exclusions.
+- Action needed: Use `delivery-friction-analyzer --source sample --out reports/tutorial` for the bundled sample, or `delivery-friction-analyzer --source github --repo owner/name --limit 30 --profile path/to/profile.json --out reports/owner-name` for live analysis.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/62
+
 ### 2026-06-27 — Tutorial Sample Bundle
 
 - What changed: Added the packaged tutorial sample source bundle, educational sample profile, and generated-aligned report excerpt for a fully synthetic repository.

package/src/cli/analyze-github.js

@@ -4,8 +4,16 @@ import { access, lstat, mkdir, open, readFile, rename, rm, stat, writeFile } fro
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { collectGitHubSourceBundle } from "../collect/github-source-bundle.js";
+import {
+  assertProductRepositoryReadableData,
+  collectGitHubSourceBundle,
+} from "../collect/github-source-bundle.js";
 import { createGhCliProvider } from "../collect/gh-provider.js";
+import {
+  DEFAULT_PRODUCT_REPOSITORY,
+  isProductRepositoryTarget,
+  productRepositoryTargetError,
+} from "../contracts/target-repository.js";
 import { computeRepositoryMetrics } from "../metrics/friction.js";
 import { normalizeFixtureBundle } from "../normalize/github-fixture.js";
 import {
@@ -25,8 +33,12 @@ import {
 } from "../profile/workflow.js";
 
 const RUN_PRESET_SCHEMA_VERSION = "analyze-github-run-preset.v1";
+const SAMPLE_SOURCE_LABEL = "Bundled synthetic sample, not live GitHub data";
+const SAMPLE_SOURCE_BUNDLE_URL = new URL("../../examples/tutorial/source-bundle.json", import.meta.url);
+const SAMPLE_PROFILE_URL = new URL("../../examples/tutorial/profile.json", import.meta.url);
 
 const ALLOWED_OPTIONS = new Set([
+  "source",
   "repo",
   "limit",
   "profile",
@@ -44,6 +56,7 @@ const ALLOWED_OPTIONS = new Set([
   "interactive",
   "preset",
   "save-preset",
+  "allow-product-repository",
 ]);
 
 const BOOLEAN_OPTIONS = new Set([
@@ -57,9 +70,11 @@ const BOOLEAN_OPTIONS = new Set([
   "json",
   "no-json",
   "interactive",
+  "allow-product-repository",
 ]);
 
 const CLI_OPTION_KEYS = Object.freeze({
+  source: "source",
   repo: "repository",
   limit: "limit",
   profile: "profilePath",
@@ -77,6 +92,7 @@ const CLI_OPTION_KEYS = Object.freeze({
   interactive: "interactive",
   preset: "presetPath",
   "save-preset": "savePresetPath",
+  "allow-product-repository": "allowProductRepository",
 });
 
 const RUN_PRESET_OPTION_KEYS = Object.freeze([
@@ -114,10 +130,13 @@ const CSV_ARTIFACT_KEYS = new Set([
 ]);
 
 export const USAGE = `Usage:
+  delivery-friction-analyzer --source sample --out <directory>
+  delivery-friction-analyzer --source github --repo <owner/name> --limit <1-100> --profile <path> --out <directory>
   delivery-friction-analyzer --repo <owner/name> --limit <1-100> --profile <path> --out <directory>
   delivery-friction-analyzer --repo <owner/name> --limit <1-100> --profile <path> --out <directory> --dry-run
 
 Options:
+  --source <sample|github> Choose the bundled synthetic sample or live GitHub analysis.
   --repo <owner/name>       Target GitHub repository to analyze.
   --limit <1-100>           Latest merged pull request count.
   --profile <path>          Repository profile JSON used for file role classification.
@@ -127,6 +146,8 @@ Options:
   --metadata-only           Alias for --dry-run.
   --validation-target       Mark output metadata as an internal validation run; does not bypass target validation.
   --no-validation-target    Disable validation-target mode when a preset enabled it.
+  --allow-product-repository
+                            Explicit live-analysis override for intentional self-analysis of this product repository.
   --exclude-pr-class <cls>  Exclude a PR class from normalized, metrics, report, methodology, and CSV artifacts. Repeat or comma-separate values.
   --csv                     Enable curated CSV evidence exports when a preset disabled them.
   --no-csv                  Suppress curated CSV evidence exports.
@@ -137,6 +158,14 @@ Options:
   --save-preset <path>      Save local run settings for non-interactive reruns.
 `;
 
+export const SOURCE_SELECTION_GUIDANCE = `Choose what to analyze.
+
+Try the bundled sample:
+  delivery-friction-analyzer --source sample --out reports/tutorial
+
+Analyze a GitHub repository:
+  delivery-friction-analyzer --source github --repo owner/name --limit 30 --profile path/to/profile.json --out reports/owner-name`;
+
 function attachOptionSource(options, property, value) {
   Object.defineProperty(options, property, {
     value,
@@ -199,6 +228,7 @@ export function parseAnalyzeGithubArgs(argv) {
       if (key === "json") options.json = true;
       if (key === "no-json") options.json = false;
       if (key === "interactive") options.interactive = true;
+      if (key === "allow-product-repository") options.allowProductRepository = true;
       continue;
     }
 
@@ -215,6 +245,7 @@ export function parseAnalyzeGithubArgs(argv) {
   }
 
   const parsed = {
+    source: options.source,
     repository: options.repo,
     limit: options.limit === undefined ? undefined : Number(options.limit),
     profilePath: options.profile,
@@ -226,8 +257,10 @@ export function parseAnalyzeGithubArgs(argv) {
     json: options.json,
     interactive: options.interactive,
   };
+  if (options.allowProductRepository) parsed.allowProductRepository = true;
   if (options.preset !== undefined) parsed.presetPath = options.preset;
   if (options["save-preset"] !== undefined) parsed.savePresetPath = options["save-preset"];
+  if (parsed.source === undefined) delete parsed.source;
 
   return attachOptionSource(parsed, "explicitCliOptions", explicitOptions);
 }
@@ -408,6 +441,12 @@ function requireOptions(options) {
   }
 }
 
+function requireSampleOptions(options) {
+  if (!options.outDir) {
+    throw new Error("Missing required option(s): --out");
+  }
+}
+
 function validateRepositorySlug(repository) {
   if (typeof repository !== "string" || !REPOSITORY_SLUG.test(repository)) {
     throw new Error("repo must use owner/name with GitHub-safe owner and name segments.");
@@ -428,6 +467,84 @@ function validateExcludedPrClasses(excludedPrClasses = []) {
   }
 }
 
+function validateSource(source) {
+  if (source !== "sample" && source !== "github") {
+    throw new Error("source must be one of: sample, github");
+  }
+}
+
+function hasLiveSourceIndicator(options) {
+  const providedOptions = new Set([
+    ...optionSourceSet(options, "explicitCliOptions"),
+    ...optionSourceSet(options, "presetOptionKeys"),
+  ]);
+  return Boolean(
+    options.repository
+      || options.limit !== undefined
+      || options.profilePath
+      || options.dryRun
+      || options.isValidationTarget
+      || options.interactive
+      || options.presetPath
+      || options.savePresetPath
+      || options.allowProductRepository
+      || options.excludedPrClasses?.length
+      || providedOptions.has("dryRun")
+      || providedOptions.has("isValidationTarget")
+      || providedOptions.has("interactive")
+      || providedOptions.has("presetPath")
+      || providedOptions.has("savePresetPath")
+      || providedOptions.has("allowProductRepository")
+      || providedOptions.has("excludedPrClasses"),
+  );
+}
+
+function resolveAnalysisSource(options) {
+  if (options.source !== undefined) {
+    validateSource(options.source);
+    return options.source;
+  }
+  if (hasLiveSourceIndicator(options)) {
+    return "github";
+  }
+  throw new Error(SOURCE_SELECTION_GUIDANCE);
+}
+
+function rejectSampleLiveOptions(options) {
+  const incompatible = [];
+  const providedOptions = new Set([
+    ...optionSourceSet(options, "explicitCliOptions"),
+    ...optionSourceSet(options, "presetOptionKeys"),
+  ]);
+  const dryRunOptionLabel = providedOptions.has("dryRun") && options.dryRun
+    ? "--dry-run/--metadata-only"
+    : "--dry-run";
+  if (options.repository) incompatible.push("--repo");
+  if (options.limit !== undefined) incompatible.push("--limit");
+  if (options.profilePath) incompatible.push("--profile");
+  if (options.dryRun || providedOptions.has("dryRun")) incompatible.push(dryRunOptionLabel);
+  if (options.isValidationTarget || providedOptions.has("isValidationTarget")) incompatible.push("--validation-target");
+  if (options.interactive) incompatible.push("--interactive");
+  if (options.presetPath) incompatible.push("--preset");
+  if (options.savePresetPath) incompatible.push("--save-preset");
+  if (options.allowProductRepository || providedOptions.has("allowProductRepository")) {
+    incompatible.push("--allow-product-repository");
+  }
+  if (options.excludedPrClasses?.length || providedOptions.has("excludedPrClasses")) {
+    incompatible.push("--exclude-pr-class");
+  }
+  if (!incompatible.length) return;
+  throw new Error(`--source sample cannot be combined with live GitHub option(s): ${incompatible.join(", ")}. Use only output options such as --out, --json, --csv, or --no-csv.`);
+}
+
+function targetInputFromRepositorySlug(repository) {
+  const match = REPOSITORY_SLUG.exec(repository);
+  if (!match) {
+    throw new Error("repo must use owner/name with GitHub-safe owner and name segments.");
+  }
+  return { owner: match[1], name: match[2] };
+}
+
 function configuredPrClasses(repositoryProfile) {
   const rules = Array.isArray(repositoryProfile?.prClasses) ? repositoryProfile.prClasses : [];
   return new Set(rules.map(rule => rule.class));
@@ -1444,6 +1561,7 @@ function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report,
     sampledLimit,
     outputDirectory: outDir,
     artifactPaths: dryRun ? null : paths,
+    source: sourceBundle.source,
     targetRepository: sourceBundle.targetRepository,
     selection: sourceBundle.selection,
     collectionCoverage: sourceBundle.coverage,
@@ -1484,6 +1602,49 @@ function applyPrClassFilter(normalized, excludedPrClasses = []) {
   };
 }
 
+async function readBundledJson(url, label) {
+  try {
+    return JSON.parse(await readFile(url, "utf8"));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`${label} must be valid JSON: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+async function buildAnalysisArtifacts({ sourceBundle, repositoryProfile, profilePath, csvEnabled, excludedPrClasses = [] }) {
+  validateExcludedPrClassesAreConfigured(excludedPrClasses, repositoryProfile);
+  const normalized = applyPrClassFilter(
+    normalizeFixtureBundle(sourceBundle, { repositoryProfile }),
+    excludedPrClasses,
+  );
+  const metrics = computeRepositoryMetrics(normalized);
+  const report = attachCollectionCoverage(
+    generateRepositoryFrictionReport(metrics, {
+      workflowContext: repositoryProfile.workflow,
+      contributorSource: normalized.contributorSource,
+    }),
+    sourceBundle,
+  );
+  const markdown = `${renderRepositoryFrictionMarkdown(report)}${collectionCoverageMarkdown(sourceBundle)}`;
+  const methodology = renderRepositoryFrictionMethodology({
+    report,
+    sourceBundle,
+    profilePath,
+    artifactFileNames: ANALYZE_GITHUB_ARTIFACTS,
+    csvEnabled,
+  });
+  const csv = csvEnabled
+    ? generateEvidenceCsvArtifacts({
+      metricsSummary: metrics,
+      report,
+      collectionCoverage: sourceBundle.coverage,
+    })
+    : {};
+  return { normalized, metrics, report, markdown, methodology, csv };
+}
+
 export async function runAnalyzeGithub(options, {
   provider = createGhCliProvider(),
   now = () => new Date().toISOString(),
@@ -1495,12 +1656,26 @@ export async function runAnalyzeGithub(options, {
   validateLimit(options.limit);
   validateExcludedPrClasses(options.excludedPrClasses);
   const csvEnabled = options.csv !== false;
+  const effectiveProductRepository = productRepository ?? DEFAULT_PRODUCT_REPOSITORY;
+  const targetInput = targetInputFromRepositorySlug(options.repository);
+  const targetsProductRepository = isProductRepositoryTarget(targetInput, effectiveProductRepository);
+  if (targetsProductRepository && !options.allowProductRepository) {
+    throw new Error(productRepositoryTargetError(targetInput));
+  }
+  onProgress?.("Validating profile.");
+  const repositoryProfile = await readProfile(options.profilePath);
+  if (targetsProductRepository) {
+    onProgress?.("Checking required GitHub read access for product-repository analysis.");
+    await assertProductRepositoryReadableData({
+      repository: options.repository,
+      limit: options.dryRun ? Math.min(options.limit, 1) : options.limit,
+      provider,
+      productRepository: effectiveProductRepository,
+    });
+  }
 
-  onProgress?.("Validating profile and output directory.");
-  const [repositoryProfile, outDir] = await Promise.all([
-    readProfile(options.profilePath),
-    validateOutputDirectory(options.outDir),
-  ]);
+  onProgress?.("Validating output directory.");
+  const outDir = await validateOutputDirectory(options.outDir);
   validateExcludedPrClassesAreConfigured(options.excludedPrClasses ?? [], repositoryProfile);
   const generatedPaths = artifactPaths(outDir, { includeCsv: csvEnabled });
   const disabledPaths = csvEnabled ? {} : Object.fromEntries(
@@ -1521,7 +1696,8 @@ export async function runAnalyzeGithub(options, {
     collectedAt: now(),
     isValidationTarget: options.isValidationTarget,
     contributors: repositoryProfile.contributors,
-    productRepository,
+    productRepository: effectiveProductRepository,
+    allowProductRepository: Boolean(options.allowProductRepository),
   });
 
   if (options.dryRun) {
@@ -1541,43 +1717,23 @@ export async function runAnalyzeGithub(options, {
   }
 
   onProgress?.("Normalizing source bundle and computing metrics.");
-  const normalized = applyPrClassFilter(
-    normalizeFixtureBundle(sourceBundle, { repositoryProfile }),
-    options.excludedPrClasses ?? [],
-  );
-  const metrics = computeRepositoryMetrics(normalized);
-  const report = attachCollectionCoverage(
-    generateRepositoryFrictionReport(metrics, {
-      workflowContext: repositoryProfile.workflow,
-      contributorSource: normalized.contributorSource,
-    }),
-    sourceBundle,
-  );
-  const markdown = `${renderRepositoryFrictionMarkdown(report)}${collectionCoverageMarkdown(sourceBundle)}`;
-  const methodology = renderRepositoryFrictionMethodology({
-    report,
+  const artifacts = await buildAnalysisArtifacts({
     sourceBundle,
     profilePath: options.profilePath,
-    artifactFileNames: ANALYZE_GITHUB_ARTIFACTS,
     csvEnabled,
+    repositoryProfile,
+    excludedPrClasses: options.excludedPrClasses ?? [],
   });
-  const csv = csvEnabled
-    ? generateEvidenceCsvArtifacts({
-      metricsSummary: metrics,
-      report,
-      collectionCoverage: sourceBundle.coverage,
-    })
-    : {};
 
   onProgress?.("Writing local artifacts.");
   await writeAnalysisArtifacts(outDir, generatedPaths, {
     sourceBundle,
-    normalized,
-    metricsSummary: metrics,
-    reportJson: report,
-    reportMarkdown: markdown,
-    methodology,
-    csv,
+    normalized: artifacts.normalized,
+    metricsSummary: artifacts.metrics,
+    reportJson: artifacts.report,
+    reportMarkdown: artifacts.markdown,
+    methodology: artifacts.methodology,
+    csv: artifacts.csv,
   }, { disabledPaths });
 
   return summarizeResult({
@@ -1585,18 +1741,75 @@ export async function runAnalyzeGithub(options, {
     outDir,
     paths: generatedPaths,
     sourceBundle,
-    metrics,
-    report,
+    metrics: artifacts.metrics,
+    report: artifacts.report,
     requestedLimit: options.limit,
     sampledLimit: collectionLimit,
     csv: csvEnabled,
-    analysisFilter: normalized.analysisFilter ?? null,
+    analysisFilter: artifacts.normalized.analysisFilter ?? null,
     savedProfilePath: options.savedProfilePath,
     savedRunPresetPath: options.savedRunPresetPath,
     prClassRulesWritten: options.prClassRulesWritten,
   });
 }
 
+export async function runAnalyzeSample(options, {
+  onProgress = null,
+} = {}) {
+  rejectSampleLiveOptions(options);
+  requireSampleOptions(options);
+  const csvEnabled = options.csv !== false;
+
+  onProgress?.("Loading bundled synthetic sample.");
+  const [sourceBundle, repositoryProfile, outDir] = await Promise.all([
+    readBundledJson(SAMPLE_SOURCE_BUNDLE_URL, "sample source bundle"),
+    readBundledJson(SAMPLE_PROFILE_URL, "sample repository profile"),
+    validateOutputDirectory(options.outDir),
+  ]);
+  if (sourceBundle.source?.kind !== "sample" || sourceBundle.source?.label !== SAMPLE_SOURCE_LABEL) {
+    throw new Error(`sample source bundle source.kind must be sample and source.label must be ${SAMPLE_SOURCE_LABEL}.`);
+  }
+  validateProfile(repositoryProfile);
+
+  const generatedPaths = artifactPaths(outDir, { includeCsv: csvEnabled });
+  const disabledPaths = csvEnabled ? {} : Object.fromEntries(
+    Object.entries(artifactPaths(outDir, { includeCsv: true })).filter(([key]) => CSV_ARTIFACT_KEYS.has(key)),
+  );
+  await assertWritableArtifactTargets({ ...generatedPaths, ...disabledPaths });
+
+  onProgress?.("Normalizing source bundle and computing metrics.");
+  const artifacts = await buildAnalysisArtifacts({
+    sourceBundle,
+    profilePath: "examples/tutorial/profile.json",
+    csvEnabled,
+    repositoryProfile,
+  });
+
+  onProgress?.("Writing local artifacts.");
+  await writeAnalysisArtifacts(outDir, generatedPaths, {
+    sourceBundle,
+    normalized: artifacts.normalized,
+    metricsSummary: artifacts.metrics,
+    reportJson: artifacts.report,
+    reportMarkdown: artifacts.markdown,
+    methodology: artifacts.methodology,
+    csv: artifacts.csv,
+  }, { disabledPaths });
+
+  return summarizeResult({
+    dryRun: false,
+    outDir,
+    paths: generatedPaths,
+    sourceBundle,
+    metrics: artifacts.metrics,
+    report: artifacts.report,
+    requestedLimit: sourceBundle.selection?.requestedLimit,
+    sampledLimit: sourceBundle.selection?.collectedCount,
+    csv: csvEnabled,
+    analysisFilter: null,
+  });
+}
+
 function writeProgress(message, stderr = process.stderr) {
   stderr.write(`${message}\n`);
 }
@@ -1637,6 +1850,7 @@ export function formatAnalyzeGithubCompletion(result) {
     lines.push(
       `Markdown report: ${paths.reportMarkdown}`,
       `Analysis complete for ${target}.`,
+      `Source: ${result.source?.label ?? "not recorded"}.`,
       `Methodology: ${paths.methodology}`,
       `JSON report: ${paths.reportJson}`,
       `Metrics summary: ${paths.metricsSummary}`,
@@ -1712,7 +1926,28 @@ export async function runAnalyzeGithubCli(argv, {
       stdout.write(USAGE);
       return null;
     }
+    if (parsedOptions.source !== undefined) {
+      validateSource(parsedOptions.source);
+      if (parsedOptions.source === "sample") {
+        const runOptions = {
+          onProgress: message => writeProgress(message, stderr),
+        };
+        const result = await runAnalyzeSample(parsedOptions, runOptions);
+        writeAnalyzeGithubCompletion(result, { json: parsedOptions.json, stdout });
+        return result;
+      }
+    }
     const options = await mergeRunPresetOptions(parsedOptions);
+    const source = resolveAnalysisSource(options);
+
+    if (source === "sample") {
+      const runOptions = {
+        onProgress: message => writeProgress(message, stderr),
+      };
+      const result = await runAnalyzeSample(options, runOptions);
+      writeAnalyzeGithubCompletion(result, { json: options.json, stdout });
+      return result;
+    }
 
     const providedOptionKeys = new Set([
       ...optionSourceSet(options, "explicitCliOptions"),

package/src/collect/github-source-bundle.js

@@ -49,7 +49,7 @@ function visibilityOf(repository) {
   return "unknown";
 }
 
-function mapTargetRepository({ owner, name, repositoryMetadata, analysisPullRequestLimit, isValidationTarget, productRepository }) {
+function mapTargetRepository({ owner, name, repositoryMetadata, analysisPullRequestLimit, isValidationTarget, productRepository, allowProductRepository }) {
   const targetRepository = {
     owner,
     name,
@@ -58,13 +58,90 @@ function mapTargetRepository({ owner, name, repositoryMetadata, analysisPullRequ
     analysisPullRequestLimit,
     isValidationTarget,
   };
-  const errors = validateTargetRepository(targetRepository, { productRepository });
+  const errors = validateTargetRepository(targetRepository, { productRepository, allowProductRepository });
   if (errors.length > 0) {
     throw new Error(`collected target repository metadata is invalid: ${errors.join(" ")}`);
   }
   return targetRepository;
 }
 
+function formatReadableDataFailure({ repository, family, action, error }) {
+  const diagnostic = redactDiagnostic(error?.message ?? error);
+  return `Cannot analyze ${repository} with --allow-product-repository because required GitHub read access could not be proven for ${family}. ${action}. Required preflight must read repository metadata, pull request inventory, and pull request details before collection or artifact writes.${diagnostic ? ` GitHub response: ${diagnostic}` : ""}`;
+}
+
+async function requireReadableProbe({ repository, family, action, run }) {
+  try {
+    return await run();
+  } catch (error) {
+    throw new Error(formatReadableDataFailure({
+      repository,
+      family,
+      action,
+      error,
+    }));
+  }
+}
+
+export async function assertProductRepositoryReadableData({
+  repository,
+  owner,
+  name,
+  limit,
+  provider,
+  productRepository = DEFAULT_PRODUCT_REPOSITORY,
+} = {}) {
+  if (!provider) {
+    throw new Error("provider is required.");
+  }
+  requirePullRequestLimit(limit);
+  const targetInput = repository ? parseRepositoryInput(repository) : { owner, name };
+  if (!isProductRepositoryTarget(targetInput, productRepository)) {
+    return { requiredFamilies: [] };
+  }
+
+  const repositoryLabel = `${targetInput.owner}/${targetInput.name}`;
+  await requireReadableProbe({
+    repository: repositoryLabel,
+    family: "repository metadata",
+    action: "Authenticate with GitHub CLI or choose a repository your token can read",
+    run: () => provider.getRepository(targetInput),
+  });
+
+  const inventory = await requireReadableProbe({
+    repository: repositoryLabel,
+    family: "pull request inventory",
+    action: "Ensure `gh pr list --repo owner/name` can list merged pull requests",
+    run: () => provider.listMergedPullRequests({ ...targetInput, limit }),
+  });
+  if (!Array.isArray(inventory)) {
+    throw new Error(`Cannot analyze ${repositoryLabel} with --allow-product-repository because required GitHub read access could not be proven for pull request inventory. GitHub returned an unreadable pull request inventory shape. Required preflight must read repository metadata, pull request inventory, and pull request details before collection or artifact writes.`);
+  }
+  const selectedInventory = [...inventory]
+    .sort((left, right) => String(right.mergedAt ?? "").localeCompare(String(left.mergedAt ?? "")))
+    .slice(0, limit);
+  const firstPullRequest = selectedInventory[0];
+  if (!firstPullRequest?.number) {
+    throw new Error(`Cannot analyze ${repositoryLabel} with --allow-product-repository because required GitHub read access could not be proven for pull request details. The pull request inventory returned no merged pull requests to inspect. Choose another repository or rerun after merged pull requests are readable.`);
+  }
+
+  await requireReadableProbe({
+    repository: repositoryLabel,
+    family: "pull request details",
+    action: "Ensure `gh pr view --repo owner/name <number> --json ...` can read merged pull request details",
+    run: () => provider.getPullRequest({ ...targetInput, number: firstPullRequest.number }),
+  });
+
+  return {
+    requiredFamilies: [
+      "repository_metadata",
+      "pull_request_inventory",
+      "pull_request_details",
+    ],
+    probedPullRequestNumber: firstPullRequest.number,
+  };
+}
+
 function mapRepositoryMetadata(repository) {
   return {
     id: repository.id ?? null,
@@ -378,6 +455,7 @@ export async function collectGitHubSourceBundle({
   isValidationTarget = false,
   contributors = null,
   productRepository = DEFAULT_PRODUCT_REPOSITORY,
+  allowProductRepository = false,
 } = {}) {
   if (!provider) {
     throw new Error("provider is required.");
@@ -385,7 +463,7 @@ export async function collectGitHubSourceBundle({
   const targetPullRequestLimit = analysisPullRequestLimit ?? limit;
   requirePullRequestLimit(targetPullRequestLimit);
   const targetInput = repository ? parseRepositoryInput(repository) : { owner, name };
-  if (isProductRepositoryTarget(targetInput, productRepository)) {
+  if (isProductRepositoryTarget(targetInput, productRepository) && !allowProductRepository) {
     throw new Error(productRepositoryTargetError(targetInput));
   }
   const targetNameErrors = validateTargetRepository({
@@ -394,7 +472,7 @@ export async function collectGitHubSourceBundle({
     visibility: "unknown",
     analysisPullRequestLimit: targetPullRequestLimit,
     isValidationTarget,
-  }, { productRepository }).filter(error => !error.includes("defaultBranch") && !error.includes("visibility"));
+  }, { productRepository, allowProductRepository }).filter(error => !error.includes("defaultBranch") && !error.includes("visibility"));
   if (targetNameErrors.length > 0) {
     throw new Error(targetNameErrors.join(" "));
   }
@@ -406,6 +484,7 @@ export async function collectGitHubSourceBundle({
     analysisPullRequestLimit: targetPullRequestLimit,
     isValidationTarget,
     productRepository,
+    allowProductRepository,
   });
   const repositoryCoverage = coverageEntry({
     family: "repository_metadata",

package/src/contracts/target-repository.js

@@ -13,7 +13,7 @@ function validateRepoPart(value, label) {
   return null;
 }
 
-export function validateTargetRepository(input, { productRepository } = {}) {
+export function validateTargetRepository(input, { productRepository, allowProductRepository = false } = {}) {
   const errors = [];
   if (!input || typeof input !== "object") {
     return ["target repository input must be an object."];
@@ -46,6 +46,8 @@ export function validateTargetRepository(input, { productRepository } = {}) {
   const normalizedProductName = typeof productRepository?.name === "string" ? productRepository.name.toLowerCase() : null;
 
   if (
+    !allowProductRepository
+    &&
     normalizedInputOwner
     && normalizedInputName
     && normalizedProductOwner
@@ -99,5 +101,12 @@ export function productRepositoryTargetError(input) {
   const repository = typeof input?.owner === "string" && typeof input?.name === "string"
     ? `${input.owner}/${input.name}`
     : "the requested repository";
-  return `Cannot analyze ${repository} because it is this tool's product repository. The guard prevents accidental self-analysis during normal live runs; it is not a data-security boundary. Choose a different repository with --repo owner/name. No GitHub data was collected.`;
+  return `Cannot analyze ${repository} because it is this tool's product repository. The guard prevents accidental self-analysis during normal live runs; it is not a data-security boundary.
+
+To learn the tool, run the bundled sample:
+  delivery-friction-analyzer --source sample --out reports/tutorial
+
+To analyze a different repository, pass --repo owner/name.
+
+If you intentionally want to analyze this product repository, rerun with --allow-product-repository. The CLI will check that required data is readable before writing artifacts. No GitHub data was collected.`;
 }