@turri-dev/cli 0.1.27 → 0.2.0

package/genome/rules/concise-specs-examples.md

@@ -1,8 +1,8 @@
 ---
-description: Worked BAD to GOOD examples of concise .plain specs, one pair per conciseness failure mode
+description: Worked BAD to GOOD examples of concise ***plain, one pair per conciseness failure mode
 ---
 
-# Worked examples of concise `.plain` specs
+# Worked examples of concise ***plain
 
 `concise-specs.md` is the rule; this file is the example bank behind it. Every entry names one failure mode, shows the padded version, and shows the rewrite that carries the same information.
 
@@ -10,7 +10,7 @@ Read the pairs, not the prose: in each one, the GOOD block says everything the B
 
 The BAD blocks intentionally demonstrate the mistakes they name, including invalid syntax. Copy only from GOOD blocks.
 
-Integration specs fail in their own ways — over-precision, inlined contract data, and edge cases the provider's documentation invites. Those examples are in `concise-specs-integration-examples.md`.
+Integration ***plain fails in its own ways — over-precision, inlined contract data, and edge cases the provider's documentation invites. Those examples are in `concise-specs-integration-examples.md`.
 
 ## Padding around one fact
 
@@ -19,11 +19,14 @@ BAD:
 ```plain
 ***functional specs***
 
-- In order to provide users with a robust and seamless experience, :TaskService: exposes a comprehensive endpoint for the creation of new :Task: items.
+# create-task
+In order to provide users with a robust and seamless experience, :TaskService: exposes a comprehensive endpoint for the creation of new :Task: items.
 
-- The endpoint accepts a request and, provided that the incoming payload is valid and well-formed, proceeds to persist the :Task: appropriately.
+# persist-task
+The endpoint accepts a request and, provided that the incoming payload is valid and well-formed, proceeds to persist the :Task: appropriately.
 
-- If the payload is not valid, an appropriate error is returned to the caller so that the user is informed of the problem.
+# reject-invalid-payload
+If the payload is not valid, an appropriate error is returned to the caller so that the user is informed of the problem.
 ```
 
 GOOD:
@@ -31,13 +34,14 @@ GOOD:
 ```plain
 ***functional specs***
 
-- A :User: can create a :Task: via `POST /tasks`.
-  - The request body is a :Task: without `id`.
-  - The response is `201` with the created :Task:.
-  - A request without a name returns `400`.
+# create-task
+A :User: can create a :Task: via `POST /tasks`.
+- The request body is a :Task: without `id`.
+- The response is `201` with the created :Task:.
+- A request without a name returns `400`.
 ```
 
-Three bullets became one, and the rewrite names the method, the path, the request shape, and both status codes — none of which the padded version pinned down.
+Three functional specs became one, and the rewrite names the method, the path, the request shape, and both status codes — none of which the padded version pinned down.
 
 ## Rationale, motivation, and benefits
 
@@ -46,7 +50,8 @@ BAD:
 ```plain
 ***functional specs***
 
-- Because support staff frequently need to find customers quickly, and because scanning the full list is slow and error-prone, :CustomerDirectory: offers a search capability that greatly improves their daily workflow.
+# search-customers
+Because support staff frequently need to find customers quickly, and because scanning the full list is slow and error-prone, :CustomerDirectory: offers a search capability that greatly improves their daily workflow.
 ```
 
 GOOD:
@@ -54,7 +59,8 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :CustomerDirectory: returns :Customer: items whose name or email contains a search term, case-insensitively.
+# search-customers
+:CustomerDirectory: returns :Customer: items whose name or email contains a search term, case-insensitively.
 ```
 
 Why the feature exists changes nothing about what is built. What "search" matches does.
@@ -86,11 +92,12 @@ BAD:
 ```plain
 ***functional specs***
 
-- :OrderApi: returns a list of :Order: items over HTTP.
-  - The list contains :Order: items.
-  - If there are no :Order: items, the list is empty.
-  - Each :Order: has an `id`, which is unique.
-  - The caller receives the response after the request is sent.
+# list-orders
+:OrderApi: returns a list of :Order: items over HTTP.
+- The list contains :Order: items.
+- If there are no :Order: items, the list is empty.
+- Each :Order: has an `id`, which is unique.
+- The caller receives the response after the request is sent.
 ```
 
 GOOD:
@@ -98,8 +105,9 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :OrderApi: returns the :Order: items of the authenticated :User: via `GET /orders`, newest first.
-  - The response is `200` with a JSON array, empty when the :User: has no :Order: items.
+# list-orders
+:OrderApi: returns the :Order: items of the authenticated :User: via `GET /orders`, newest first.
+- The response is `200` with a JSON array, empty when the :User: has no :Order: items.
 ```
 
 Every cut line was already implied: a list of :Order: items contains :Order: items, an identifier identifies, and a response follows a request. What survives is what a reader could *not* have guessed — the ownership filter, the sort order, and the response shape.
@@ -113,11 +121,14 @@ BAD:
 ```plain
 ***functional specs***
 
-- :OrderService: validates all incoming data before processing it.
+# validate-input
+:OrderService: validates all incoming data before processing it.
 
-- :OrderService: handles errors and returns meaningful error messages.
+# handle-errors
+:OrderService: handles errors and returns meaningful error messages.
 
-- :OrderService: saves the :Order: to storage so that it is not lost.
+# save-order
+:OrderService: saves the :Order: to storage so that it is not lost.
 ```
 
 GOOD:
@@ -125,7 +136,8 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :OrderService: rejects an :Order: whose `total` does not equal the sum of its :OrderLine: amounts, with `422`.
+# reject-wrong-total
+:OrderService: rejects an :Order: whose `total` does not equal the sum of its :OrderLine: amounts, with `422`.
 ```
 
 Validating input, reporting errors, and persisting on a save operation belong in the `***implementation reqs***` and a baseline is assumed. If there is a specific use case for a particular operation, it should be documented there, not in the `***functional specs***`. The one fact worth stating is *which* rule is enforced and what the caller sees when it fails.
@@ -208,7 +220,7 @@ GOOD:
 - :ConformanceTests: mock every external HTTP call.
 ```
 
-Every hedge hands the renderer a decision the spec was supposed to make. A spec states one behavior.
+Every hedge hands the coding agent a decision the ***plain was supposed to make. A functional spec states one behavior.
 
 ## Ornate vocabulary
 
@@ -217,7 +229,8 @@ BAD:
 ```plain
 ***functional specs***
 
-- :ReportGenerator: is responsible for facilitating the utilization of a plurality of :DataSource: instances in order to initiate the generation of a :Report: prior to the performance of the validation of the resulting output.
+# build-report
+:ReportGenerator: is responsible for facilitating the utilization of a plurality of :DataSource: instances in order to initiate the generation of a :Report: prior to the performance of the validation of the resulting output.
 ```
 
 GOOD:
@@ -225,22 +238,24 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :ReportGenerator: builds a :Report: from one or more :DataSource: items, then validates it.
+# build-report
+:ReportGenerator: builds a :Report: from one or more :DataSource: items, then validates it.
 ```
 
 Same sequence, plain words. See the substitution table in `concise-specs.md`.
 
-## Sub-bullets that elaborate instead of disambiguating
+## Detail that elaborates instead of disambiguating
 
 BAD:
 
 ```plain
 ***functional specs***
 
-- A :User: can archive a :Project:.
-  - Archiving is an action the user performs on a project.
-  - The archive action is available to users who have access to the project.
-  - Once archived, the project is in the archived state.
+# archive-project
+A :User: can archive a :Project:.
+- Archiving is an action the user performs on a project.
+- The archive action is available to users who have access to the project.
+- Once archived, the project is in the archived state.
 ```
 
 GOOD:
@@ -248,23 +263,25 @@ GOOD:
 ```plain
 ***functional specs***
 
-- A :User: can archive a :Project: they own.
-  - An archived :Project: is excluded from :ProjectList:.
-  - Archiving a :Project: that is already archived returns `409`.
+# archive-project
+A :User: can archive a :Project: they own.
+- An archived :Project: is excluded from :ProjectList:.
+- Archiving a :Project: that is already archived returns `409`.
 ```
 
-A sub-bullet earns its line by removing an ambiguity. If it only says the parent again in more words, it is filler.
+A detail bullet earns its line by removing an ambiguity. If it only says the statement line again in more words, it is filler.
 
-## Restating the parent bullet
+## Restating the statement line
 
 BAD:
 
 ```plain
 ***functional specs***
 
-- :SessionStore: expires a :Session: 30 minutes after its last use.
-  - Sessions do not live forever; they time out.
-  - The timeout is 30 minutes.
+# expire-session
+:SessionStore: expires a :Session: 30 minutes after its last use.
+- Sessions do not live forever; they time out.
+- The timeout is 30 minutes.
 ```
 
 GOOD:
@@ -272,8 +289,9 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :SessionStore: expires a :Session: 30 minutes after its last use.
-  - A request carrying an expired :Session: returns `401`.
+# expire-session
+:SessionStore: expires a :Session: 30 minutes after its last use.
+- A request carrying an expired :Session: returns `401`.
 ```
 
 ## Synonym drift
@@ -283,23 +301,27 @@ BAD:
 ```plain
 ***functional specs***
 
-- A :User: can upload a :Document:.
+# upload-document
+A :User: can upload a :Document:.
 
-- The system stores the submitted file in :DocumentStore:.
+# store-document
+The system stores the submitted file in :DocumentStore:.
 
-- The uploaded asset is retrievable by its identifier.
+# retrieve-document
+The uploaded asset is retrievable by its identifier.
 ```
 
-Three names — `:Document:`, "file", "asset" — read as three things. A reader cannot tell whether "asset" is a fourth concept, and the renderer cannot either.
+Three names — `:Document:`, "file", "asset" — read as three things. A reader cannot tell whether "asset" is a fourth concept, and the coding agent cannot either.
 
 GOOD:
 
 ```plain
 ***functional specs***
 
-- A :User: can upload a :Document:.
-  - :DocumentStore: stores the :Document: and assigns it a :DocumentId:.
-  - A :User: can retrieve a :Document: by its :DocumentId:.
+# upload-document
+A :User: can upload a :Document:.
+- :DocumentStore: stores the :Document: and assigns it a :DocumentId:.
+- A :User: can retrieve a :Document: by its :DocumentId:.
 ```
 
 ## Meta-commentary and scope disclaimers
@@ -309,13 +331,17 @@ BAD:
 ```plain
 ***functional specs***
 
-- This spec is intentionally kept small so that it stays within the complexity limit.
+# export-csv-size-note
+This spec is intentionally kept small so that it stays within the complexity limit.
 
-- As described above, :ExportService: writes a :CsvFile:.
+# export-csv-reference
+As described above, :ExportService: writes a :CsvFile:.
 
-- No changes are made to the existing :ImportService: or to the user interface.
+# export-csv-no-changes
+No changes are made to the existing :ImportService: or to the user interface.
 
-- Future specs will extend this behavior with additional formats.
+# export-csv-future
+Future specs will extend this behavior with additional formats.
 ```
 
 GOOD:
@@ -323,12 +349,13 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :ExportService: writes the :Order: items of a :BillingPeriod: to a :CsvFile:.
-  - The header row is `id,customer,total,currency`.
-  - An empty :BillingPeriod: produces a :CsvFile: with only the header row.
+# export-csv
+:ExportService: writes the :Order: items of a :BillingPeriod: to a :CsvFile:.
+- The header row is `id,customer,total,currency`.
+- An empty :BillingPeriod: produces a :CsvFile: with only the header row.
 ```
 
-A spec describes the software, not itself. What the spec does *not* change is everything it does not mention, and what later specs will add belongs to those specs.
+***plain describes the software, not itself. What a functional spec does *not* change is everything it does not mention, and what later functional specs will add belongs to them.
 
 ## Prose and tables inside a section
 
@@ -337,13 +364,14 @@ BAD:
 ```plain
 ***functional specs***
 
-- :PricingEngine: applies discounts.
-  The discount matrix is as follows:
-  | Tier | Volume | Discount |
-  |---|---|---|
-  | Bronze | 0-99 | 0% |
-  | Silver | 100-499 | 5% |
-  | Gold | 500+ | 12% |
+# apply-discounts
+:PricingEngine: applies discounts.
+The discount matrix is as follows:
+| Tier | Volume | Discount |
+|---|---|---|
+| Bronze | 0-99 | 0% |
+| Silver | 100-499 | 5% |
+| Gold | 500+ | 12% |
 ```
 
 GOOD:
@@ -351,15 +379,16 @@ GOOD:
 ```plain
 ***functional specs***
 
-- :PricingEngine: applies the :DiscountTier: matrix in [resources/discount-tiers.json](resources/discount-tiers.json) to an :Order: total.
-  - An :Order: below the lowest tier threshold gets no discount.
+# apply-discounts
+:PricingEngine: applies the :DiscountTier: matrix in [resources/discount-tiers.json](resources/discount-tiers.json) to an :Order: total.
+- An :Order: below the lowest tier threshold gets no discount.
 ```
 
 A section holds `- ` list items. Matrices, schemas, and payloads are external artifacts and are linked from `resources/` — see `linked-resources.md`.
 
 ## Split one crowded bullet across its owning sections
 
-One bullet that mixes behavior, technology, and test policy is hard to review and partly ignored: the renderer reads each concept only from its owning section, so the unit-test and conformance-test facts below never reach the generators that need them.
+One bullet that mixes behavior, technology, and test policy is hard to review and partly ignored: turri reads each concept only from its owning section, so the unit-test and conformance-test facts below never reach the agents that need them.
 
 BAD — everything in one place:
 
@@ -372,7 +401,8 @@ BAD — everything in one place:
 
 ***functional specs***
 
-- :ImageResizer:, implemented as a Python class using Pillow with a thread pool of 4 workers, resizes an uploaded :Image: to a thumbnail, where a thumbnail is defined as a JPEG at most 256 pixels on its longest edge.
+# resize-image
+:ImageResizer:, implemented as a Python class using Pillow with a thread pool of 4 workers, resizes an uploaded :Image: to a thumbnail, where a thumbnail is defined as a JPEG at most 256 pixels on its longest edge.
 ```
 
 GOOD — each fact in the section that owns it:
@@ -394,9 +424,10 @@ GOOD — each fact in the section that owns it:
 
 ***functional specs***
 
-- :ImageResizer: produces a :Thumbnail: from an :Image:.
-  - An :Image: already within the :Thumbnail: bounds is returned unchanged.
-  - An :Image: that is not a supported format raises :UnsupportedImageError:.
+# resize-image
+:ImageResizer: produces a :Thumbnail: from an :Image:.
+- An :Image: already within the :Thumbnail: bounds is returned unchanged.
+- An :Image: that is not a supported format raises :UnsupportedImageError:.
 ```
 
 Each section now answers one question, and the definition, the mechanism, and the behavior are each one line to check instead of clauses buried in a paragraph about resizing. Use the split whenever a bullet answers more than one of *what is it*, *what does it do*, *how is it built*, and *how is it tested* — see `module-structure.md` for section ownership and canonical section order.
@@ -405,25 +436,25 @@ Use `resolve-section-ownership` to perform the split. It is not the same as spli
 
 The most common single case of this is a functional spec that states a mechanism rather than a result — a retry schedule, a cache, a token refresh. `impl-reqs.md` owns HOW; a functional spec keeps what a caller observes. `concise-specs-integration-examples.md` works through several.
 
-## Narrated acceptance tests
+## Narrated scenarios
 
 BAD:
 
 ```plain
-***acceptance tests***
+***conformance tests***
 
-- The tester should first open the application and log in with a valid account, then navigate to the projects area where they will be able to see the list of projects, and then they should create a new project by filling in the form, after which they should verify that everything worked as expected and the project shows up correctly.
+# create-project
+The tester should first open the application and log in with a valid account, then navigate to the projects area where they will be able to see the list of projects, and then they should create a new project by filling in the form, after which they should verify that everything worked as expected and the project shows up correctly.
 ```
 
 GOOD:
 
 ```plain
-***acceptance tests***
+***conformance tests***
 
-- A :User: creates a :Project: and finds it in :ProjectList:.
-  - Sign in as a :User: with no :Project: items.
-  - Create a :Project: named `Apollo`.
-  - :ProjectList: contains exactly one :Project:, named `Apollo`.
+# create-project
+A signed-in :User: with no :Project: items creates a :Project: named `Apollo` and finds it in :ProjectList:.
+- :ProjectList: contains exactly one :Project:, named `Apollo`.
 ```
 
-One narrated paragraph becomes an ordered set of checkable steps, and "everything worked as expected" becomes an assertion.
+One narrated paragraph becomes one checkable sentence, and "everything worked as expected" becomes an assertion.

package/genome/rules/concise-specs-integration-examples.md

@@ -1,22 +1,22 @@
 ---
-description: Worked BAD to GOOD examples of concise integration specs, where over-precision and obvious edge cases dominate
+description: Worked BAD to GOOD examples of concise integration ***plain, where over-precision and obvious edge cases dominate
 ---
 
-# Worked examples of concise integration specs
+# Worked examples of concise integration ***plain
 
-`concise-specs.md` is the rule and `concise-specs-examples.md` is the general example bank. This file covers integration specs only, because they fail differently.
+`concise-specs.md` is the rule and `concise-specs-examples.md` is the general example bank. This file covers integration ***plain only, because it fails differently.
 
-An integration is technically demanding, the provider's contract is large, and the author has the provider's documentation open while writing. The result is a spec that is *too precise*: status codes, field lists, retry arithmetic, and every edge case the API can produce, written out as prose bullets. It reads as rigorous and is unreviewable.
+An integration is technically demanding, the provider's contract is large, and the author has the provider's documentation open while writing. The result is ***plain that is *too precise*: status codes, field lists, retry arithmetic, and every edge case the API can produce, written out as prose bullets. It reads as rigorous and is unreviewable.
 
 Conciseness here is almost never about covering less. `integrations.md` makes edge-case coverage a hard floor — auth, environments, versioning, pagination, rate limits, the error model, retries, idempotency, webhooks, data mapping, compliance, observability. Every one of those must be covered. The lever is **where** the coverage lives:
 
-- **Shapes and enumerations go to `resources/`** — schemas, error maps, retry policy, rate-limit headers. A spec bullet links to the file; it never restates its contents.
-- **The spec keeps behavior** — what the integration does with the shape, and what a caller observes.
+- **Shapes and enumerations go to `resources/`** — schemas, error maps, retry policy, rate-limit headers. A ***plain bullet links to the file; it never restates its contents.
+- **The ***plain keeps behavior** — what the integration does with the shape, and what a caller observes.
 - **Mechanism goes to `***implementation reqs***`** — retry logic, exception hierarchies, token caching, connection handling. Integration precision is mostly HOW, and `impl-reqs.md` owns HOW. `***functional specs***` keeps only what a caller can observe.
 
-That last lever is easy to miss, so several examples below move a bullet between sections rather than shortening it. A fact in the wrong section is worse than a verbose one: the renderer reads each concept only from its owning section, so a misplaced fact is silently ignored.
+That last lever is easy to miss, so several examples below move a bullet between sections rather than shortening it. A fact in the wrong section is worse than a verbose one: turri reads each concept only from its owning section, so a misplaced fact is silently ignored.
 
-Applied consistently, a spec gets shorter as coverage goes *up*, because each new corner case adds a line to a resource file rather than a paragraph to the spec.
+Applied consistently, ***plain gets shorter as coverage goes *up*, because each new corner case adds a line to a resource file rather than a paragraph to the ***plain.
 
 The BAD blocks intentionally demonstrate the mistakes they name, including invalid syntax. Copy only from GOOD blocks.
 
@@ -31,11 +31,14 @@ BAD:
 
 ***functional specs***
 
-- :ProviderClient: retries the request when :ProviderApi: returns 408, 425, 429, 500, 502, 503, or 504, and also on connection errors, DNS failures, socket timeouts, TLS handshake failures, and connection resets.
+# retry-transient-errors
+:ProviderClient: retries the request when :ProviderApi: returns 408, 425, 429, 500, 502, 503, or 504, and also on connection errors, DNS failures, socket timeouts, TLS handshake failures, and connection resets.
 
-- :ProviderClient: does not retry on 400, 401, 403, 404, 405, 409, 410, 415, or 422, and raises immediately.
+# no-retry-permanent-errors
+:ProviderClient: does not retry on 400, 401, 403, 404, 405, 409, 410, 415, or 422, and raises immediately.
 
-- On 429, :ProviderClient: waits and tries again, unless the retry budget is exhausted.
+# retry-on-429
+On 429, :ProviderClient: waits and tries again, unless the retry budget is exhausted.
 ```
 
 GOOD:
@@ -50,7 +53,7 @@ GOOD:
 - :ProviderClient: classifies every failure of :ProviderApi: through [resources/error-map.yaml](resources/error-map.yaml) and retries the transient ones under [resources/retry-policy.yaml](resources/retry-policy.yaml).
 ```
 
-The status-code lists move into `error-map.yaml`, which the renderer already reads to generate the exception hierarchy and the transient predicate. Coverage is unchanged and the classification now has one source of truth instead of two that can disagree — see *Transient vs. permanent exception classification* in `integrations.md`.
+The status-code lists move into `error-map.yaml`, which the coding agent already reads to generate the exception hierarchy and the transient predicate. Coverage is unchanged and the classification now has one source of truth instead of two that can disagree — see *Transient vs. permanent exception classification* in `integrations.md`.
 
 Note the section too. Classifying and retrying is mechanism, so it is an implementation req; what belongs in `***functional specs***` is only the part a caller observes — which exception each error category surfaces as.
 
@@ -76,7 +79,7 @@ GOOD:
 - :Customer: is a :ProviderApi: record, defined by [resources/provider.openapi.yaml](resources/provider.openapi.yaml) under `components.schemas.Customer`.
 ```
 
-Field lists rot the moment the provider adds a field, and the renderer generates types from the schema, not from the sentence. Keep in the definition only what the schema cannot say — a stability or uniqueness guarantee, a unit, a lifecycle rule.
+Field lists rot the moment the provider adds a field, and the coding agent generates types from the schema, not from the sentence. Keep in the definition only what the schema cannot say — a stability or uniqueness guarantee, a unit, a lifecycle rule.
 
 ## Specifying the provider instead of the integration
 
@@ -91,13 +94,17 @@ BAD:
 
 ***functional specs***
 
-- :ProviderApi: returns `200` with a JSON body when a request succeeds.
+# provider-success-response
+:ProviderApi: returns `200` with a JSON body when a request succeeds.
 
-- :ProviderApi: returns `404` when the requested :Customer: does not exist.
+# provider-not-found
+:ProviderApi: returns `404` when the requested :Customer: does not exist.
 
-- :ProviderApi: rate-limits clients and includes the remaining quota in the response headers.
+# provider-rate-limit
+:ProviderApi: rate-limits clients and includes the remaining quota in the response headers.
 
-- :ProviderApi: requires the `Authorization` header on every request.
+# provider-auth-header
+:ProviderApi: requires the `Authorization` header on every request.
 ```
 
 GOOD:
@@ -123,20 +130,21 @@ GOOD:
 
 ***functional specs***
 
-- :ProviderClient: fetches a :Customer: from :ProviderApi: by :CustomerId:.
+# fetch-customer
+:ProviderClient: fetches a :Customer: from :ProviderApi: by :CustomerId:.
 ```
 
 Every BAD bullet is true, and none of them is deleted — they are moved. The success shape, the `404`, and the `Authorization` requirement are what an OpenAPI file exists to state; the rate-limit model has its own conventional files. Provider behavior with no machine-readable home goes in `resources/<provider>-notes.md`. `integrations.md` carries the full artifact table.
 
-What stays in the sections is only what gets built. A bullet stating provider behavior renders into nothing — the renderer cannot build the provider, and no conformance test can assert a sentence that makes no claim about the integration. State instead what the integration does when the provider behaves that way.
+What stays in the sections is only what gets built. A bullet stating provider behavior regenerates into nothing — the coding agent cannot build the provider, and no conformance test can assert a sentence that makes no claim about the integration. State instead what the integration does when the provider behaves that way.
 
-Note where the links hang: both artifacts attach to the :ProviderApi: concept, and everything else references the token. `linked-resources.md` requires each resource to be linked from exactly one place, so a second spec needing the contract cannot introduce a second, divergent reference to it.
+Note where the links hang: both artifacts attach to the :ProviderApi: concept, and everything else references the token. `linked-resources.md` requires each resource to be linked from exactly one place, so a second functional spec needing the contract cannot introduce a second, divergent reference to it.
 
-## One operation fragmented into several specs
+## One operation fragmented into several functional specs
 
 Integration work invites this: the author walks through the request lifecycle — credential check, discovery call, request shape, paging — and each step becomes its own spec.
 
-BAD — four specs, one operation:
+BAD — four functional specs, one operation:
 
 ```plain
 ***definitions***
@@ -147,22 +155,26 @@ BAD — four specs, one operation:
 
 ***functional specs***
 
-- A call to `fetch` fails before any request to :ProviderApi: is sent when `PROVIDER_API_KEY` is unset or empty.
-  - The failure names `PROVIDER_API_KEY`.
+# fetch-requires-api-key
+A call to `fetch` fails before any request to :ProviderApi: is sent when `PROVIDER_API_KEY` is unset or empty.
+- The failure names `PROVIDER_API_KEY`.
 
-- A call to `fetch` reads the field catalogue from :ProviderApi: once, before requesting any :Record:.
-  - The catalogue yields the name of every field the account defines.
-  - A call to `fetch` whose catalogue read fails requests no :Record: items.
+# fetch-reads-catalogue
+A call to `fetch` reads the field catalogue from :ProviderApi: once, before requesting any :Record:.
+- The catalogue yields the name of every field the account defines.
+- A call to `fetch` whose catalogue read fails requests no :Record: items.
 
-- A request for :Record: items from :ProviderApi: names every field in the catalogue and asks for at most 100 records.
-  - Archived :Record: items are not requested.
+# fetch-requests-records
+A request for :Record: items from :ProviderApi: names every field in the catalogue and asks for at most 100 records.
+- Archived :Record: items are not requested.
 
-- A call to `fetch` requests pages until :ProviderApi: returns a response carrying no next-page cursor.
-  - Each page after the first is requested with the cursor from the previous response.
-  - The :Record: items of every page are carried forward together.
+# fetch-pages-records
+A call to `fetch` requests pages until :ProviderApi: returns a response carrying no next-page cursor.
+- Each page after the first is requested with the cursor from the previous response.
+- The :Record: items of every page are carried forward together.
 ```
 
-GOOD — one spec, with the result stated first:
+GOOD — one functional spec, with the result stated first:
 
 ```plain
 ***definitions***
@@ -175,13 +187,14 @@ GOOD — one spec, with the result stated first:
 
 ***functional specs***
 
-- :RecordSource: `fetch()` returns every non-archived :Record: with every field :ProviderApi: defines, paging under [resources/pagination.yaml](resources/pagination.yaml).
-  - :RecordSource: reads the field catalogue once per `fetch()`.
-  - `fetch()` fails before any request when `PROVIDER_API_KEY` is unset or empty, naming it.
-  - A failed catalogue read fails `fetch()` before any :Record: is requested.
+# fetch-records
+:RecordSource: `fetch()` returns every non-archived :Record: with every field :ProviderApi: defines, paging under [resources/pagination.yaml](resources/pagination.yaml).
+- :RecordSource: reads the field catalogue once per `fetch()`.
+- `fetch()` fails before any request when `PROVIDER_API_KEY` is unset or empty, naming it.
+- A failed catalogue read fails `fetch()` before any :Record: is requested.
 ```
 
-Merging is not in tension with the complexity limit. Split a spec when it implies more than 200 changed lines of code (`break-down-func-spec`); merge when several specs implement one operation that fits inside that budget. Fragment count is not a measure of size.
+Merging is not in tension with the complexity limit. Split a functional spec when it implies more than 200 changed lines of code (`break-down-func-spec`); merge when several implement one operation that fits inside that budget. Fragment count is not a measure of size.
 
 ## The auth flow narrated step by step
 
@@ -190,9 +203,11 @@ BAD:
 ```plain
 ***functional specs***
 
-- :ProviderAuth: first reads the client id and the client secret, then builds a form-encoded body containing `grant_type=client_credentials`, the client id, and the client secret, then posts that body to the token endpoint, then parses the JSON response, then extracts the `access_token` and the `expires_in` fields, then stores the token in memory together with the moment it expires, and then attaches it to subsequent requests as a bearer token.
+# obtain-token
+:ProviderAuth: first reads the client id and the client secret, then builds a form-encoded body containing `grant_type=client_credentials`, the client id, and the client secret, then posts that body to the token endpoint, then parses the JSON response, then extracts the `access_token` and the `expires_in` fields, then stores the token in memory together with the moment it expires, and then attaches it to subsequent requests as a bearer token.
 
-- Before each request, :ProviderAuth: compares the current time to the stored expiry and, if the token has expired or is about to expire, repeats the whole procedure described above to obtain a new token.
+# refresh-token
+Before each request, :ProviderAuth: compares the current time to the stored expiry and, if the token has expired or is about to expire, repeats the whole procedure described above to obtain a new token.
 ```
 
 GOOD:
@@ -223,7 +238,7 @@ GOOD:
 
 The grant type, endpoint, body encoding, and response fields are in the security scheme. What survives is the policy the scheme does not describe: the env-var names, the refresh margin, the retry-once-on-401 rule, and the concurrency behavior.
 
-Almost all of it is implementation reqs — acquisition, caching, and refresh are machinery a caller never sees. Not all of it, though, and the rewrite has to name a component to say the rest. :ProviderAuth: performs the grant and has no observable surface; :AuthTokenManager: is what consumes it and hands tokens to :ProviderClient:, so it is the concept a functional spec can take as its subject. Without that consumer the section is left with a subject-less bullet, which `func-specs.md` rules out — and that one spec is the only line here a live conformance test can assert.
+Almost all of it is implementation reqs — acquisition, caching, and refresh are machinery a caller never sees. Not all of it, though, and the rewrite has to name a component to say the rest. :ProviderAuth: performs the grant and has no observable surface; :AuthTokenManager: is what consumes it and hands tokens to :ProviderClient:, so it is the concept a functional spec can take as its subject. Without that consumer the section is left with a subject-less bullet, which `func-specs.md` rules out — and that one functional spec is the only line here a live conformance test can assert.
 
 ## Per-endpoint test reqs