feat: give the corpus an entry point and an honest description

openspec/changes/specify-documentation-homes/design.md

@@ -230,3 +230,53 @@ their genres. Rejected for now — renaming before extraction relabels documents
 that still contain requirements, and these are site routes, so the rename costs
 external links. It belongs after, when what remains is unambiguously
 description.
+
+## The corpus promised something it does not hold
+
+The `specs` README says of `openspec/specs/`:
+
+> What survives is `openspec/specs/` — the current description of how osapi-io
+> behaves, kept honest by every change that passes through.
+
+It is not that. Of the six capabilities in the corpus, five govern how work is
+done — package layout, coverage targets, continuous integration, labels,
+justfile modules, module paths, ignore files, badges. Only `sdk-standards` says
+anything about how the software behaves. A reader could learn all forty-five
+requirements and know the linting rules without learning that osapi has three
+processes or what a provider is.
+
+The gap is an artifact of sequence rather than intent. Every change so far has
+been repository standardization, and standardization produces rules about
+process. The capabilities queued next — routing, API design, provider semantics,
+domain completeness — are about behavior, and the corpus will start to resemble
+its own description.
+
+It will never fully match it. Package maps and request flows stay in the
+repositories, because writing them as requirements produces a corpus that goes
+stale on every refactor — a decision this capability already records. So the
+README is corrected to say what the corpus is: the rules the software is held
+to, with the reasoning in the archive.
+
+### An entry point, before there are twenty capabilities
+
+`openspec/` holds six capability directories and eleven archived changes, and
+nothing that says where to start. That is survivable at six and is not at
+twenty.
+
+The requirement asks for a map rather than a summary: naming each capability and
+what it covers, saying what the corpus is, and pointing at the archive for
+reasoning. A summary would restate the requirements and drift from them; a map
+stays true as long as the names do.
+
+*Alternative considered:* generate the entry point from the capability files.
+Rejected — the useful part is the sentence explaining what a capability is for
+and when to reach for it, which is not derivable from a list of `SHALL`
+statements.
+
+### Purpose sections carry the orientation
+
+The second requirement follows from the same problem. A capability opening with
+its first requirement teaches a reader who already knows the domain and no one
+else. Asking the `## Purpose` to state what the capability governs, and why that
+ground needs governing, is what makes the corpus readable rather than only
+searchable.

openspec/changes/specify-documentation-homes/specs/documentation/spec.md

@@ -143,6 +143,52 @@ what each part covers.
   navigation
 - **THEN** that navigation is the index, and no second one is maintained
 
+### Requirement: The corpus has an entry point
+
+The corpus SHALL contain a document naming every capability and what each one
+covers, so a reader arriving without knowing which capability holds what can
+find their way in.
+
+That document SHALL state what the corpus is: the rules the organization's
+software is held to, and where the reasoning behind each rule is kept. It SHALL
+NOT describe the corpus as a description of how the software behaves, because
+descriptions of current behavior stay in the repositories that hold the code.
+
+#### Scenario: A reader arrives at the corpus
+
+- **WHEN** someone opens the corpus without knowing which capability governs the
+  work they are doing
+- **THEN** an entry point names each capability and what it covers, rather than
+  requiring every capability to be opened
+
+#### Scenario: A capability is added
+
+- **WHEN** a change adds a capability to the corpus
+- **THEN** the entry point names it, so the map does not fall behind what it
+  maps
+
+#### Scenario: A reader wants to know why a rule exists
+
+- **WHEN** a requirement's reasoning matters more than its wording
+- **THEN** the entry point says the reasoning is in the archived change that
+  introduced it, rather than leaving the archive to be discovered
+
+### Requirement: A capability says what it is for before it constrains
+
+A capability SHALL open by stating what it governs and why that ground needs
+governing.
+
+A reader who does not already know the domain SHALL be able to learn what the
+capability is about from that opening, without reconstructing it from the
+requirements below.
+
+#### Scenario: A capability is read by someone new to the domain
+
+- **WHEN** a contributor opens a capability governing a subsystem they have not
+  worked in
+- **THEN** its opening explains what the subsystem is for, so the requirements
+  that follow are read with the reason for them in view
+
 ### Requirement: Documentation organisation is the repository's own
 
 The names and shape of directories inside `docs/` SHALL be chosen by the

openspec/changes/specify-documentation-homes/tasks.md

@@ -71,8 +71,19 @@
   the corpus. Done for `osapi-orchestrator`; `osapi` has no root
   `CONTRIBUTING.md` until `standardize-repository-layout` task 4.5 writes one
 
+## 4a. Make the corpus navigable
+
+- [ ] 4a.1 `specs` — write the corpus entry point naming every capability and
+  what it covers
+- [ ] 4a.2 `specs` — correct the README, which calls `openspec/specs/` "the
+  current description of how osapi-io behaves". It holds rules; five of its six
+  capabilities govern how work is done rather than how the software behaves
+- [ ] 4a.3 `specs` — confirm each capability's `## Purpose` states what it
+  governs, rather than restating its first requirement
+
 ## 5. Verification
 
 - [x] 5.1 Confirm every repository's documentation is indexed
 - [x] 5.2 Confirm no repository contains a planning directory
 - [ ] 5.3 Confirm no relocated requirement is stated in two places
+- [ ] 5.4 Confirm the entry point names every capability in the corpus