delivery-friction-analyzer 0.16.2 → 0.16.3

package/README.md

@@ -21,36 +21,36 @@ For public repositories, ordinary read access is usually enough. Private reposit
 
 ## Quickstart
 
-### Try the sample target
+### Guided setup
 
-From this repository, install dependencies and run the analyzer against the sample validation target:
+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 -- \
-  --repo hannasdev/mcp-writing \
+  --repo owner/name \
   --limit 30 \
-  --profile fixtures/github/mcp-writing/profile.json \
-  --out reports/mcp-writing
+  --profile profiles/owner-name.json \
+  --out reports/owner-name \
+  --interactive \
+  --dry-run
 ```
 
-Open `reports/mcp-writing/friction-report.md` first. It is the main human-readable report. Use the JSON and CSV files when you want to audit a finding, compare PRs, or build follow-up analysis.
+If the profile path does not exist, interactive setup can create a minimal `repository-profile.v1` profile. `--dry-run` validates repository access, profile JSON, output directory writability, and a small sample of GitHub API coverage without writing the full report bundle. When the profile looks right, rerun the command without `--dry-run`.
 
-### Analyze your own repository
+### Run the analysis
 
-For a guided first run in a local terminal, let interactive setup create or confirm the repository profile:
+After you have a repository profile, run the analyzer against the target repository:
 
 ```sh
 npm run analyze:github -- \
-  --interactive \
   --repo owner/name \
   --limit 30 \
   --profile profiles/owner-name.json \
-  --out reports/owner-name \
-  --dry-run
+  --out reports/owner-name
 ```
 
-If the profile path does not exist, interactive setup can create a minimal `repository-profile.v1` profile. `--dry-run` validates repository access, profile JSON, output directory writability, and a small sample of GitHub API coverage without writing the full report bundle. When the profile looks right, rerun the command without `--dry-run`.
+Open `reports/owner-name/friction-report.md` first. It is the main human-readable report. Use the JSON and CSV files when you want to audit a finding, compare PRs, or build follow-up analysis.
 
 To run the CLI from another project with the npm package, pass the same choices as explicit flags:
 
@@ -78,7 +78,7 @@ Profiles can define:
 
 For a new repository, the easiest path is the guided `--interactive --dry-run` command in Quickstart. If the profile path does not exist, interactive setup asks whether to create it, then writes a minimal `repository-profile.v1` profile with user-provided workflow context and optional release PR title rules. It may create the output directory and briefly write then remove a temporary probe file to confirm writability. When interactive setup saves or generates a profile during a dry run, the completion output prints the saved profile path so you can inspect and edit it before a full run.
 
-Use `fixtures/github/mcp-writing/profile.json` as a starting point when you prefer to copy an existing profile by hand. The full profile format is documented in `docs/reference/repository-profile.md`, and the schema lives at `schemas/repository-profile.schema.json`.
+Use `docs/reference/repository-profile.md` and `schemas/repository-profile.schema.json` when you prefer to create a profile by hand. Existing profiles and fixtures in this repository are internal validation examples; copy them only if their repository-specific assumptions match your target.
 
 ## Outputs
 
@@ -163,7 +163,7 @@ The current product focus is a maintainer workflow:
 
 The product should eventually combine GitHub delivery friction with token and model usage, but GitHub-only analytics remain the active validation surface.
 
-`hannasdev/mcp-writing` remains the first validation target and fixture source, not product-specific scope.
+`hannasdev/mcp-writing` remains an internal validation target and fixture source, not a public tutorial path or product-specific scope.
 
 The existing metrics-summary-only report command remains available for fixture and advanced workflows:
 

package/docs/contracts/target-repository.md

@@ -11,15 +11,15 @@ The local analyzer accepts a target repository and a pull request sample size. T
 - `defaultBranch`: expected default branch for merge-base and branch lookup context.
 - `visibility`: `public`, `private`, or `unknown`.
 - `analysisPullRequestLimit`: latest merged pull request count from 1 to 100, supplied by the live CLI as `--limit`.
-- `isValidationTarget`: optional flag for fixture-source repositories such as `hannasdev/mcp-writing`.
+- `isValidationTarget`: optional metadata flag for internal validation or fixture-source repositories such as `hannasdev/mcp-writing`. It does not bypass target repository validation.
 
 Schema: `schemas/target-repository.schema.json`. Live analysis selection is latest-N merged pull requests, not a rolling day window.
 
 ## Product Repository Separation
 
-The validator rejects a target repository that exactly matches the configured product repository. For this repository, the product repository is `hannasdev/delivery-friction-analyzer`; the first validation target is `hannasdev/mcp-writing`.
+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, tells you to choose the repository you want to measure with `--repo owner/name`, and confirms that no GitHub data was collected. 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, 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.
 
 ## Degraded Behavior
 

package/docs/reference/github-data-inventory.md

@@ -1,6 +1,6 @@
 # GitHub Data Inventory
 
-Checked against `hannasdev/mcp-writing` on 2026-06-08 with `gh` authenticated as `hannasdev`.
+Internal validation inventory was checked against `hannasdev/mcp-writing` on 2026-06-08 with `gh` authenticated as `hannasdev`. This repository is fixture and calibration context, not the public tutorial target.
 
 ## API Fields
 

package/docs/reference/release-automation.md

@@ -9,7 +9,7 @@ The npm package allowlist includes:
 - runtime source in `src`;
 - JSON schemas in `schemas`;
 - public contract and reference docs in `docs/contracts` and `docs/reference`;
-- the sample repository profile at `fixtures/github/mcp-writing/profile.json`;
+- the internal validation repository profile at `fixtures/github/mcp-writing/profile.json`;
 - `LICENSE`;
 - `README.md`;
 - `release-log.md`.

package/package.json

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

package/release-log.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### 2026-06-23 — Tutorial Target Guidance
+
+- What changed: Public quickstart guidance no longer depends on `hannasdev/mcp-writing`, and product-repository rejection plus `--validation-target` help now make the analysis boundary clearer.
+- Why it matters: First-time users and maintainers get a clearer path for learning the CLI without confusing internal validation history, product-repository guardrails, or validation-target metadata for an override.
+- Who is affected: Users running the CLI for the first time and maintainers reviewing first-run documentation or help text.
+- Action needed: None.
+- PR: #59
+
 ### 2026-06-21 — Done Initiative Hygiene Guard
 
 - What changed: `npm test` now enforces completed initiative documentation hygiene, and `AGENTS.md` documents how shipped, deferred, future-decision, backlog-linked, and intentionally omitted items should be recorded in done initiative docs.

package/src/cli/analyze-github.js

@@ -125,7 +125,7 @@ Options:
   --dry-run                 Validate inputs and sample GitHub coverage without writing artifacts.
   --no-dry-run              Disable dry-run mode when a preset enabled it.
   --metadata-only           Alias for --dry-run.
-  --validation-target       Mark the target repository as a validation target in output metadata.
+  --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.
   --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.

package/src/contracts/target-repository.js

@@ -99,5 +99,5 @@ 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, not the target repository to measure. 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. Choose a different repository with --repo owner/name. No GitHub data was collected.`;
 }