@nurix/etna 0.20.25 → 0.20.27

package/data/harnesses/etna/skills/documentation/references/examples.md

@@ -146,37 +146,41 @@ Replaced change-tracking merge with version-based conflict resolution.
 
 ---
 
-## Example 4: Data Flow
+## Example 4: Flow
 
-### ❌ Bad: Prose Description
+### ❌ Bad: Mechanism narrated in a paragraph
 
 ```markdown
+## Data Flow
+
 When the page loads, the useAppInit hook calls the syncData function. This function first fetches data from the server using the API. Then it gets the local data from Redux. After that, it compares versions...
 ```
 
-### ✅ Good: Diagram + Key Points
+**Problems:** names a hook, a function and a store that a rename would invalidate (the stability test); runs parallel cases together in one paragraph; gives a scanning reader no label to land on; "Data Flow" is a retired mechanism section.
 
-```markdown
-## Data Flow
+### ✅ Good: Labelled bullets, a role-level diagram beside them
 
-┌─────────────────────────────────────────┐
-│               DATA SYNC                 │
-├─────────────────────────────────────────┤
-│                                         │
-│   ┌──────┐     ┌──────┐     ┌──────┐    │
-│   │Server│────▶│Merge │────▶│Redux │    │
-│   │ API  │     │      │     │Store │    │
-│   └──────┘     └──────┘     └──────┘    │
-│        │                                │
-│        ▼                                │
-│   Version Check                         │
-│                                         │
-└─────────────────────────────────────────┘
-
-**Trigger:** `useAppInit()` on page load
-
-**Version Rule:** Match → local wins, Mismatch → server wins
+````markdown
+## Flows
+
+### Page load
+
+- **Fresh data:** the page fetches the server's copy and the local copy on every load; nothing is cached between visits.
+- **Matching versions:** local changes win and are kept.
+- **Mismatched versions:** the server's copy wins and local changes are dropped.
+
+```mermaid
+sequenceDiagram
+  participant Page
+  participant Server
+  participant Store
+  Page->>Server: fetch the server's copy
+  Page->>Store: read the local copy
+  Page->>Store: write the merged copy
 ```
+````
+
+**Why it works:** every fact is in the bullets, so a reader who greps finds it without the diagram; the labels are noun phrases a scanning reader lands on; the diagram names roles, never a function or a file, so no rename touches it.
 
 ---
 
@@ -242,7 +246,7 @@ The feature doc states only what is:
 ```markdown
 ## Export Pipeline
 
-`src/export/run.js` renders every export format from one job queue. Output is
+The exporter renders every export format from one job queue. Output is
 buffered per job (streaming is out of scope — see `docs/history/backlog.md`).
 ```
 
@@ -272,8 +276,8 @@ Extracted export logic from the `reports` worker into `src/export/`.
 | ---------- | -------------------- | --------------------------- |
 | Code       | Full implementations | Signatures + contracts      |
 | State      | Every occurrence     | Persistence points only     |
-| Flows      | Prose paragraphs     | ASCII diagrams              |
+| Flows      | Paragraphs naming functions | Labelled bullets in plain words, a role-level diagram beside them |
 | Changelogs | "Updated X"          | Function names + migrations |
 | Decisions  | New doc per revision | One AD per subject, updated in place |
 | History    | Narrated in the doc  | Present-tense doc + dated record |
-| Length     | 100+ lines           | 20-40 lines                 |
+| Length     | Padded with mechanism | The genre's own expectation; length is a signal, never a target |

package/data/harnesses/etna/skills/documentation/references/frontmatter.md

@@ -32,7 +32,7 @@ Every other genre owns no code and carries no `owns:`. That includes the cross-c
 
 ## How to derive the frontmatter
 
-An owning doc's ownership frontmatter is `owns:` (required), `module:` (optional — feature docs only; a package is already a bounded unit and a system spans contexts by definition), `keywords:` (required), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key. `slug:` completes the set on generated docs: the identity key, minted once at creation and never re-derived from a display name — in the repo the filename is the slug, and the `maintenance` agent re-aligns the two when they diverge.
+An owning doc's frontmatter is `objects:` (required — the product objects it designs, by their graph names; its discovery terms and its traced edge into the knowledge graph), `owns:` (required until the graph computes ownership from traces), `module:` (optional — feature docs only; a package is already a bounded unit and a system spans contexts by definition), and `status:` (required). An optional `last-reviewed:` date (stamped whenever the doc is substantively reviewed or updated) gives the `maintenance` agent a staleness signal to rank its audits by — it is tooling metadata, never narrated in the body. `type:` (required — the genre, enum = the template names) and `rev:` (generator-written generation stamp) are the same class: external tooling reads them, sessions **preserve them on edits** and never narrate or inject them. The `maintenance` agent stamps `type:` on docs that predate the key. `slug:` completes the set on generated docs: the identity key, minted once at creation and never re-derived from a display name — in the repo the filename is the slug, and the `maintenance` agent re-aligns the two when they diverge.
 
 **1. `owns:`** (the path scope)
 
@@ -59,9 +59,9 @@ Glob each pattern against the codebase. At `status: active`, drop any that match
 
 The single bounded-context label this feature belongs to, or omit it for a cross-cutting feature that belongs to no single context. A module is a label, not a folder — features sharing a `module:` value are what ties that module to code (a filter over the generated ownership index). Package and system docs omit it entirely.
 
-**3. `keywords:` & `status:`**
+**3. `objects:` & `status:`**
 
-`keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
+`objects:` names the product objects the document designs — the discovery terms topic→doc lookup rides, and the edge the knowledge graph renders each object's documents from. There is no `keywords:` key: an object's name is its discovery term. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
 
 ## The doc → doc edges