phpbotscout index sources¶

Lists every repository discovery found, and the exact clause of the corpus predicate that admitted or rejected it.

Usage¶

$ phpbotscout index sources
SOURCE                                VERDICT   CLAUSE      REASON
phpboyscout/go/config                 indexed   none        public, in-group, documented
phpboyscout/go/config-toml            rejected  no-docsite  no zensical.toml
phpboyscout/go/chat-platform-discord  rejected  no-docsite  no zensical.toml
phpboyscout/blog                      rejected  visibility  visibility is "private", not public
phpboyscout/iac/landing               rejected  visibility  visibility is "private", not public
phpboyscout/infra                     rejected  excluded    permanently excluded by "phpboyscout/infra"

52 of 99 sources qualify.

Why rejections are shown¶

Every candidate is listed, rejected ones included, because a source listing has to explain an absence. A repository that simply vanished from the output would send an operator hunting for a bug in discovery when the answer is that the predicate did its job.

A predicate nobody can inspect is a curated list with extra steps.

Clauses¶

Clause	Meaning
`none`	Nothing rejected it.
`excluded`	On the permanent exclusion list — `infra`, `sandbox`, `scoutdm`, `scoutdm-site`. Checked first and absolute; no later clause can readmit it, and an excluded repository is never read from at all.
`namespace`	Outside the `phpboyscout` group.
`visibility`	The forge did not report it as public. Allowlisted against `public` rather than denylisted against `private`, since `!= private` would admit both `unknown` and `internal`. This is the clause doing the real work — every exclusion-list entry is also private, so the deny list is a second lock rather than the control.
`no-docsite`	No `zensical.toml` marker.
`no-pages`	No publicly reachable documentation site.
`archived`	The forge reports it as retired.
`unresolved`	A fact the predicate needs could not be determined — the forge returned an error that was not "not found". Not a rejection on the merits: the source may well qualify, and the next run asks again.

unresolved exists because "no" and "I could not find out" demand opposite handling. Reading a repository's zensical.toml can fail with a 404 — which genuinely means no marker — or with a 500, which means nothing at all. Treating the second as the first would drop a documented repository out of the corpus silently, and a different one on the next run. The same applies to the Pages lookup, where a 403 is routine because reading Pages settings needs the Maintainer role.

archived is evaluated after the predicate rather than inside it: an archived repository is a judgement about usefulness, not about whether a source is permitted. Its documentation is unmaintained, which for a bot answering questions is worse than absent — it is confidently out of date.

Where the facts come from¶

Three forge capabilities, all optional in the contract and all required here:

Capability	Answers
`Repositories`	what is in the namespace, with visibility and archived state
`Contents`	whether the repository carries `zensical.toml`
`Sites`	where its documentation is published

A provider implementing none of them is conformant, so their absence is refused at startup rather than tolerated. Without Contents, every repository would be reported as undocumented — which reads as a fact about the repositories when it is really a fact about the provider.

Subgroups and archived repositories are both requested explicitly, because the forge excludes them by default and both defaults fail silently: the entire Go toolkit lives under phpboyscout/go/*, and a filtered listing looks exactly like a complete one.

Why a configured list is refused¶

Discovery enumerates from the forge API and will not fall back to a list of sources in your config file.

A configuration file asserting a repository is public would replace the check that keeps an infrastructure repository out of a public channel with the operator's memory. Configuration is a request to index and never an authority on visibility — a checkout cannot say whether a repository is still public, still in the group, or even which project it is, and one made private yesterday looks identical on disk.

Flags¶

sources defines no flags of its own. Global flags (--config, --debug, --output, --ci) are inherited from the root command.

Name	Description	Default
`-h`, `--help`	Help for `sources`.	`false`