## Why now The [provider-contract-widening spec](docs/development/specs/2026-07-22-provider-contract-widening.md) parked `PullRequests`, `Repositories` and `Contents`, with the first open question being *"Which concrete consumer justifies it? (Nothing today — this is why it is parked.)"* There is one now. **phpbotscout** defines its knowledge corpus by a predicate rather than a curated list: a repository qualifies if it is in the `phpboyscout` group, is reported public by the API, carries a `zensical.toml`, and publishes a documentation site. The corpus grows as the toolkit grows with no configuration change — which requires enumerating the namespace rather than being told what is in it. That project's corpus validation was explicit that enumeration must come from the API and never from disk. A local checkout cannot answer whether a repository is still public, still in the namespace, or even which project it is: several working directories in that estate resolve to a repository with a different name, and a repository made private yesterday looks identical on disk. This matters more than convenience. phpbotscout's predicate is a security boundary — `phpboyscout/infra` carries a `zensical.toml` and publishes a docsite, so it satisfies every positive clause and is kept out by the exclusion list alone. The visibility check has to be live, which means it has to be an API call. ## What is needed Two of the three parked capabilities. `PullRequests` stays parked. ```go // Repositories is an OPTIONAL capability implemented by providers that can // enumerate the repositories in a namespace. type Repositories interface { ListRepositories(ctx context.Context, namespace string, opts ListOptions) ([]Repository, error) } // Contents is an OPTIONAL capability implemented by providers that can read a // single file at a ref without cloning. type Contents interface { GetFile(ctx context.Context, owner, repo, path, ref string) ([]byte, error) } ``` `Contents` is what avoids cloning every candidate in a namespace just to discover it has no `zensical.toml`. ### Repository Provider-neutral, carrying what a caller needs in order to decide whether to use a repository at all — not everything a forge knows about one. ```go type Repository struct { // Path is the canonical namespace path the API reported. It is the identity // a caller keys on: forges redirect renamed and transferred projects, so the // path a caller supplied may not be the path that answers. Path string Name string Description string URL string // web URL, for humans and citations CloneURL string DefaultBranch string Visibility Visibility Archived bool // SiteURL is the published documentation site, empty when there is none. SiteURL string } type Visibility string const ( VisibilityPublic Visibility = "public" VisibilityInternal Visibility = "internal" VisibilityPrivate Visibility = "private" ) ``` `Visibility` is a named type rather than a bare string because callers make security decisions on it, and a typo in a string comparison there is a disclosure rather than a bug. `internal` is included because GitLab has it and it is *not* public; flattening to a boolean loses the distinction a caller most needs. ### ListOptions ```go type ListOptions struct { IncludeSubgroups bool // GitLab has them, GitHub does not IncludeArchived bool // excluded by default } ``` Pagination is the provider's problem. `ListRepositories` returns the complete set rather than making every caller write a loop it would get wrong. ## Open questions 1. **How should `SiteURL` be populated?** GitLab reports Pages from a separate endpoint, so it is an extra request per repository. Options: a `ListOptions.WithSiteURL` flag so the cost is opt-in and visible at the call site; populate always; or a separate `Pages` capability. The flag was the working proposal, and it is the least settled part of the design. 2. **`GetFile` returning `[]byte` or a reader?** Bytes are simpler and these are configuration files; a reader suits large files, which is not this capability's job. 3. **Is `Archived` enough, or is `LastActivityAt` worth adding?** A repository can be unarchived and abandoned. Cheap now, awkward later. ## Scope Implement in `forge-gitlab` only. Other providers implement neither and remain conformant — that is the capability pattern working as intended, not a gap. Add a conformance entry per capability, including that a provider not implementing one is still valid. Deliberately out of scope: write operations, repository creation, a search capability, and `PullRequests`. ## Consumer phpbotscout phase 2 (knowledge index). Its discovery work is blocked on this and will consume the released capability rather than shimming a local implementation.