Motivation
Curated sampling chooses a repeatable page set; it is not a request allowlist. Sitemap coverage and llms.txt link checks still perform independent index/link work. Users should be able to understand this before starting a scan, particularly when many product teams share a documentation host.
The Documentation at Scale draft corrects wording that curated sampling skips all discovery, but documentation alone does not expose the effective configuration after CLI overrides, check selection, and defaults.
Design Scope
Investigate a resolved-config or execution-scope summary using existing configuration and check metadata. Settle the presentation/API before adding flags or named profiles. Prioritize visibility over introducing opinionated check bundles.
Distinguish page-sample selection, index acquisition, published-link checking, coverage, and checks that can make supplementary requests. Show selected/excluded checks, sampling strategy, explicit page count, relevant limits and source overrides. Disclose that curated entries are not clipped by the discovery path/locale/version filters and are not capped by maxLinksToTest.
The summary must not claim an exact number of requests or a hard network boundary. Redirects, retries, Markdown candidates, cache reuse, and unknown index sizes make such promises unreliable.
Acceptance Criteria
- Users can inspect the effective selection and request categories without fetching discovery sources or pages merely to produce the summary.
- Explicit CLI overrides, auto-discovered and explicit configs, curated/none strategies, and check dependencies are resolved through existing machinery.
- Selecting curated pages alongside coverage or link checks clearly exposes the additional work.
- Any machine-readable representation is consistent with the human-readable summary and documented as a plan, not an execution guarantee.
- Tests cover check metadata completeness and new-check registration so the summary cannot silently drift from implemented behavior.
- Existing runs remain compatible unless a separately documented default presentation change is chosen. No new scan traffic, profile system, allowlist, or score policy is implied.
References
#120, PR #140, #141, #142, #18, #50. Design notes: working-notes/page-discovery-notes.md, Documentation at scale section. #141 describes actual discovery evidence; this issue describes intended work before execution.
Motivation
Curated sampling chooses a repeatable page set; it is not a request allowlist. Sitemap coverage and llms.txt link checks still perform independent index/link work. Users should be able to understand this before starting a scan, particularly when many product teams share a documentation host.
The Documentation at Scale draft corrects wording that curated sampling skips all discovery, but documentation alone does not expose the effective configuration after CLI overrides, check selection, and defaults.
Design Scope
Investigate a resolved-config or execution-scope summary using existing configuration and check metadata. Settle the presentation/API before adding flags or named profiles. Prioritize visibility over introducing opinionated check bundles.
Distinguish page-sample selection, index acquisition, published-link checking, coverage, and checks that can make supplementary requests. Show selected/excluded checks, sampling strategy, explicit page count, relevant limits and source overrides. Disclose that curated entries are not clipped by the discovery path/locale/version filters and are not capped by maxLinksToTest.
The summary must not claim an exact number of requests or a hard network boundary. Redirects, retries, Markdown candidates, cache reuse, and unknown index sizes make such promises unreliable.
Acceptance Criteria
References
#120, PR #140, #141, #142, #18, #50. Design notes:
working-notes/page-discovery-notes.md, Documentation at scale section. #141 describes actual discovery evidence; this issue describes intended work before execution.