@turri-dev/cli 0.1.27-next.763d091 → 0.1.28-next.d5f2680

package/genome/rules/integration-embedded.md

@@ -1,25 +1,25 @@
 ---
-description: Rules for authoring ***plain specs for REST API integrations embedded into an existing host codebase
+description: Rules for authoring ***plain for REST API integrations embedded into an existing host codebase
 ---
 
-# Rules for **embedded** integration specs
+# Rules for **embedded** integrations in ***plain
 
 When an integration `.plain` module is **embedded** — meaning the generated code in `plain_modules/` is consumed in-process by an existing host codebase as a library / module — these rules apply on top of the shared rules in [`integrations.md`](integrations.md). If anything below contradicts a guess made from memory, the rules here win.
 
 Embedded means: the host codebase already exists, has its own language / framework / dependency manager / packaging layout, and the integration must conform to all of that without negotiation.
 
-> **For test-script authoring**, also follow [`integration-embedded-testing.md`](integration-embedded-testing.md). It defines the per-script contract (`run_unittests_<lang>`, `run_conformance_tests_<lang>`) — staging into the host and the system temp directory, arg validation, exit codes, output parsing, the `***implementation reqs***` and `***test reqs***` entries the spec must declare so the scripts can be generated. This file (`integration-embedded.md`) only summarizes the test-script wiring; the testing rule is the source of truth.
+> **For test-script authoring**, also follow [`integration-embedded-testing.md`](integration-embedded-testing.md). It defines the per-script contract (`run_unittests_<lang>`, `run_conformance_tests_<lang>`) — staging into the host and the system temp directory, arg validation, exit codes, output parsing, the `***implementation reqs***` and `***test reqs***` entries the ***plain must declare so the scripts can be generated. This file (`integration-embedded.md`) only summarizes the test-script wiring; the testing rule is the source of truth.
 
 ## The host codebase dictates the tech stack (hard rule)
 
-- Language, framework, dependency manager, packaging layout, coding standards, error model, logging library, and architecture are **inherited** from the host — they are **never chosen** by the integration spec
+- Language, framework, dependency manager, packaging layout, coding standards, error model, logging library, and architecture are **inherited** from the host — they are **never chosen** by the integration's ***plain
 - Do not re-ask the user about any of these in any phase — they are facts to be discovered from the host's manifest files (`pyproject.toml`, `package.json`, `go.mod`, `Cargo.toml`, `pom.xml`, …) and other integrations.
 - If a stack question seems to push back on a host rule, treat the host as ground truth and rewrite the question
 - Implementation reqs added in the stack phase are **transcribed** from the host stack verbatim — host language and exact version, host framework + version, dependency manager and manifest path, packaging layout, host conventions the contract must follow, and every host-package version the contract pins
 
 ## Project layout — the integration lives under `plain/` at the host root
 
-The embedded integration's `.plain` specs (and the rest of the ***plain project — `template/`, `resources/`, `test_scripts/`, generated `plain_modules/`) live in a single top-level `plain/` folder at the host repository root, alongside the host's own source tree:
+The embedded integration's `.plain` files (and the rest of the ***plain project — `template/`, `resources/`, `test_scripts/`, generated `plain_modules/`) live in a single top-level `plain/` folder at the host repository root, alongside the host's own source tree:
 
 ```
 <host repo>/
@@ -36,7 +36,7 @@ The embedded integration's `.plain` specs (and the rest of the ***plain project
 └── src/            # host source tree (Java, Python, etc.)
 ```
 
-This keeps the integration self-contained in one directory the user can `cd` into to render, while leaving the host's own source layout untouched.
+This keeps the integration self-contained in one directory the user can `cd` into to regenerate, while leaving the host's own source layout untouched.
 
 - If the host **already** has a `plain/` directory, adopt it verbatim — see step 1 of *Discover before you ask* below
 - If the host does **not** yet have one, create `plain/` at the repo root; do not invent a different name (`specs/`, `plain_specs/`, …)
@@ -60,19 +60,19 @@ Run host discovery **before** the first interview question. Treat the results as
 
 ## Reference host symbols by fully qualified import path
 
-- Every host class, interface, struct, exception, or type alias that appears in a spec must be written with its full dotted / slashed import path (e.g. `host_project.integrations.base.IntegrationContract`, `@host/integrations#Contract`) and tagged in the spec text as **"imported from the host codebase; do not redefine"**
-- The renderer is allowed to redefine **only** symbols the host does not provide and the contract schema does not capture
-- Naming the symbol by FQN is not optional decoration — it tells the renderer where the type comes from, which prevents a duplicate definition under `plain_modules/`
+- Every host class, interface, struct, exception, or type alias that appears in the ***plain must be written with its full dotted / slashed import path (e.g. `host_project.integrations.base.IntegrationContract`, `@host/integrations#Contract`) and tagged in the ***plain's text as **"imported from the host codebase; do not redefine"**
+- The coding agent is allowed to redefine **only** symbols the host does not provide and the contract schema does not capture
+- Naming the symbol by FQN is not optional decoration — it tells the coding agent where the type comes from, which prevents a duplicate definition under `plain_modules/`
 
 ## Link host files at their original path — never copy them into `resources/`
 
-The integration's `.plain` module lives **inside the host codebase** (per the "adopt the host's `.plain` setup verbatim" step). That means host source files are already reachable as linked resources via their host-relative paths. The integration spec references them **in place**; it never duplicates them under `resources/host/`.
+The integration's `.plain` module lives **inside the host codebase** (per the "adopt the host's `.plain` setup verbatim" step). That means host source files are already reachable as linked resources via their host-relative paths. The integration's ***plain references them **in place**; it never duplicates them under `resources/host/`.
 
-- Every host file the integration touches (base classes, configuration modules, registries, exception classes, lifecycle hooks) is referenced from the relevant spec using `***linked resource***` syntax with the **path as it exists in the host codebase** — e.g. `[base.py](host_project/integrations/base.py)` if the `.plain` module sits next to `host_project/`
-- **Do NOT copy host files into `resources/host/`.** A copy creates a second source of truth that drifts the moment the host file is edited; the rendered code will then disagree with whatever the host actually ships
+- Every host file the integration touches (base classes, configuration modules, registries, exception classes, lifecycle hooks) is referenced from the relevant ***plain using `***linked resource***` syntax with the **path as it exists in the host codebase** — e.g. `[base.py](host_project/integrations/base.py)` if the `.plain` module sits next to `host_project/`
+- **Do NOT copy host files into `resources/host/`.** A copy creates a second source of truth that drifts the moment the host file is edited; the regenerated code will then disagree with whatever the host actually ships
 - **Do NOT copy host files into `resources/`** when that would duplicate them — link the existing host path directly
-- **Never inline a host file's contents** into a spec
-- **Never describe a host symbol's shape from memory** — the renderer reads the linked file's bytes at its host path and that is the source of truth
+- **Never inline a host file's contents** into the ***plain
+- **Never describe a host symbol's shape from memory** — the coding agent reads the linked file's bytes at its host path and that is the source of truth
 - This still obeys the broader [`linked-resources.md`](linked-resources.md) rules: a directory is not a valid link, a URL is not a valid link, a binary is not a valid link. Only the *location* changes — host files live where the host put them, not under `resources/`
 
 ### What still belongs under `resources/`
@@ -85,16 +85,16 @@ This rule applies to **host source code only**. Other artifacts still live under
 
 The rule of thumb: if the host wrote it and ships it, link it where the host put it. If the integration is authoring it for the first time, it goes under `resources/`.
 
-## The contract spec declares inheritance, not duplication
+## The contract's ***plain declares inheritance, not duplication
 
-- The entry-point class / interface / struct in the contract spec must `subclass` / `implements` / `embeds` the host symbol by its full import path
-- The spec describes only the **integration-specific additions and overrides** — never restates the parent's fields or methods
+- The entry-point class / interface / struct in the contract's ***plain must `subclass` / `implements` / `embeds` the host symbol by its full import path
+- The ***plain describes only the **integration-specific additions and overrides** — never restates the parent's fields or methods
 - The additions and overrides are themselves expressed in the linked schema under `resources/contract/` (JSON Schema or OpenAPI), with `allOf` / `$ref` extending the host's schema rather than duplicating fields
 - If a host base class adds fields the integration shouldn't redeclare, the contract schema's `allOf` chain captures that explicitly
 
-## Renderer directives go in the spec, shapes go in the schema
+## Coding-agent directives go in the ***plain, shapes go in the schema
 
-Each contract spec carries the language-specific glue that the schema can't express:
+The contract's ***plain carries the language-specific glue that the schema can't express:
 
 - Target generated-class fully qualified name (e.g. `plain_modules.integrations.<provider>.Client`)
 - Target file path under `plain_modules/`
@@ -102,13 +102,13 @@ Each contract spec carries the language-specific glue that the schema can't expr
 - Host-package version pins (e.g. `pydantic ~= 2.5`, `fastapi ^0.110`)
 - Framework-specific decorators or metaclasses (`model_config`, `@Depends`, …)
 
-The renderer reads the directives from the spec and the shapes from the linked schema, then emits the host-language class. The spec must **not** also contain a class body or a field list — that creates two sources of truth and they will drift.
+The coding agent reads the directives from the ***plain and the shapes from the linked schema, then emits the host-language class. The ***plain must **not** also contain a class body or a field list — that creates two sources of truth and they will drift.
 
 ## Single source of truth for the host root
 
 - The `host-codebase` concept holds the host root path as a **fact**
-- Test scripts, configuration-loading specs, and any other spec that needs the host location reads it from **that one fact** (via the env var declared in the configuration concept)
-- Never hardcode the host path in any spec, script, or runtime config
+- Test scripts, configuration-loading functional specs, and any other ***plain that needs the host location reads it from **that one fact** (via the env var declared in the configuration concept)
+- Never hardcode the host path in any ***plain, script, or runtime config
 
 ## No host-overlapping reqs
 
@@ -120,7 +120,7 @@ The renderer reads the directives from the spec and the shapes from the linked s
 
 Embedded integrations are tested **inside the host codebase itself**. A module's code and unit tests live in `plain_modules/<module>/code`; its conformance tests live in one folder, `plain_modules/<module>/tests` — the module's whole conformance suite. turri runs two self-contained scripts on the person's machine, once per check: `run_unittests_<lang>.sh <build_folder>` decides the unit tests, and `run_conformance_tests_<lang>.sh <build_folder> <conformance_tests_folder>` (absolute paths) runs the whole conformance suite at once and its exit code decides the conformance tests. There is no prepare-environment script.
 
-Both scripts copy the renderer's output (`$1`, i.e. `plain_modules/<module>/code/`) into the host's source tree at the module's package path, then compile / test the host project in place. The conformance script also uses a scratch folder in the system temp directory (`/tmp/<lang>_conformance/`), because the conformance suite is a separate project that consumes the host build as a dependency.
+Both scripts copy the coding agent's output (`$1`, i.e. `plain_modules/<module>/code/`) into the host's source tree at the module's package path, then compile / test the host project in place. The conformance script also uses a scratch folder in the system temp directory (`/tmp/<lang>_conformance/`), because the conformance suite is a separate project that consumes the host build as a dependency.
 
 This matters because the integration's generated code references host symbols by their full import path (e.g. `from host_project.integrations.base import IntegrationContract`). Those imports only resolve cleanly when the test process is rooted in the host's package layout — anything else creates path edge cases that bite later in conformance failures.
 
@@ -131,8 +131,8 @@ See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the
 
 ### Invariants the scripts must enforce
 
-- **Host root is a parameter, not a literal.** No script may hardcode an absolute host path. Read the host root from an env var (e.g. `HOST_CODEBASE_ROOT`) with a sensible default matching the user's layout (e.g. `../host_project`). Surface the env var in each script's `--help` / usage banner. Capture this env var in the integration's configuration concept so it has exactly one declared name across specs, scripts, and runtime
-- **Everything about `:UnitTests:` is declared in `***implementation reqs***`** — paths, approach, packages, framework, conventions. Both scripts derive their copy destinations from these reqs, and the unit-test script its test-filter argument. See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the exact reqs the spec must author (phrased in terms of `:UnitTests:`)
+- **Host root is a parameter, not a literal.** No script may hardcode an absolute host path. Read the host root from an env var (e.g. `HOST_CODEBASE_ROOT`) with a sensible default matching the user's layout (e.g. `../host_project`). Surface the env var in each script's `--help` / usage banner. Capture this env var in the integration's configuration concept so it has exactly one declared name across the ***plain, scripts, and runtime
+- **Everything about `:UnitTests:` is declared in `***implementation reqs***`** — paths, approach, packages, framework, conventions. Both scripts derive their copy destinations from these reqs, and the unit-test script its test-filter argument. See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the exact reqs the ***plain must author (phrased in terms of `:UnitTests:`)
 - **Everything about `:ConformanceTests:` is declared in `***test reqs***`** — paths, approach, packages, framework, execution command, pass criteria, mocking policy. The conformance script derives its build and run steps from these reqs. See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the exact reqs (phrased in terms of `:ConformanceTests:`)
 - **The two groups never overlap.** `:UnitTests:` facts belong only in `***implementation reqs***`; `:ConformanceTests:` facts belong only in `***test reqs***`. Neither lives in the `host-codebase` concept
 - **Destructive ops are scoped to the module's own package path** under the host's source tree. `rm -rf` never touches the host's `src/main/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root. Only the module-specific package directories are wiped
@@ -143,9 +143,9 @@ See [`integration-embedded-testing.md`](integration-embedded-testing.md) for the
 Before declaring an embedded integration done, in addition to the shared checklist in [`integrations.md`](integrations.md):
 
 - [ ] `host-codebase` concept records host root path, host language + version, host dependency manager + manifest, target package path, host base class import path, target generated-class FQN, and the host conventions the contract follows
-- [ ] Contract spec carries renderer directives (target language, target file path, target class name, host base class to subclass, host-package pins) and **links** to the contract schema; no class body is inlined
-- [ ] Every host symbol referenced in any spec uses its fully qualified import path and is tagged "imported from the host codebase; do not redefine"
-- [ ] Every host file the integration touches is linked at its **original host-relative path** — no host file has been copied into `resources/host/` or anywhere else, and no host file contents are inlined in any spec
+- [ ] The contract's ***plain carries coding-agent directives (target language, target file path, target class name, host base class to subclass, host-package pins) and **links** to the contract schema; no class body is inlined
+- [ ] Every host symbol referenced anywhere in the ***plain uses its fully qualified import path and is tagged "imported from the host codebase; do not redefine"
+- [ ] Every host file the integration touches is linked at its **original host-relative path** — no host file has been copied into `resources/host/` or anywhere else, and no host file contents are inlined in the ***plain
 - [ ] The stack decisions are transcribed verbatim from the host (no independent stack choices)
 - [ ] Host-package version pins are copied into `***implementation reqs***`
 - [ ] `run_unittests` copies `$1` into the host's source tree at the module's package path and invokes the host's test runner scoped to the module's package
@@ -160,12 +160,12 @@ Before declaring an embedded integration done, in addition to the shared checkli
 ## Anti-patterns specific to embedded integrations
 
 - **Choosing a different language, framework, or dependency manager than the host.** The host stack is inherited; cross-stack `requires` chains are forbidden by [`requires-modules.md`](requires-modules.md)
-- **Redefining a host class under `plain_modules/`.** Reference the host symbol by FQN; let the renderer import it
+- **Redefining a host class under `plain_modules/`.** Reference the host symbol by FQN; let the coding agent import it
 - **Inlining a host base class body into the contract spec.** Reference the host file as a linked resource **at its original host-relative path** — do not inline its contents and do not copy it into `resources/`
 - **Copying host source files into `resources/host/` (or anywhere under `resources/`).** That creates a second source of truth that silently drifts from the host. Link the host file in place; the integration `.plain` module already lives inside the host codebase, so the path resolves naturally
-- **Hardcoding the host codebase path in any spec or script.** Read it from the env var declared in the configuration concept
+- **Hardcoding the host codebase path in any ***plain or script.** Read it from the env var declared in the configuration concept
 - **Asking the user to design the integration's tech stack.** Read it from the host's manifest files
-- **Authoring an integration spec that contradicts an existing integration in the same host** without first surfacing the conflict and getting explicit user confirmation
+- **Authoring an integration's ***plain that contradicts an existing integration in the same host** without first surfacing the conflict and getting explicit user confirmation
 - **Wiring tests with `PYTHONPATH` / `NODE_PATH` / Go `replace` directives instead of physically copying `$1` into the host's package tree.** The import-stitching approach is forbidden — every test script starts by copying the generated module into the host's source tree at the module's package path
 - **Letting an `rm -rf` in a test script reach the host's `src/main/`, `target/`, `node_modules/`, `build/`, or `dist/` at the project root.** Destructive ops are scoped strictly to the module's own package directory. A wrong package path in the script silently does nothing and copies files in the wrong place — both produce a green build with stale code
 - **Running conformance tests against a stale local dependency cache.** The conformance script must stage `$1` and build / install the host itself before it runs the suite, so the conformance project resolves this build from `~/.m2` (or the language equivalent). Without that step the suite tests whichever build last hit the cache — the wrong code

package/genome/rules/integration-standalone.md

@@ -1,8 +1,8 @@
 ---
-description: Rules for authoring ***plain specs for REST API integrations deployed standalone
+description: Rules for authoring ***plain for REST API integrations deployed standalone
 ---
 
-# Rules for **standalone** integration specs
+# Rules for **standalone** integrations in ***plain
 
 When an integration `.plain` module is **standalone** — meaning the generated code in `plain_modules/` is the deployable artifact itself (a service, daemon, CLI, scheduled job, container, or library published to a registry) — these rules apply on top of the shared rules in [`integrations.md`](integrations.md). If anything below contradicts a guess made from memory, the rules here win.
 
@@ -23,7 +23,7 @@ Standalone integrations may freely import any third-party library that isn't con
 
 ## The contract schema is the public artifact
 
-In an embedded integration, the schema feeds the renderer's code generation; the host codebase consumes the *generated class*. In a standalone integration, the schema is **shipped** to external consumers and the generated implementation is internal to `plain_modules/`.
+In an embedded integration, the schema feeds the coding agent's code generation; the host codebase consumes the *generated class*. In a standalone integration, the schema is **shipped** to external consumers and the generated implementation is internal to `plain_modules/`.
 
 - **Pick the publication surface and write it into the spec.** Examples (one functional spec per surface):
   - HTTP service: "served at `/openapi.json` (and a Swagger UI at `/docs`)"
@@ -33,16 +33,16 @@ In an embedded integration, the schema feeds the renderer's code generation; the
   - Queue worker: "published as a JSON Schema in the team's schema registry under `<topic>.v<version>.json`"
   - Scheduled job: "published as JSON Schema in `resources/contract/job-config.schema.json` and linked from the runbook"
 - **Schema versioning is part of the contract.** Pin the version in the schema's `$id` / OpenAPI `info.version` and follow semver. Backwards-incompatible changes ship under a new file path, never as mutations to the published version
-- **The renderer ships the schema verbatim** — the spec must not restate fields from the schema, and the generated implementation must consume the same file as the published artifact (so the two cannot drift)
+- **The coding agent ships the schema verbatim** — the ***plain must not restate fields from the schema, and the generated implementation must consume the same file as the published artifact (so the two cannot drift)
 
 ## All lifecycle stages must be explicit
 
 A standalone integration has no host lifecycle to delegate to. Every stage that an embedded integration could skip is mandatory here, each one captured as its own functional spec:
 
-- **Initialization** — one-time setup at startup. Read configuration, validate credentials proactively (eager) or defer to first call (lazy) — pick one and write the spec accordingly. Open connection pools, register webhook handlers, initialize observability
+- **Initialization** — one-time setup at startup. Read configuration, validate credentials proactively (eager) or defer to first call (lazy) — pick one and write the ***plain accordingly. Open connection pools, register webhook handlers, initialize observability
 - **Credential refresh** — proactive (background timer / pre-expiry refresh) vs. reactive (refresh-on-401). Use a refresh lock to prevent thundering herd. Specify the lock primitive (in-process mutex, distributed lock in Redis, …) when the integration runs as more than one replica
 - **Graceful shutdown** — drain in-flight requests with a deadline; what happens to retries still queued (abandoned, persisted, returned to caller as a specific error); what signals trigger shutdown (`SIGTERM`, container-stop hook, …)
-- **Health checks** — define what "healthy" means for **this** integration: last successful provider call within a window, valid credentials, provider's own `/health` returning 2xx, dependent storage reachable. Spec the response shape (status code, body) for the health endpoint when one is exposed
+- **Health checks** — define what "healthy" means for **this** integration: last successful provider call within a window, valid credentials, provider's own `/health` returning 2xx, dependent storage reachable. State the response shape (status code, body) for the health endpoint when one is exposed
 - **Background loops** — cron jobs, polling workers, queue consumers: each gets its own functional spec covering trigger, interval, leader-election (if applicable), failure handling, and observability
 
 ## Entry-point types — pick deliberately, enumerate fully
@@ -71,7 +71,7 @@ A standalone integration usually mutates state outside the provider call itself.
 
 ## Concurrency and backpressure
 
-Standalone integrations face concurrent load that an embedded library doesn't. The spec must pin:
+Standalone integrations face concurrent load that an embedded library doesn't. The ***plain must pin:
 
 - **Sync vs. async** in the host-language sense (`async def`, `Promise`, goroutines, threads)
 - **Expected peak throughput** (RPS) the consumer will issue
@@ -128,8 +128,8 @@ Before declaring a standalone integration done, in addition to the shared checkl
 ## Anti-patterns specific to standalone integrations
 
 - **Skipping any lifecycle stage** because it "feels small". Standalone integrations have no host to fall back on; an implicit shutdown is an undefined shutdown
-- **Inlining fields from `resources/contract/<entry-point>.schema.json` into a functional spec.** The schema is the source of truth and is **published** — duplicating fields in spec text guarantees drift
+- **Inlining fields from `resources/contract/<entry-point>.schema.json` into a functional spec.** The schema is the source of truth and is **published** — duplicating fields in ***plain guarantees drift
 - **Mutating a published schema's `$id` / version path** instead of shipping a new file. Consumers may already be pinning the old version
 - **Treating configuration as "whatever env vars seem useful at runtime".** Every key lives in `resources/config.schema.json` with type, default, and validation; the loader fails fast on missing required values
-- **Picking a tech stack incrementally while writing functional specs.** Decide it once, when the stack is chosen, and transcribe into `***implementation reqs***`; don't accrete a stack across several specs
+- **Picking a tech stack incrementally while writing functional specs.** Decide it once, when the stack is chosen, and transcribe into `***implementation reqs***`; don't accrete a stack across several functional specs
 - **Hitting the live provider in rate-limit (429) or destructive-error (500) tests.** Use a local mock; live calls are for the happy path and for sandbox-safe error paths

package/genome/rules/integrations.md

@@ -1,12 +1,12 @@
 ---
-description: Rules for authoring ***plain specs for REST API integrations
+description: Rules for authoring ***plain for REST API integrations
 ---
 
-# Rules for writing integration specs in `***plain`
+# Rules for writing integrations in `***plain`
 
 When writing or editing a `.plain` file that describes an **integration** against a REST API (synchronous JSON/HTTP request-response plus webhook callbacks), always follow these rules. Non-REST integrations (gRPC, GraphQL, SOAP, message brokers, raw TCP, file drops) are out of scope of these rules.
 
-## Scope of "integration" specs
+## Scope of "integration" ***plain
 - An integration `.plain` module describes how the project talks to a **third-party or internal REST API**
 - The integration may be **embedded** (lives as a library/module inside an existing host codebase) — see [`integration-embedded.md`](integration-embedded.md) for the additional rules that apply
 - Or **standalone** (a service, daemon, CLI, scheduled job, or container) — see [`integration-standalone.md`](integration-standalone.md) for the additional rules that apply
@@ -34,23 +34,23 @@ Rules that flow from this:
 
 - **Provider behavior is recorded, not specified.** How the provider itself works — its quota accounting, consistency guarantees, documented quirks, and any place the live API diverges from its docs — is true and worth capturing, but it is not a requirement on the software being built. Whatever has a machine-readable home in the table above goes there; the rest goes in `resources/<provider>-notes.md`. A functional spec never states provider behavior; it states what the integration does in the face of it.
 - **Concepts carry references, not data.** An endpoint concept names the endpoint and points at its OpenAPI `paths.<path>.<method>` entry; it does not duplicate the request/response shape in concept attributes. Same for webhook concepts, error-model concepts, pagination concepts, etc.
-- **Functional specs consume linked resources.** A spec describes **behavior** ("call endpoint X, parse the response, classify errors, retry on 5xx") and links to the resource that supplies the **shape**. Field names, types, and validation rules live in the resource file.
+- **Functional specs consume linked resources.** A functional spec describes **behavior** ("call endpoint X, parse the response, classify errors, retry on 5xx") and links to the resource that supplies the **shape**. Field names, types, and validation rules live in the resource file.
 - **Schemas are versioned by file path.** When the provider releases a new API version, copy the new OpenAPI file to a new path (e.g. `resources/<provider>.v2.openapi.yaml`); never mutate the v1 file in place.
-- **The renderer generates language-native types from the resources.** For embedded integrations the renderer reads JSON Schema / OpenAPI components and emits Pydantic / TypeScript / Go types in `plain_modules/`. The spec declares **which** schema to generate from, **where** the generated type should land, and **what host base class** it must subclass — but never restates the schema's fields.
+- **The coding agent generates language-native types from the resources.** For embedded integrations the coding agent reads JSON Schema / OpenAPI components and emits Pydantic / TypeScript / Go types in `plain_modules/`. The ***plain declares **which** schema to generate from, **where** the generated type should land, and **what host base class** it must subclass — but never restates the schema's fields.
 
 A single `.plain` module can (and typically will) reference many resources. That is the intended pattern; do not try to collapse them into one mega-file.
 
 ## Live API must be cross-checked against the documentation
 
-Documentation lies — it goes stale, omits undocumented fields, describes a different API version, papers over breaking changes. Every integration spec must be grounded in what the API really returns, not what the docs claim it returns.
+Documentation lies — it goes stale, omits undocumented fields, describes a different API version, papers over breaking changes. Every integration's ***plain must be grounded in what the API really returns, not what the docs claim it returns.
 
 - **Discover the documentation links with web search first, then `fetch` all of them.** Documentation moves, gets reorganized, and is versioned — so never assume a doc URL from memory. Begin every topic by issuing **web searches with human-readable queries** to find the canonical pages, then `fetch` **every** relevant link the search surfaces — the endpoint reference, the auth guide, the webhook catalog, the error reference, the pagination/rate-limit docs, the changelog. The search step finds *which* URLs are authoritative and current; the `fetch` step retrieves their actual content. Do not stop at the first hit — fetch the full set so a topic is grounded in all of its sources, not a single page.
   - If the environment has **no web-search tool** (only URL-based `fetch` is available), say so explicitly, construct the URL from the provider's well-known documentation root and crawl outward by `fetch`-ing that root and following its links, and ask the user for the canonical URL whenever you cannot reach the right page that way. Never substitute memory for the search-then-fetch step.
-- **Always `fetch` the provider's documentation — even if you already "know" the API.** The only acceptable source of truth for what the API looks like *today* is the provider's own live documentation, retrieved with `fetch` at spec-authoring time. This applies without exception — there is no API well-known enough to skip this step, and a spec authored from memory is a spec authored against the wrong contract. Concretely:
+- **Always `fetch` the provider's documentation — even if you already "know" the API.** The only acceptable source of truth for what the API looks like *today* is the provider's own live documentation, retrieved with `fetch` at authoring time. This applies without exception — there is no API well-known enough to skip this step, and ***plain authored from memory is authored against the wrong contract. Concretely:
   - Before authoring **any** endpoint, auth, error, pagination, or webhook concept, **web-search to locate the relevant documentation page(s), then `fetch` each one** and quote concrete details (status codes, field names, header names, error formats) directly from the fetched content into the resources under `resources/`. Never paraphrase from memory.
   - If a documentation page is unreachable (paywall, login wall, JS-only render that `fetch` can't see), say so explicitly and ask the user for the canonical content rather than filling the gap from memory.
   - **The fetched documentation is then cross-checked against the live API** — see the rest of this section.
-- **Validate credentials against the live API** before authoring downstream specs. A 2xx on a low-risk read-only endpoint (`/v1/me`, `/account`, `/whoami`, `/health`) is the gate. On 401/403, stop and resolve before continuing. The credentials should be validated against the live API before any downstream specs are authored.
+- **Validate credentials against the live API** before authoring the ***plain that depends on them. A 2xx on a low-risk read-only endpoint (`/v1/me`, `/account`, `/whoami`, `/health`) is the gate. On 401/403, stop and resolve before continuing. The credentials should be validated against the live API before any ***plain that depends on them is authored.
 - **Issue the minimum cross-check coverage** with `fetch`: one discovery / schema endpoint if available, one list endpoint per primary entity in scope, one single-object retrieval per primary entity, one empty/boundary response, one 404, one 400/422, and one deliberate 401.
 - **Where the docs and the live API disagree, the live API wins** — the resource records what the API actually returns, and nothing records the disagreement itself.
 - **Only `GET` / `HEAD` / `OPTIONS` on the cross-check.** Mutating calls (`POST`, `PATCH`, `PUT`, `DELETE`) require explicit per-call user confirmation and must target a sandbox account.
@@ -67,7 +67,7 @@ Integrations exist to talk to a real third-party (or internal) API. Their `:Conf
 
 ### Secrets come from the environment
 
-Live conformance needs credentials. The integration spec must pin every credential as **an env var name, never a literal value**, and the conformance script must read those env vars at runtime:
+Live conformance needs credentials. The integration's ***plain must pin every credential as **an env var name, never a literal value**, and the conformance script must read those env vars at runtime:
 
 - **Author the env-var names in `***test reqs***`** (using `:ConformanceTests:`) and again in the auth concept. Examples: `STRIPE_API_KEY`, `GITHUB_TOKEN`, `SALESFORCE_CLIENT_ID` + `SALESFORCE_CLIENT_SECRET`. Use names that match what the provider's own docs use, so a user copying values from the provider console doesn't need to translate
 - **The user supplies the values out-of-band**, either:
@@ -78,7 +78,7 @@ Live conformance needs credentials. The integration spec must pin every credenti
 - **The conformance suite reads the same env-var names** the integration's runtime reads — so a credential that works at runtime is the same credential that exercises the suite
 - **Credentials never appear in `.plain` files, commits, summaries, logs, or fixtures.** The cross-check (see *Live API must be cross-checked*) already requires redacting credentials from saved fixtures; the same rule applies to conformance logs
 
-The `.plain` spec should make this discoverable. A minimal `***test reqs***` block for an integration looks like:
+The `.plain` file should make this discoverable. A minimal `***test reqs***` block for an integration looks like:
 
 ```plain
 - :ConformanceTests: run against the live :ProviderName: sandbox — no mocking of provider calls.
@@ -90,16 +90,16 @@ The `.plain` spec should make this discoverable. A minimal `***test reqs***` blo
 
 ## Embedded vs standalone — pick the shape early
 
-Every integration is either **embedded** (lives as a library/module inside an existing host codebase) or **standalone** (a service, daemon, CLI, scheduled job, or container). The choice is captured as a concept (`integration-shape: embedded | standalone`) so later specs can reference it.
+Every integration is either **embedded** (lives as a library/module inside an existing host codebase) or **standalone** (a service, daemon, CLI, scheduled job, or container). The choice is captured as a concept (`integration-shape: embedded | standalone`) so later functional specs can reference it.
 
-The contract artifact itself is **identical** across both shapes: a JSON Schema (or OpenAPI) file under `resources/contract/`. What changes is **what the renderer emits from it** and **what extra context the spec carries**:
+The contract artifact itself is **identical** across both shapes: a JSON Schema (or OpenAPI) file under `resources/contract/`. What changes is **what the coding agent emits from it** and **what extra context the ***plain carries**:
 
-- **Embedded** → the renderer generates a host-language class from the schema and wires it into the host's import path. The host codebase dictates the tech stack — see [`integration-embedded.md`](integration-embedded.md) for the full ruleset
-- **Standalone** → the renderer treats the schema as the public artifact: it generates an internal implementation in `plain_modules/` and ships the schema verbatim for external consumers. The integration owns its stack — see [`integration-standalone.md`](integration-standalone.md) for the full ruleset
+- **Embedded** → the coding agent generates a host-language class from the schema and wires it into the host's import path. The host codebase dictates the tech stack — see [`integration-embedded.md`](integration-embedded.md) for the full ruleset
+- **Standalone** → the coding agent treats the schema as the public artifact: it generates an internal implementation in `plain_modules/` and ships the schema verbatim for external consumers. The integration owns its stack — see [`integration-standalone.md`](integration-standalone.md) for the full ruleset
 
 ## Edge-case coverage is a hard floor, not a stretch goal
 
-A production-ready integration spec captures every corner case the API can throw at the integration. Each of the following must be in the specs (or explicitly recorded as "not applicable" / "not in scope" with the user's acknowledgement) before the integration is considered complete:
+A production-ready integration's ***plain captures every corner case the API can throw at the integration. Each of the following must be in the ***plain (or explicitly recorded as "not applicable" / "not in scope" with the user's acknowledgement) before the integration is considered complete:
 
 - **Provider, purpose, canonical documentation URL(s)** as concepts
 - **Endpoints in scope** in `resources/<provider>.openapi.yaml`, one `paths.<path>.<method>` entry per endpoint; endpoint concepts link to the OpenAPI entry
@@ -115,7 +115,7 @@ A production-ready integration spec captures every corner case the API can throw
   - **Transient by default**: network-level errors (`ConnectionError` / equivalent, DNS failure, socket timeout, TLS handshake failure, connection reset), HTTP 408, 425, 429, 500, 502, 503, 504, and any provider-specific application-level error codes the docs / live API mark as retryable (e.g. Stripe's `lock_timeout`, AWS `ThrottlingException`)
   - **Permanent by default**: every other 4xx (400, 401, 403, 404, 405, 409, 410, 415, 422, …), schema-validation failures on otherwise-2xx responses, signature-verification failures on webhooks, and any provider error code the docs / live API mark as non-retryable
   - **Integration exception hierarchy**: the integration exposes a base exception class (e.g. `<Provider>Error`) with two direct subclasses, `<Provider>TransientError` (raised after the retry policy gives up on a transient condition) and `<Provider>PermanentError` (raised immediately on a permanent condition). Every concrete exception inherits from exactly one of those two — callers branch on the base class, never on individual subclasses
-  - **The classification is data-driven**, not code-driven — `resources/error-map.yaml` is the source of truth, the renderer reads it to generate the exception hierarchy and the `is_transient(error) -> bool` predicate. Spec text never enumerates status codes inline
+  - **The classification is data-driven**, not code-driven — `resources/error-map.yaml` is the source of truth, the coding agent reads it to generate the exception hierarchy and the `is_transient(error) -> bool` predicate. ***plain never enumerates status codes inline
   - **Discrepancies found during the live-API cross-check override the docs** — if the docs say a code is transient but the live API never recovers from it (or vice versa), the live behavior wins and the divergence is recorded in `error-map.yaml` plus a note in the error-model concept ("docs claim X retryable, live API returns Y permanently; we follow the live API")
 - **Idempotency strategy** in `resources/idempotency.yaml` + idempotency header in `components.parameters`
 - **Webhook contracts** as `resources/webhooks/<event>.schema.json` per event type + `resources/webhook-signing.yaml`
@@ -125,12 +125,12 @@ A production-ready integration spec captures every corner case the API can throw
 
 ## Anti-patterns (do not do these)
 
-- **Restating an OpenAPI / JSON Schema field list in a concept or functional spec.** The schema lives in `resources/`; the spec links to it
+- **Restating an OpenAPI / JSON Schema field list in a concept or functional spec.** The schema lives in `resources/`; the ***plain links to it
 - **Pasting a webhook payload, error envelope, or list-endpoint response inline.** Describe its shape in the applicable schema under `resources/` and link that schema
 - **Inlining a host base class body into the contract spec.** Add the host file as a linked resource under `resources/host/` and reference it by FQN
 - **Embedding credentials, tokens, or signing keys in a `.plain` file or in a summary** — credentials are referenced by env-var name only
 - **Authoring against unverified credentials.** Validate first; if the user has no credentials yet, flag it in the module's frontmatter description and re-validate once credentials arrive
 - **`requires`-ing a separate-stack module** (a Python backend `requires`-ing a React frontend, or vice versa) — see [`requires-modules.md`](requires-modules.md). Use a shared API schema in `resources/` instead
 - **Authoring the integration's functional specs from the docs first and "reconciling" with the live API later.** Probe the API as you reach each topic; the live response is the source of truth from the moment it's captured
-- **Writing any integration spec from memory of the provider's API instead of web-searching for its documentation and `fetch`-ing every relevant page first.** No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the canonical pages must be located with web search and then retrieved with `fetch` at spec-authoring time — see *Live API must be cross-checked against the documentation*. Authoring from memory bakes in whatever version of the API was current during training, which is always older than the version the integration will actually call
+- **Writing any integration's ***plain from memory of the provider's API instead of web-searching for its documentation and `fetch`-ing every relevant page first.** No matter how well-known the API (Stripe, GitHub, Slack, Salesforce, AWS, OpenAI, …), the canonical pages must be located with web search and then retrieved with `fetch` at authoring time — see *Live API must be cross-checked against the documentation*. Authoring from memory bakes in whatever version of the API was current during training, which is always older than the version the integration will actually call
 - **Guessing a documentation URL from memory and `fetch`-ing it without searching first.** A remembered URL may 404, redirect to a stale version, or miss the page that actually documents the topic. Search to find the authoritative, current links, then fetch the full set

package/genome/rules/linked-resources.md

@@ -1,35 +1,35 @@
 ---
-description: Rules for linking external resources from .plain specs
+description: Rules for linking external resources from .plain files
 ---
 
 # Rules for linked resources in `.plain` files
 
-Specifications can reference external files using markdown link syntax. The renderer reads the linked file's bytes verbatim and feeds them to the model alongside the spec. That mechanism only works for a specific shape of target — violating any of the rules below is one of the most common and disruptive mistakes in `.plain` authoring.
+***plain can reference external files using markdown link syntax. turri reads the linked file's bytes verbatim and feeds them to the coding agent alongside the ***plain. That mechanism only works for a specific shape of target — violating any of the rules below is one of the most common and disruptive mistakes in `.plain` authoring.
 
 ## Hard constraint: a linked resource is always a single file on disk - text, or a PNG or JPEG image
 
 A linked resource **must not** be any of the following:
 
-1. **A folder / directory.** `[integrations](src/integrations/)`, `[host project](../host_project/)` are invalid — the renderer cannot ingest a directory. Pick the single most representative file inside (a `README.md`, an exemplar source file, a manifest) and link **that**.
+1. **A folder / directory.** `[integrations](src/integrations/)`, `[host project](../host_project/)` are invalid — turri cannot ingest a directory. Pick the single most representative file inside (a `README.md`, an exemplar source file, a manifest) and link **that**.
 2. **A URL / external location.** `[Stripe docs](https://stripe.com/docs/api)`, any `http://` / `https://` / `ftp://` / `git://` / `s3://` / `gs://` target. Linked resources are local-file only. If a URL's content is essential, fetch it once, save the response to a text file under `resources/`, and link the saved file.
-3. **A binary file other than a PNG or JPEG image.** GIF, WEBP, SVG, PDF, DOCX, XLSX, ZIP, MP3, MP4, compiled binaries (`.exe`, `.so`, `.class`, `.wasm`), and anything else that isn't human-readable text in its raw form. Binary content cannot be meaningfully consumed by the renderer — transcribe it into a text-based form first (a PDF spec becomes a Markdown extract or the underlying JSON Schema / OpenAPI, an architecture diagram becomes a Mermaid block).
-   - **PNG and JPEG images (`.png`, `.jpg`, `.jpeg`) are the exception**: a UI mockup, a screenshot of the look to match, a diagram. The coding agents are shown the image itself, so the coding model must be one that reads images - the render stops, saying so, when it is not. Each image is at most 5 MB.
-   - An image says what something looks like, not what it does: the behaviour still belongs in the spec's text. Link a mockup from a concept (`:CheckoutPage:` looks as [checkout mockup](resources/checkout.png) shows) and keep the rules - what each button does, which fields are required - in the functional specs.
+3. **A binary file other than a PNG or JPEG image.** GIF, WEBP, SVG, PDF, DOCX, XLSX, ZIP, MP3, MP4, compiled binaries (`.exe`, `.so`, `.class`, `.wasm`), and anything else that isn't human-readable text in its raw form. Binary content cannot be meaningfully consumed by the coding agent — transcribe it into a text-based form first (a PDF spec becomes a Markdown extract or the underlying JSON Schema / OpenAPI, an architecture diagram becomes a Mermaid block).
+   - **PNG and JPEG images (`.png`, `.jpg`, `.jpeg`) are the exception**: a UI mockup, a screenshot of the look to match, a diagram. The coding agents are shown the image itself, so the coding model must be one that reads images - the regeneration stops, saying so, when it is not. Each image is at most 5 MB.
+   - An image says what something looks like, not what it does: the behaviour still belongs in the ***plain's text. Link a mockup from a concept (`:CheckoutPage:` looks as [checkout mockup](resources/checkout.png) shows) and keep the rules - what each button does, which fields are required - in the functional specs.
    - Where the model may not read images, or a detail must be exact (a colour code, a spacing, a label), say it in text as well; the image is the reference, not the only source.
-4. **Another `.plain` file.** `[Auth Module](auth.plain)` is invalid. To reference another module, use the `require` or `import` frontmatter directives. Do not link it as a markdown resource; the renderer will flag this as a syntax error.
+4. **Another `.plain` file.** `[Auth Module](auth.plain)` is invalid. To reference another module, use the `require` or `import` frontmatter directives. Do not link it as a markdown resource; turri will flag this as a syntax error.
 
 ## Never use a URL or folder path as a *reference* in prose
-- The hard constraint above is enforced only on markdown links. A bare URL or folder path in prose (concept body, functional-spec text, implementation reqs, test reqs) passes validation and is fed to the renderer verbatim as part of the spec text
-- That is exactly why it is dangerous as a *reference*: the renderer cannot fetch the URL or open the folder, so the model sees only the address, not the content behind it. To a human reader the line looks grounded in a source; to the renderer it is a *ghost dependency*, and the spec silently drifts from whatever the URL actually says
+- The hard constraint above is enforced only on markdown links. A bare URL or folder path in prose (concept body, functional-spec text, implementation reqs, test reqs) passes validation and is fed to the coding agent verbatim as part of the ***plain's text
+- That is exactly why it is dangerous as a *reference*: the coding agent cannot fetch the URL or open the folder, so it sees only the address, not the content behind it. To a human reader the line looks grounded in a source; to the coding agent it is a *ghost dependency*, and the ***plain silently drifts from whatever the URL actually says
 - A URL or path in prose is fine when the *text itself* is the complete fact:
   - **Runtime values** the produced software uses — the base URL an integration calls, a database connection path, a CLI argument default, an output directory layout
   - **Provenance notes** for a snapshotted resource — recording the canonical URL a file saved under `resources/` was fetched from
-- Litmus test: "Would the renderer benefit from reading the bytes at this URL / folder?" If yes, save it to a file and link the file. If no (the address itself is the fact), it can stay as plain text
+- Litmus test: "Would the coding agent benefit from reading the bytes at this URL / folder?" If yes, save it to a file and link the file. If no (the address itself is the fact), it can stay as plain text
 
 ## Structured protocol artifacts must be linked, never transcribed
 - JSON Schema, OpenAPI / Swagger, GraphQL SDL, Protobuf `.proto`, Avro / Thrift schemas, XML XSDs, AsyncAPI specs, JSON-RPC method definitions, wire-protocol descriptions, payload examples — anything with a formal machine-readable shape — belongs in a file under `resources/` (or another directory within the project)
-- The spec line should describe the *role* of the artifact ("the request body conforms to ...", "the public API surface is defined in ...") rather than its contents
-- Reasons: one source of truth (no drift between prose and schema); the renderer and the generated code can both consume the file directly; schema changes show up cleanly as diffs
+- The ***plain line should describe the *role* of the artifact ("the request body conforms to ...", "the public API surface is defined in ...") rather than its contents
+- Reasons: one source of truth (no drift between prose and schema); the coding agent and the generated code can both consume the file directly; schema changes show up cleanly as diffs
 
 ```plain
 ***definitions***
@@ -41,8 +41,9 @@ A linked resource **must not** be any of the following:
 
 ***functional specs***
 
-- A :User: can add a :Task: by POSTing :TaskCreateRequest: to the `POST /tasks` endpoint of :TasksAPI:.
-  - The endpoint responds per :TasksAPI:.
+# add-task
+A :User: can add a :Task: by POSTing :TaskCreateRequest: to the `POST /tasks` endpoint of :TasksAPI:.
+- The endpoint responds per :TasksAPI:.
 ```
 
 ## Each linked resource is referenced from exactly one place
@@ -58,9 +59,11 @@ A linked resource **must not** be any of the following:
 
 ***functional specs***
 
-- A :User: can add a :Task: using :TaskModalSpec:.
+# add-task
+A :User: can add a :Task: using :TaskModalSpec:.
 
-- A :User: can edit a :Task: using :TaskModalSpec:.
+# edit-task
+A :User: can edit a :Task: using :TaskModalSpec:.
 ```
 
 ## When to link

package/genome/rules/module-structure.md

@@ -9,7 +9,8 @@ When creating a new `.plain` file or reviewing the structure of a whole file, al
 ## File skeleton
 - A `.plain` file is one **module**: optional YAML frontmatter between `---` markers, followed by sections marked with `***section name***` headers
 - The frontmatter, when present, must be the first thing in the file
-- Every content line inside a section must be a `- ` list item — see `bullet-continuation.md`
+- Every content line inside `***definitions***`, `***implementation reqs***`, and `***test reqs***` is a `- ` list item - see `bullet-continuation.md`
+- Every functional spec in `***functional specs***` is a `# <func-id>` heading followed by its body - see `func-specs.md` and `semantic-ids.md`
 - Every line must be as short and plain as its content allows — see `concise-specs.md`
 
 ## Frontmatter fields
@@ -23,21 +24,22 @@ When creating a new `.plain` file or reviewing the structure of a whole file, al
 | `required_concepts` | Declare concepts an import module expects the importing module to define | `required-concepts.md` |
 
 ## Sections
-- There are exactly four top-level section markers: `***definitions***`, `***implementation reqs***`, `***test reqs***`, and `***functional specs***`
+- A module has exactly four top-level section markers: `***definitions***`, `***implementation reqs***`, `***test reqs***`, and `***functional specs***`
 - Each section appears **at most once** per file; all are optional (which ones are allowed depends on the module kind below)
-- `***acceptance tests***` is **never a top-level section** — it appears only nested under a single functional spec (see `func-specs.md`)
+- `***conformance tests***` and `***acceptance tests***` never appear in a module, not even nested under a functional spec; they are the two sections of a test plain file (see `test-plain-files.md`)
 - Write sections in canonical order: `***definitions***` → `***implementation reqs***` → `***test reqs***` → `***functional specs***`
   - Definitions come first because every concept must be defined before it is referenced
-  - Functional specs come last because they are rendered incrementally and their nested acceptance tests close the file
+  - Functional specs come last because each one builds on those before it
 
 ## Module kinds
 - A **root module** lives at the repository root and carries behavior: it contains `***functional specs***`
-- To be renderable, a root module needs at least one functional spec plus the implementation reqs to build it — its own or from an `import`ed module (implementation reqs are not inherited through `requires`). A frontmatter-only file is a valid scaffold, but it cannot be rendered until a functional spec is added
+- To be regenerated, a root module needs at least one functional spec plus the implementation reqs to build it — its own or from an `import`ed module (implementation reqs are not inherited through `requires`). A frontmatter-only file is a valid scaffold, but it cannot be regenerated until a functional spec is added
 - A **requires module** is a root module that is used by another root module via `requires` directive (see `requires-modules.md`)
 - An **import module** provides shared content that other modules pull in via `import`: it contains only `***definitions***`, `***implementation reqs***`, and/or `***test reqs***` — never `***functional specs***`, never `requires` (see `import-modules.md`)
+- A **test plain file** is not a module: it holds the scenarios of one functional spec of a root module, its frontmatter `module:` and `func_id:` bind it to that functional spec, it lives in `tests/<module>/`, and it has none of a module's sections (see `test-plain-files.md`)
 
 ## Section ownership (where a fact lives)
-- The renderer reads each kind of fact **only from its owning section** — a fact placed in the wrong section is silently ignored, not flagged
+- turri reads each kind of fact **only from its owning section** — a fact placed in the wrong section is silently ignored, not flagged
 - Before writing any requirement, place it by content:
 - To move facts that are already misplaced, or to split a bullet carrying several kinds of fact, use the `resolve-section-ownership` skill
 
@@ -47,29 +49,32 @@ When creating a new `.plain` file or reviewing the structure of a whole file, al
 | HOW the software is built — tech stack, architecture, coding standards — and **everything about `:UnitTests:`** | `***implementation reqs***` | `impl-reqs.md` |
 | **Everything about `:ConformanceTests:`** — framework, run command, mocking and network policy | `***test reqs***` | `test-reqs.md` |
 | WHAT the software does — observable, language-agnostic behavior | `***functional specs***` | `func-specs.md` |
-| End-to-end workflow verification of one functional spec | nested `***acceptance tests***` | `func-specs.md` |
+| Test scenarios of one functional spec, conformance and acceptance | its test plain file, `tests/<module>/<func-id>.plain` | `test-plain-files.md` |
 
 ## Comments
-- Lines beginning with `>` are ignored when rendering
+- Lines beginning with `>` are ignored when regenerating
 
 ```plain
 > This is a comment in ***plain.
 ```
 
-- Comments explain the specification to human authors — never use a comment to carry a requirement the renderer must implement
+- Comments explain the ***plain to human authors — never use a comment to carry a requirement the coding agent must implement
 
 ## Liquid templates
 - `.plain` files are processed with [Liquid](https://shopify.github.io/liquid/) before parsing — the full Liquid syntax (variables, filters, conditionals, loops) is available in any section
-- Expansion is **textual** and happens before the specification is interpreted — unlike `import`, which includes another module semantically (see `import-modules.md`)
+- Expansion is **textual** and happens before the ***plain is interpreted — unlike `import`, which includes another module semantically (see `import-modules.md`)
 
 ```plain
 {% assign max_tags = 3 %}
 
 ***functional specs***
 
-- A :Widget: can be created with up to {{ max_tags }} tags.
+# create-widget
+A :Widget: can be created with up to {{ max_tags }} tags.
 {% if max_tags > 1 %}
-- A :Widget: can have its tags listed.
+
+# list-widget-tags
+A :Widget: can have its tags listed.
 {% endif %}
 ```
 
@@ -99,7 +104,9 @@ import:
 
 ***functional specs***
 
-- A :Task: can be added to the :TaskList:.
+# add-task
+A :Task: can be added to the :TaskList:.
 
-- The :TaskList: is displayed.
+# show-task-list
+The :TaskList: is displayed.
 ```