delivery-friction-analyzer 0.17.0 → 0.19.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/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/docs/reference/repository-profile.md

@@ -41,6 +41,12 @@ This keeps validation-target details in profile data rather than hardcoded produ
 
 Each file rule must include a unique lowercase `id`, a non-empty `match` object, a supported `category`, and a supported `role`. Optional `functionalSurface` values use the same lowercase identifier shape as rule IDs. Optional `generated` values must be booleans. Unsupported rule or matcher keys fail validation, and invalid JavaScript regexes fail before collection with the rule ID and matcher field in the error.
 
+File rules may include an optional `notes` string. Notes are human-readable
+profile context for maintainers and reviewers. They can explain why a path rule
+exists, what product surface it represents, or why a generated or low-signal
+path is intentionally classified. Notes do not affect matching order,
+classification output, scoring, collection, reports, or CSV exports.
+
 ## Pull Request Classes
 
 `prClasses` is optional. Rules are evaluated in order and the first matching rule wins. The current profile contract supports title-only matchers:
@@ -64,6 +70,12 @@ Class identifiers are validated as lower-kebab-case or lower_snake_case strings.
 
 PR class evidence is interpretive and profile-driven. It helps reports show class distributions, dominance notes, and explicit `--exclude-pr-class` filtering when you request filtering, but configured PR class rules do not change default scoring, ranking formulas, collection, or CSV export shape by themselves.
 
+PR class rules may include an optional `notes` string. Use notes to document the
+repository convention behind a class rule, such as Conventional Commit-style
+title prefixes or release-train naming. Notes are valid JSON profile data for
+humans only; they do not change title matching, PR class assignment, filtering,
+scoring, collection, reports, or CSV exports.
+
 Interactive setup can add a release PR class rule from a confirmed title convention using the current title-only matcher shape. Branch strategy answers stay in `workflow` context only; they do not create branch-based PR class matching. Branch-based class matching is deferred until a future matcher contract supports branch fields explicitly.
 
 ### Copyable PR Class Examples

package/examples/tutorial/profile.json

@@ -0,0 +1,110 @@
+{
+  "schemaVersion": "repository-profile.v1",
+  "repository": {
+    "owner": "example-org",
+    "name": "delivery-dashboard"
+  },
+  "rules": [
+    {
+      "id": "frontend-ui-paths",
+      "match": { "prefix": "apps/web/" },
+      "category": "code",
+      "role": "product_ui",
+      "functionalSurface": "dashboard_ui",
+      "generated": false,
+      "notes": "Maps the customer-facing dashboard app to the UI surface so broad UI changes are not treated as unknown code."
+    },
+    {
+      "id": "api-runtime-paths",
+      "match": { "prefix": "services/api/" },
+      "category": "code",
+      "role": "core_product_code",
+      "functionalSurface": "delivery_api",
+      "generated": false,
+      "notes": "Represents backend delivery workflow behavior that usually needs API-focused review."
+    },
+    {
+      "id": "worker-runtime-paths",
+      "match": { "prefix": "workers/" },
+      "category": "code",
+      "role": "core_product_code",
+      "functionalSurface": "background_jobs",
+      "generated": false
+    },
+    {
+      "id": "integration-tests",
+      "match": { "prefix": "tests/integration/" },
+      "category": "tests",
+      "role": "tests",
+      "functionalSurface": "test_suite",
+      "generated": false
+    },
+    {
+      "id": "workflow-config",
+      "match": { "prefix": ".github/workflows/" },
+      "category": "infrastructure",
+      "role": "infrastructure",
+      "functionalSurface": "ci_workflows",
+      "generated": false,
+      "notes": "Classifies CI workflow edits separately from product runtime changes."
+    },
+    {
+      "id": "planning-notes",
+      "match": { "prefix": "docs/initiatives/" },
+      "category": "docs",
+      "role": "planning_docs",
+      "functionalSurface": "planning",
+      "generated": false
+    },
+    {
+      "id": "release-notes",
+      "match": { "exact": "CHANGELOG.md" },
+      "category": "docs",
+      "role": "release_notes",
+      "functionalSurface": "release_docs",
+      "generated": false
+    },
+    {
+      "id": "generated-api-client",
+      "match": { "prefix": "packages/generated-client/" },
+      "category": "generated",
+      "role": "generated_or_vendored",
+      "functionalSurface": "generated_client",
+      "generated": true,
+      "notes": "Shows how generated code can stay visible while receiving low-signal weighting."
+    }
+  ],
+  "prClasses": [
+    {
+      "id": "feature-title",
+      "class": "feature",
+      "match": { "titleRegex": "^feat(?:\\([^)]+\\))?:" },
+      "notes": "Use when feature PR titles follow a Conventional Commit-style prefix."
+    },
+    {
+      "id": "fix-title",
+      "class": "fix",
+      "match": { "titleRegex": "^fix(?:\\([^)]+\\))?:" },
+      "notes": "Separates corrective work from feature delivery in the class distribution."
+    },
+    {
+      "id": "test-title",
+      "class": "test",
+      "match": { "titleRegex": "^test(?:\\([^)]+\\))?:" }
+    },
+    {
+      "id": "maintenance-title",
+      "class": "maintenance",
+      "match": { "titleRegex": "^(?:chore|ci|build|refactor)(?:\\([^)]+\\))?:" }
+    }
+  ],
+  "workflow": {
+    "primaryMergeMethod": "squash_merge",
+    "releaseStrategy": "release_prs",
+    "branchStrategy": "trunk_based"
+  },
+  "contributors": {
+    "sourceType": "all_contributors",
+    "path": ".all-contributorsrc"
+  }
+}

package/examples/tutorial/report-excerpt.md

@@ -0,0 +1,7 @@
+# Tutorial Sample Report Excerpt
+
+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.
+
+Use the excerpt in public docs to set expectations: the sample is synthetic tutorial evidence, not observed GitHub data, and its value is showing how caveats, profile classifications, PR classes, workflow context, and CSV evidence appear in a local report bundle.

package/examples/tutorial/source-bundle.json

@@ -0,0 +1,388 @@
+{
+  "schemaVersion": "source-bundle.v1",
+  "collectedAt": "2026-06-15T12:00:00Z",
+  "source": {
+    "kind": "sample",
+    "label": "Bundled synthetic sample, not live GitHub data",
+    "metadata": {
+      "tutorial": true,
+      "publicSafety": "fully synthetic placeholder data"
+    }
+  },
+  "collector": {
+    "name": "tutorial-sample-collector",
+    "provider": "bundled-sample"
+  },
+  "targetRepository": {
+    "owner": "example-org",
+    "name": "delivery-dashboard",
+    "defaultBranch": "main",
+    "visibility": "public",
+    "analysisPullRequestLimit": 4,
+    "isValidationTarget": false
+  },
+  "repositoryMetadata": {
+    "id": "sample-repository-001",
+    "name": "delivery-dashboard",
+    "owner": "example-org",
+    "fullName": "example-org/delivery-dashboard",
+    "defaultBranch": "main",
+    "visibility": "public",
+    "isPrivate": false,
+    "htmlUrl": "https://example.com/example-org/delivery-dashboard"
+  },
+  "selection": {
+    "strategy": "bundled_tutorial_pull_requests",
+    "requestedLimit": 4,
+    "collectedCount": 4,
+    "source": "bundled tutorial sample"
+  },
+  "coverage": {
+    "status": "partial",
+    "sourceFamilies": [
+      {
+        "family": "repository_metadata",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Fictional repository identity is available for report labeling."
+      },
+      {
+        "family": "pull_request_inventory",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Four fictional merged pull requests are available for normalization and metrics."
+      },
+      {
+        "family": "pull_request_details",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Synthetic lifecycle, files, reviews, checks, and workflow summaries are populated."
+      },
+      {
+        "family": "review_threads",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Review-thread counts and comment sources are populated without comment text."
+      },
+      {
+        "family": "workflow_runs",
+        "source": "bundled tutorial sample",
+        "status": "partial",
+        "attempts": 1,
+        "diagnostics": ["One PR intentionally has unavailable workflow-run history to demonstrate coverage caveats."],
+        "downstreamImpact": "Validation-gap metrics use observed runs where present and preserve unavailable coverage where missing."
+      },
+      {
+        "family": "pr_open_diff",
+        "source": "bundled tutorial sample",
+        "status": "partial",
+        "attempts": 1,
+        "diagnostics": ["One PR intentionally lacks PR-open diff data to demonstrate partial diff-growth coverage."],
+        "downstreamImpact": "Diff-growth ratios are computed only for PRs with open-time snapshots."
+      },
+      {
+        "family": "languages",
+        "source": "bundled tutorial sample",
+        "status": "available",
+        "attempts": 1,
+        "diagnostics": [],
+        "downstreamImpact": "Language distribution is illustrative context only."
+      },
+      {
+        "family": "contributor_source",
+        "source": "bundled tutorial sample",
+        "status": "partial",
+        "attempts": 1,
+        "diagnostics": ["Synthetic contributor hints omit one reviewer to demonstrate partial profile context."],
+        "downstreamImpact": "Contributor-aware comment-source hints are available; scoring and person-level outputs are unchanged."
+      }
+    ]
+  },
+  "languageDistribution": {
+    "source": "bundled tutorial sample",
+    "bytesByLanguage": {
+      "TypeScript": 420000,
+      "JavaScript": 180000,
+      "Markdown": 52000,
+      "YAML": 18000
+    },
+    "coverage": {
+      "family": "languages",
+      "source": "bundled tutorial sample",
+      "status": "available",
+      "attempts": 1,
+      "diagnostics": [],
+      "downstreamImpact": "Language distribution is illustrative context only."
+    }
+  },
+  "contributorSource": {
+    "sourceType": "all_contributors",
+    "path": ".all-contributorsrc",
+    "coverage": {
+      "family": "contributor_source",
+      "source": "bundled tutorial sample",
+      "status": "partial",
+      "attempts": 1,
+      "diagnostics": ["Synthetic contributor hints omit one reviewer to demonstrate partial profile context."],
+      "downstreamImpact": "Contributor-aware comment-source hints are available; scoring and person-level outputs are unchanged."
+    },
+    "hintCount": 3
+  },
+  "pullRequests": [
+    {
+      "number": 101,
+      "title": "feat: add route health dashboard",
+      "author": { "login": "sample-author-ui", "type": "User" },
+      "url": "https://example.com/pull/101",
+      "state": "MERGED",
+      "createdAt": "2026-05-04T09:00:00Z",
+      "mergedAt": "2026-05-05T16:30:00Z",
+      "updatedAt": "2026-05-05T16:45:00Z",
+      "baseRefName": "main",
+      "headRefName": "sample/route-health-dashboard",
+      "headRefOid": "sample101merge",
+      "additions": 410,
+      "deletions": 96,
+      "changedFiles": 5,
+      "prOpenDiff": { "source": "direct", "confidence": "high", "additions": 190, "deletions": 44, "changedFiles": 5 },
+      "commits": [
+        { "oid": "sample101a", "authoredDate": "2026-05-04T08:40:00Z", "committedDate": "2026-05-04T08:42:00Z", "messageHeadline": "feat: add route health dashboard" },
+        { "oid": "sample101b", "authoredDate": "2026-05-05T12:15:00Z", "committedDate": "2026-05-05T12:16:00Z", "messageHeadline": "test: cover delayed route states" }
+      ],
+      "files": [
+        { "path": "apps/web/src/routes/RouteHealthPanel.tsx", "additions": 140, "deletions": 22, "changeType": "ADDED" },
+        { "path": "apps/web/src/routes/RouteHealthChart.tsx", "additions": 94, "deletions": 16, "changeType": "ADDED" },
+        { "path": "services/api/src/routes/health-summary.ts", "additions": 78, "deletions": 18, "changeType": "MODIFIED" },
+        { "path": "tests/integration/route-health.test.ts", "additions": 82, "deletions": 20, "changeType": "ADDED" },
+        { "path": "CHANGELOG.md", "additions": 16, "deletions": 20, "changeType": "MODIFIED" }
+      ],
+      "reviews": [
+        { "id": "sample-review-101-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-04T14:20:00Z", "state": "CHANGES_REQUESTED", "commitOid": "sample101a", "generatedCommentCount": 0, "failedAttempt": true },
+        { "id": "sample-review-101-b", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-05T15:20:00Z", "state": "APPROVED", "commitOid": "sample101b", "generatedCommentCount": 0, "failedAttempt": false }
+      ],
+      "reviewThreads": {
+        "source": "bundled tutorial sample:review_threads",
+        "totalCount": 2,
+        "nodes": [
+          { "id": "sample-thread-101-a", "isResolved": true, "isOutdated": false, "path": "apps/web/src/routes/RouteHealthPanel.tsx", "line": 88, "comments": [
+            { "databaseId": "sample-comment-101-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "path": "apps/web/src/routes/RouteHealthPanel.tsx", "line": 88, "originalLine": 88, "createdAt": "2026-05-04T14:21:00Z", "updatedAt": "2026-05-04T14:21:00Z", "url": "https://example.com/pull/101#discussion-sample-101-a" },
+            { "databaseId": "sample-comment-101-b", "author": { "login": "sample-author-ui", "type": "User" }, "path": "apps/web/src/routes/RouteHealthPanel.tsx", "line": 88, "originalLine": 88, "createdAt": "2026-05-05T12:18:00Z", "updatedAt": "2026-05-05T12:18:00Z", "url": "https://example.com/pull/101#discussion-sample-101-b" }
+          ] },
+          { "id": "sample-thread-101-b", "isResolved": true, "isOutdated": true, "path": "services/api/src/routes/health-summary.ts", "line": 41, "comments": [
+            { "databaseId": "sample-comment-101-c", "author": { "login": "sample-reviewer-b", "type": "User" }, "path": "services/api/src/routes/health-summary.ts", "line": 41, "originalLine": 41, "createdAt": "2026-05-04T15:02:00Z", "updatedAt": "2026-05-04T15:02:00Z", "url": "https://example.com/pull/101#discussion-sample-101-c" }
+          ] }
+        ]
+      },
+      "statusCheckRollup": [
+        { "__typename": "CheckRun", "name": "unit", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-04T09:10:00Z", "completedAt": "2026-05-04T09:16:00Z" },
+        { "__typename": "CheckRun", "name": "integration", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "FAILURE", "startedAt": "2026-05-04T09:12:00Z", "completedAt": "2026-05-04T09:24:00Z" },
+        { "__typename": "CheckRun", "name": "integration", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-05T12:20:00Z", "completedAt": "2026-05-05T12:31:00Z" }
+      ],
+      "workflowRuns": {
+        "source": "bundled tutorial sample:workflow_runs",
+        "totalCount": 2,
+        "conclusions": { "success": 1, "failure": 1 },
+        "runs": [
+          { "id": "sample-run-101-a", "name": "CI", "workflowName": "CI", "headSha": "sample101a", "headBranch": "sample/route-health-dashboard", "event": "pull_request", "status": "completed", "conclusion": "failure", "createdAt": "2026-05-04T09:10:00Z", "updatedAt": "2026-05-04T09:24:00Z", "runStartedAt": "2026-05-04T09:12:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-101-a" },
+          { "id": "sample-run-101-b", "name": "CI", "workflowName": "CI", "headSha": "sample101b", "headBranch": "sample/route-health-dashboard", "event": "pull_request", "status": "completed", "conclusion": "success", "createdAt": "2026-05-05T12:20:00Z", "updatedAt": "2026-05-05T12:31:00Z", "runStartedAt": "2026-05-05T12:21:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-101-b" }
+        ]
+      },
+      "coverage": {
+        "prOpenDiff": { "family": "pr_open_diff", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Diff-growth metrics can compare open and merge sizes." },
+        "reviewThreads": { "family": "review_threads", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Review-thread evidence is available." },
+        "workflowRuns": { "family": "workflow_runs", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Workflow-run evidence is available." }
+      }
+    },
+    {
+      "number": 102,
+      "title": "fix: retry stalled dispatch jobs",
+      "author": { "login": "sample-author-api", "type": "User" },
+      "url": "https://example.com/pull/102",
+      "state": "MERGED",
+      "createdAt": "2026-05-07T10:00:00Z",
+      "mergedAt": "2026-05-07T18:10:00Z",
+      "updatedAt": "2026-05-07T18:20:00Z",
+      "baseRefName": "main",
+      "headRefName": "sample/retry-dispatch-jobs",
+      "headRefOid": "sample102merge",
+      "additions": 126,
+      "deletions": 34,
+      "changedFiles": 4,
+      "prOpenDiff": { "source": "direct", "confidence": "high", "additions": 120, "deletions": 30, "changedFiles": 4 },
+      "commits": [
+        { "oid": "sample102a", "authoredDate": "2026-05-07T09:45:00Z", "committedDate": "2026-05-07T09:46:00Z", "messageHeadline": "fix: retry stalled dispatch jobs" },
+        { "oid": "sample102b", "authoredDate": "2026-05-07T15:10:00Z", "committedDate": "2026-05-07T15:12:00Z", "messageHeadline": "test: cover retry backoff" }
+      ],
+      "files": [
+        { "path": "workers/dispatch/retry.ts", "additions": 58, "deletions": 18, "changeType": "MODIFIED" },
+        { "path": "services/api/src/jobs/dispatch.ts", "additions": 24, "deletions": 8, "changeType": "MODIFIED" },
+        { "path": "tests/integration/dispatch-retry.test.ts", "additions": 42, "deletions": 8, "changeType": "ADDED" },
+        { "path": "docs/initiatives/retry-jobs/checklist.md", "additions": 2, "deletions": 0, "changeType": "ADDED" }
+      ],
+      "reviews": [
+        { "id": "sample-review-102-a", "author": { "login": "sample-reviewer-b", "type": "User" }, "submittedAt": "2026-05-07T13:00:00Z", "state": "COMMENTED", "commitOid": "sample102a", "generatedCommentCount": 0, "failedAttempt": false },
+        { "id": "sample-review-102-b", "author": { "login": "sample-reviewer-b", "type": "User" }, "submittedAt": "2026-05-07T17:40:00Z", "state": "APPROVED", "commitOid": "sample102b", "generatedCommentCount": 0, "failedAttempt": false }
+      ],
+      "reviewThreads": {
+        "source": "bundled tutorial sample:review_threads",
+        "totalCount": 1,
+        "nodes": [
+          { "id": "sample-thread-102-a", "isResolved": true, "isOutdated": false, "path": "workers/dispatch/retry.ts", "line": 30, "comments": [
+            { "databaseId": "sample-comment-102-a", "author": { "login": "sample-reviewer-b", "type": "User" }, "path": "workers/dispatch/retry.ts", "line": 30, "originalLine": 30, "createdAt": "2026-05-07T13:01:00Z", "updatedAt": "2026-05-07T13:01:00Z", "url": "https://example.com/pull/102#discussion-sample-102-a" },
+            { "databaseId": "sample-comment-102-b", "author": { "login": "sample-author-api", "type": "User" }, "path": "workers/dispatch/retry.ts", "line": 30, "originalLine": 30, "createdAt": "2026-05-07T15:15:00Z", "updatedAt": "2026-05-07T15:15:00Z", "url": "https://example.com/pull/102#discussion-sample-102-b" }
+          ] }
+        ]
+      },
+      "statusCheckRollup": [
+        { "__typename": "CheckRun", "name": "unit", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-07T10:10:00Z", "completedAt": "2026-05-07T10:16:00Z" }
+      ],
+      "workflowRuns": {
+        "source": "bundled tutorial sample:workflow_runs",
+        "totalCount": 1,
+        "conclusions": { "success": 1 },
+        "runs": [
+          { "id": "sample-run-102-a", "name": "CI", "workflowName": "CI", "headSha": "sample102b", "headBranch": "sample/retry-dispatch-jobs", "event": "pull_request", "status": "completed", "conclusion": "success", "createdAt": "2026-05-07T15:20:00Z", "updatedAt": "2026-05-07T15:29:00Z", "runStartedAt": "2026-05-07T15:21:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-102-a" }
+        ]
+      },
+      "coverage": {
+        "prOpenDiff": { "family": "pr_open_diff", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Diff-growth metrics can compare open and merge sizes." },
+        "reviewThreads": { "family": "review_threads", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Review-thread evidence is available." },
+        "workflowRuns": { "family": "workflow_runs", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Workflow-run evidence is available." }
+      }
+    },
+    {
+      "number": 103,
+      "title": "test: add billing webhook contract coverage",
+      "author": { "login": "sample-author-test", "type": "User" },
+      "url": "https://example.com/pull/103",
+      "state": "MERGED",
+      "createdAt": "2026-05-10T11:00:00Z",
+      "mergedAt": "2026-05-10T14:40:00Z",
+      "updatedAt": "2026-05-10T14:45:00Z",
+      "baseRefName": "main",
+      "headRefName": "sample/billing-webhook-tests",
+      "headRefOid": "sample103merge",
+      "additions": 88,
+      "deletions": 10,
+      "changedFiles": 3,
+      "prOpenDiff": { "source": "unavailable", "confidence": "unavailable", "reason": "Open-time snapshot intentionally omitted from the bundled sample." },
+      "commits": [
+        { "oid": "sample103a", "authoredDate": "2026-05-10T10:40:00Z", "committedDate": "2026-05-10T10:41:00Z", "messageHeadline": "test: add billing webhook contract coverage" }
+      ],
+      "files": [
+        { "path": "tests/integration/billing-webhooks.test.ts", "additions": 72, "deletions": 4, "changeType": "ADDED" },
+        { "path": "services/api/src/billing/webhook-fixtures.ts", "additions": 10, "deletions": 4, "changeType": "MODIFIED" },
+        { "path": "packages/generated-client/billing.ts", "additions": 6, "deletions": 2, "changeType": "MODIFIED" }
+      ],
+      "reviews": [
+        { "id": "sample-review-103-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-10T13:30:00Z", "state": "APPROVED", "commitOid": "sample103a", "generatedCommentCount": 0, "failedAttempt": false }
+      ],
+      "reviewThreads": { "source": "bundled tutorial sample:review_threads", "totalCount": 0, "nodes": [] },
+      "statusCheckRollup": [
+        { "__typename": "CheckRun", "name": "unit", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-10T11:10:00Z", "completedAt": "2026-05-10T11:15:00Z" }
+      ],
+      "workflowRuns": {
+        "source": "unavailable",
+        "totalCount": null,
+        "conclusions": {},
+        "runs": []
+      },
+      "coverage": {
+        "prOpenDiff": { "family": "pr_open_diff", "source": "bundled tutorial sample", "status": "unavailable", "attempts": 1, "diagnostics": ["Open-time snapshot intentionally omitted from the bundled sample."], "downstreamImpact": "Diff-growth metrics are unavailable for this PR." },
+        "reviewThreads": { "family": "review_threads", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Review-thread evidence is available and shows zero threads." },
+        "workflowRuns": { "family": "workflow_runs", "source": "bundled tutorial sample", "status": "unavailable", "attempts": 1, "diagnostics": ["Workflow-run history intentionally omitted for this PR."], "downstreamImpact": "Validation-gap metrics preserve unavailable workflow coverage." }
+      }
+    },
+    {
+      "number": 104,
+      "title": "feat: consolidate dispatch settings",
+      "author": { "login": "sample-author-platform", "type": "User" },
+      "url": "https://example.com/pull/104",
+      "state": "MERGED",
+      "createdAt": "2026-05-14T08:00:00Z",
+      "mergedAt": "2026-05-17T19:00:00Z",
+      "updatedAt": "2026-05-17T19:15:00Z",
+      "baseRefName": "main",
+      "headRefName": "sample/consolidate-dispatch-settings",
+      "headRefOid": "sample104merge",
+      "additions": 980,
+      "deletions": 420,
+      "changedFiles": 8,
+      "prOpenDiff": { "source": "direct", "confidence": "high", "additions": 260, "deletions": 90, "changedFiles": 6 },
+      "commits": [
+        { "oid": "sample104a", "authoredDate": "2026-05-14T07:45:00Z", "committedDate": "2026-05-14T07:46:00Z", "messageHeadline": "feat: consolidate dispatch settings" },
+        { "oid": "sample104b", "authoredDate": "2026-05-15T10:20:00Z", "committedDate": "2026-05-15T10:22:00Z", "messageHeadline": "fix: split overloaded settings model" },
+        { "oid": "sample104c", "authoredDate": "2026-05-16T16:30:00Z", "committedDate": "2026-05-16T16:31:00Z", "messageHeadline": "test: cover settings migration" },
+        { "oid": "sample104d", "authoredDate": "2026-05-17T13:00:00Z", "committedDate": "2026-05-17T13:02:00Z", "messageHeadline": "ci: repair migration fixture" }
+      ],
+      "files": [
+        { "path": "apps/web/src/settings/DispatchSettingsPage.tsx", "additions": 210, "deletions": 90, "changeType": "MODIFIED" },
+        { "path": "apps/web/src/settings/DispatchSettingsForm.tsx", "additions": 180, "deletions": 70, "changeType": "ADDED" },
+        { "path": "services/api/src/settings/dispatch-settings.ts", "additions": 190, "deletions": 88, "changeType": "MODIFIED" },
+        { "path": "workers/dispatch/settings-sync.ts", "additions": 150, "deletions": 64, "changeType": "ADDED" },
+        { "path": "tests/integration/dispatch-settings.test.ts", "additions": 120, "deletions": 30, "changeType": "ADDED" },
+        { "path": ".github/workflows/dispatch-settings.yml", "additions": 62, "deletions": 20, "changeType": "ADDED" },
+        { "path": "docs/initiatives/dispatch-settings/prd.md", "additions": 48, "deletions": 22, "changeType": "MODIFIED" },
+        { "path": "packages/generated-client/settings.ts", "additions": 20, "deletions": 36, "changeType": "MODIFIED" }
+      ],
+      "reviews": [
+        { "id": "sample-review-104-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-14T16:00:00Z", "state": "CHANGES_REQUESTED", "commitOid": "sample104a", "generatedCommentCount": 0, "failedAttempt": true },
+        { "id": "sample-review-104-b", "author": { "login": "sample-reviewer-b", "type": "User" }, "submittedAt": "2026-05-15T14:00:00Z", "state": "CHANGES_REQUESTED", "commitOid": "sample104b", "generatedCommentCount": 0, "failedAttempt": true },
+        { "id": "sample-review-104-c", "author": { "login": "sample-reviewer-a", "type": "User" }, "submittedAt": "2026-05-16T18:30:00Z", "state": "COMMENTED", "commitOid": "sample104c", "generatedCommentCount": 0, "failedAttempt": false },
+        { "id": "sample-review-104-d", "author": { "login": "sample-reviewer-b", "type": "User" }, "submittedAt": "2026-05-17T17:45:00Z", "state": "APPROVED", "commitOid": "sample104d", "generatedCommentCount": 0, "failedAttempt": false }
+      ],
+      "reviewThreads": {
+        "source": "bundled tutorial sample:review_threads",
+        "totalCount": 3,
+        "nodes": [
+          { "id": "sample-thread-104-a", "isResolved": true, "isOutdated": true, "path": "services/api/src/settings/dispatch-settings.ts", "line": 65, "comments": [
+            { "databaseId": "sample-comment-104-a", "author": { "login": "sample-reviewer-a", "type": "User" }, "path": "services/api/src/settings/dispatch-settings.ts", "line": 65, "originalLine": 65, "createdAt": "2026-05-14T16:02:00Z", "updatedAt": "2026-05-14T16:02:00Z", "url": "https://example.com/pull/104#discussion-sample-104-a" },
+            { "databaseId": "sample-comment-104-b", "author": { "login": "sample-author-platform", "type": "User" }, "path": "services/api/src/settings/dispatch-settings.ts", "line": 65, "originalLine": 65, "createdAt": "2026-05-15T10:24:00Z", "updatedAt": "2026-05-15T10:24:00Z", "url": "https://example.com/pull/104#discussion-sample-104-b" }
+          ] },
+          { "id": "sample-thread-104-b", "isResolved": true, "isOutdated": false, "path": "apps/web/src/settings/DispatchSettingsForm.tsx", "line": 112, "comments": [
+            { "databaseId": "sample-comment-104-c", "author": { "login": "sample-reviewer-b", "type": "User" }, "path": "apps/web/src/settings/DispatchSettingsForm.tsx", "line": 112, "originalLine": 112, "createdAt": "2026-05-15T14:05:00Z", "updatedAt": "2026-05-15T14:05:00Z", "url": "https://example.com/pull/104#discussion-sample-104-c" },
+            { "databaseId": "sample-comment-104-d", "author": { "login": "sample-author-platform", "type": "User" }, "path": "apps/web/src/settings/DispatchSettingsForm.tsx", "line": 112, "originalLine": 112, "createdAt": "2026-05-16T16:40:00Z", "updatedAt": "2026-05-16T16:40:00Z", "url": "https://example.com/pull/104#discussion-sample-104-d" }
+          ] },
+          { "id": "sample-thread-104-c", "isResolved": false, "isOutdated": false, "path": ".github/workflows/dispatch-settings.yml", "line": 18, "comments": [
+            { "databaseId": "sample-comment-104-e", "author": { "login": "sample-ci-bot", "type": "Bot" }, "path": ".github/workflows/dispatch-settings.yml", "line": 18, "originalLine": 18, "createdAt": "2026-05-17T13:10:00Z", "updatedAt": "2026-05-17T13:10:00Z", "url": "https://example.com/pull/104#discussion-sample-104-e" }
+          ] }
+        ]
+      },
+      "statusCheckRollup": [
+        { "__typename": "CheckRun", "name": "unit", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "FAILURE", "startedAt": "2026-05-14T08:10:00Z", "completedAt": "2026-05-14T08:16:00Z" },
+        { "__typename": "CheckRun", "name": "integration", "context": null, "workflowName": "CI", "status": "COMPLETED", "conclusion": "FAILURE", "startedAt": "2026-05-14T08:12:00Z", "completedAt": "2026-05-14T08:28:00Z" },
+        { "__typename": "CheckRun", "name": "migration", "context": null, "workflowName": "Migration checks", "status": "COMPLETED", "conclusion": "SUCCESS", "startedAt": "2026-05-17T13:10:00Z", "completedAt": "2026-05-17T13:24:00Z" }
+      ],
+      "workflowRuns": {
+        "source": "bundled tutorial sample:workflow_runs",
+        "totalCount": 4,
+        "conclusions": { "success": 1, "failure": 2, "cancelled": 1 },
+        "runs": [
+          { "id": "sample-run-104-a", "name": "CI", "workflowName": "CI", "headSha": "sample104a", "headBranch": "sample/consolidate-dispatch-settings", "event": "pull_request", "status": "completed", "conclusion": "failure", "createdAt": "2026-05-14T08:10:00Z", "updatedAt": "2026-05-14T08:28:00Z", "runStartedAt": "2026-05-14T08:12:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-104-a" },
+          { "id": "sample-run-104-b", "name": "CI", "workflowName": "CI", "headSha": "sample104b", "headBranch": "sample/consolidate-dispatch-settings", "event": "pull_request", "status": "completed", "conclusion": "failure", "createdAt": "2026-05-15T10:30:00Z", "updatedAt": "2026-05-15T10:48:00Z", "runStartedAt": "2026-05-15T10:31:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-104-b" },
+          { "id": "sample-run-104-c", "name": "CI", "workflowName": "CI", "headSha": "sample104c", "headBranch": "sample/consolidate-dispatch-settings", "event": "pull_request", "status": "completed", "conclusion": "cancelled", "createdAt": "2026-05-16T16:36:00Z", "updatedAt": "2026-05-16T16:39:00Z", "runStartedAt": "2026-05-16T16:37:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-104-c" },
+          { "id": "sample-run-104-d", "name": "Migration checks", "workflowName": "Migration checks", "headSha": "sample104d", "headBranch": "sample/consolidate-dispatch-settings", "event": "pull_request", "status": "completed", "conclusion": "success", "createdAt": "2026-05-17T13:10:00Z", "updatedAt": "2026-05-17T13:24:00Z", "runStartedAt": "2026-05-17T13:11:00Z", "htmlUrl": "https://example.com/actions/runs/sample-run-104-d" }
+        ]
+      },
+      "coverage": {
+        "prOpenDiff": { "family": "pr_open_diff", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Diff-growth metrics can compare open and merge sizes." },
+        "reviewThreads": { "family": "review_threads", "source": "bundled tutorial sample", "status": "available", "attempts": 1, "diagnostics": [], "downstreamImpact": "Review-thread evidence is available." },
+        "workflowRuns": { "family": "workflow_runs", "source": "bundled tutorial sample", "status": "partial", "attempts": 1, "diagnostics": ["One cancelled run is included to demonstrate validation caveats."], "downstreamImpact": "Validation-gap metrics include observed failed and cancelled workflow runs." }
+      }
+    }
+  ],
+  "raw": {
+    "sample": {
+      "description": "Fictional tutorial data for Delivery Friction Analyzer.",
+      "containsPrivateData": false
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Local GitHub pull request analytics for delivery friction reports.",
   "license": "MIT",
   "type": "module",
@@ -10,6 +10,7 @@
   "files": [
     "src",
     "schemas",
+    "examples/tutorial",
     "docs/contracts",
     "docs/reference",
     "fixtures/github/mcp-writing/profile.json",

package/release-log.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+### 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.
+- Why it matters: Maintainers can review and ship a public-safe sample report experience without relying on private repository access or live GitHub data.
+- Who is affected: Maintainers preparing the tutorial sample experience and future users who inspect the bundled sample artifacts after sample CLI wiring lands.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/61
+
 ### 2026-06-26 — Generic Source Bundle Report Wording
 
 - What changed: Report Markdown, methodology-adjacent contract docs, and CSV coverage expectations now use generic source-bundle and source-family wording for `source-bundle.v1`, including `collectionCoverage.status` and `collectionCoverage.sourceFamilies`.

package/src/cli/analyze-github.js

@@ -25,8 +25,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",
@@ -60,6 +64,7 @@ const BOOLEAN_OPTIONS = new Set([
 ]);
 
 const CLI_OPTION_KEYS = Object.freeze({
+  source: "source",
   repo: "repository",
   limit: "limit",
   profile: "profilePath",
@@ -114,10 +119,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.
@@ -137,6 +145,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,
@@ -215,6 +231,7 @@ export function parseAnalyzeGithubArgs(argv) {
   }
 
   const parsed = {
+    source: options.source,
     repository: options.repo,
     limit: options.limit === undefined ? undefined : Number(options.limit),
     profilePath: options.profile,
@@ -228,6 +245,7 @@ export function parseAnalyzeGithubArgs(argv) {
   };
   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 +426,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 +452,71 @@ 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.excludedPrClasses?.length
+      || providedOptions.has("dryRun")
+      || providedOptions.has("isValidationTarget")
+      || providedOptions.has("interactive")
+      || providedOptions.has("presetPath")
+      || providedOptions.has("savePresetPath")
+      || 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.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 configuredPrClasses(repositoryProfile) {
   const rules = Array.isArray(repositoryProfile?.prClasses) ? repositoryProfile.prClasses : [];
   return new Set(rules.map(rule => rule.class));
@@ -1444,6 +1533,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 +1574,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(),
@@ -1541,43 +1674,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 +1698,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 +1807,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 +1883,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"),