Module why 

The Why catalogue: the operational moments this tool is a response to, the audiences that recognise them and the areas they fall under, read from the index and answered as one immutable typed model.

Nothing here discovers or parses a file. The moments, audiences and areas are ordinary declarative objects of the layer — kinds moment, audience and area in share/kinds.yaml, discovered by the source classes in the repository’s sources.yaml, and already validated against their JSON Schemas by the time the index holds them. This module projects that validated metadata into typed records, resolves every reference the records make, derives every relation nobody authored, and answers queries over the result.

Built once, at the moment a crate::capability::Context is composed, and shared by every projection: the command line, the HTTP routes, the MCP tools, the derived graph and the site’s dataset are readers of this one value. A request never rebuilds it.

Two directions are kept apart on purpose. Authored is what a file says: its hook, its summary, the audiences and areas it belongs to, its signals, its examples, and the things of this repository it names. Derived is everything else — the route, the members of an audience, the moments that answer a claim, the responsibilities a moment touches, the reverse of related, every count and every facet — and none of it may be written into a source file. The schemas refuse the derived keys, and this module is where they come from instead.

Structs

Area

One operational area. Membership is never listed here either.

Audience

One audience. Membership is never listed here: it is each moment’s audiences.

Catalogue

The validated catalogue and every index derived from it. Immutable: built once from an index and a registry, read many times.

Diagnosis

What a reader’s selection implies, computed by counting rather than by inference.

Example

One concrete situation, in one audience, with what happens today and what happens instead.

FacetValue

One selectable value of one facet, with how many public moments carry it. Every filter a reader is offered is one of these; nothing anywhere lists the values by hand.

Facets

The filters the catalogue offers, derived from the records rather than declared.

Finding

One thing wrong with the catalogue, named where it is, with the nearest candidate when there is one. A finding always carries enough to fix it without searching.

Moment

One operational moment, as its file declares it plus the two facts the file cannot hold: where it came from and where it is published.

Query

What a listing is narrowed by. Every field is optional and they compose as a conjunction; the values a caller may pass are the facets the catalogue reports, never a list written anywhere.

Recommendation

One recommendation, with the moments that produced it. A recommendation with no matched_because is a recommendation nobody can check.

Signal

One observable symptom of a moment: a question a reader can answer about their own week. The questionnaire on the site and the input of why diagnose are these and nothing else.

Constants

AREA

The kind of an operational area.

AUDIENCE

The kind of an audience.

MOMENT

The kind of an operational moment.

RESERVED

The identities the section’s own routes use. A moment called one of these would claim a route the section already owns — /why/audiences/ is the taxonomy, not a moment — and the collision would show up as a page quietly replaced rather than as an error.

ROUTE

The section the catalogue is published under.

STABLE

A moment that is complete and public. Draft records are listed as drafts and counted nowhere; deprecated ones keep their route and are listed nowhere.