@nurix/etna 0.19.20 → 0.19.22

package/data/harnesses/etna/skills/documentation/scripts/doc-lint.mjs

@@ -0,0 +1,117 @@
+// skills/documentation/scripts/doc-lint.mjs - mechanical checks over markdown docs (tense narration, dates, stubs, redirects)
+// Usage: node doc-lint.mjs <file.md ...> | node doc-lint.mjs --changed   (git-changed + untracked .md)
+// Exit 1 when any block-severity finding survives. Escape hatch: <!-- doc-lint-disable: id[, id] --> (file-wide, or on the offending line).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+
+const RULES = [
+  { id: 'stale-tripwire', severity: 'block', scope: 'truth', pattern: /treat (any )?[\w`./-]+ ?(references? )?as stale|superseded (by|the)|\bused to (be|target|live|hold)\b/i, message: 'stale-reference tripwire / supersession talk — fix the references, state the present fact' },
+  { id: 'history-narration', severity: 'block', scope: 'truth', pattern: /\bno longer\b|\bwas (renamed|removed|extracted|folded|migrated|replaced)\b|\bmoved (to|from|into) [\w`./-]+ \(?20\d{2}/i, message: 'history narration — the journey belongs in a dated record' },
+  { id: 'progress-marker', severity: 'block', scope: 'truth', pattern: /\bphases?\s+\d[^.\n]{0,40}\b(complete|done)\b|\b(build|implementation) (is )?(\d+%|partially) (complete|done)\b/i, message: 'progress marker — progress lives in the plan/backlog record' },
+  { id: 'temporal-hedge', severity: 'warn', scope: 'truth', pattern: /\bnot yet\b|\bfor now\b|\bcurrently\b|\bstill (unsupported|missing|pending|unimplemented|in progress)\b/i, message: 'temporal hedge — state the fact without "currently / not yet / for now"' },
+  { id: 'predecessor-frame', severity: 'warn', scope: 'truth', pattern: /\bpreviously\b|\bthe old \w+\b|\blegacy \w+ (was|is)\b/i, message: 'predecessor framing — describe the one current design' },
+  { id: 'status-glyph', severity: 'warn', scope: 'truth', pattern: /(^|\s)(✅|⏳|- \[[ x]\])/u, message: 'status glyph / checklist in a truth doc — tracking belongs in a record' },
+  { id: 'date-in-truth-doc', severity: 'warn', scope: 'truth', pattern: /\b20\d{2}-\d{2}-\d{2}\b/, message: 'date in a truth doc — only the AD Decision Changelog and structure.md Health Log tails carry dates' },
+];
+
+// Sections inside a truth doc where dated history is sanctioned (the two bridges).
+const BRIDGE_HEADINGS = /^#{1,4}\s+(decision changelog|health log)\b/i;
+// Instruction files and generated trees are a different genre — out of this linter's scope.
+const SKIP = /(^|\/)(\.claude|node_modules|skills|rules|agents|harness|packages\/[^/]+\/data)\/|(^|\/)(CLAUDE|AGENTS)\.md$/;
+const RECORD = /(^|\/)docs\/(history|research|memory)\//;
+
+// Classify a path: skipped genre, record, or truth.
+function scopeOf(path) {
+  if (SKIP.test(path)) return 'skip';
+  return RECORD.test(path) ? 'record' : 'truth';
+}
+
+// Yield prose lines only: frontmatter, fenced code blocks, and bridge sections drop out.
+function proseLines(text) {
+  const lines = text.split('\n');
+  const out = [];
+  let inFence = false;
+  let inFrontmatter = lines[0] === '---';
+  let inBridge = false;
+  let bridgeLevel = 0;
+  for (let i = inFrontmatter ? 1 : 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (inFrontmatter) { if (line === '---') inFrontmatter = false; continue; }
+    if (/^\s*(```|~~~|````)/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const heading = line.match(/^(#{1,4})\s/);
+    if (heading) {
+      if (inBridge && heading[1].length <= bridgeLevel) inBridge = false;
+      if (BRIDGE_HEADINGS.test(line)) { inBridge = true; bridgeLevel = heading[1].length; }
+    }
+    if (!inBridge) out.push({ n: i + 1, line });
+  }
+  return out;
+}
+
+// Collect file-wide disabled rule ids from <!-- doc-lint-disable: a, b --> comments.
+function fileDisables(text) {
+  const ids = new Set();
+  for (const m of text.matchAll(/<!--\s*doc-lint-disable:\s*([\w-,\s]+?)\s*-->/g))
+    m[1].split(',').forEach((id) => ids.add(id.trim()));
+  return ids;
+}
+
+function lintFile(path, findings) {
+  const scope = scopeOf(path);
+  if (scope === 'skip' || !existsSync(path)) return;
+  const text = readFileSync(path, 'utf8');
+  const disabled = fileDisables(text);
+  const lines = proseLines(text);
+
+  const nonEmpty = text.split('\n').filter((l) => l.trim()).length;
+  if (scope === 'truth' && nonEmpty <= 10 && /\b(moved to|relocated to|see [\w`./-]+ instead)\b/i.test(text) && !disabled.has('redirect-doc'))
+    findings.push({ path, n: 1, severity: 'block', id: 'redirect-doc', message: 'redirect stub — delete the file and repoint every inbound link' });
+
+  for (const rule of RULES) {
+    if (rule.scope !== scope || disabled.has(rule.id)) continue;
+    for (const { n, line } of lines) {
+      if (!rule.pattern.test(line)) continue;
+      if (line.includes(`doc-lint-disable: ${rule.id}`) || new RegExp(`doc-lint-disable:[^>]*\\b${rule.id}\\b`).test(line)) continue;
+      findings.push({ path, n, severity: rule.severity, id: rule.id, message: rule.message, excerpt: line.trim().slice(0, 90) });
+    }
+  }
+
+  if (scope === 'truth' && /(^|\/)docs\/features\/[^/]+\.md$/.test(path)) {
+    const fm = text.startsWith('---') ? text.slice(0, text.indexOf('\n---', 3)) : '';
+    for (const key of ['owns:', 'keywords:', 'status:'])
+      if (!fm.includes(key)) findings.push({ path, n: 1, severity: 'block', id: 'feature-frontmatter', message: `feature doc missing \`${key}\` frontmatter` });
+  }
+}
+
+// A changed plan whose committed version is already frozen must not be edited.
+function checkFrozenEdits(paths, findings) {
+  for (const path of paths) {
+    if (!/(^|\/)docs\/history\/(plans|changelog|migrations)\//.test(path)) continue;
+    try {
+      const head = execSync(`git show HEAD:"${path}"`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] });
+      if (/(^|\/)plans\//.test(path) && !/Status:\s*(Complete|Abandoned)/i.test(head)) continue;
+      findings.push({ path, n: 1, severity: 'block', id: 'frozen-record-edit', message: 'frozen record modified — records are never edited; write a new dated record that links back' });
+    } catch { /* new file — creating a record is fine */ }
+  }
+}
+
+const args = process.argv.slice(2);
+let files = args.filter((a) => a !== '--changed');
+const changedMode = args.includes('--changed');
+if (changedMode) {
+  const out = execSync('git diff --name-only HEAD -- "*.md"; git ls-files --others --exclude-standard -- "*.md"', { encoding: 'utf8', shell: '/bin/bash' });
+  files = [...new Set([...files, ...out.split('\n').filter(Boolean)])];
+}
+if (!files.length) { console.error('usage: node doc-lint.mjs <file.md ...> | --changed'); process.exit(2); }
+
+const findings = [];
+files.forEach((f) => lintFile(f, findings));
+if (changedMode) checkFrozenEdits(files.filter((f) => existsSync(f)), findings);
+
+for (const f of findings.sort((a, b) => (a.severity === b.severity ? 0 : a.severity === 'block' ? -1 : 1)))
+  console.log(`${f.path}:${f.n} [${f.severity}] ${f.id} — ${f.message}${f.excerpt ? `: "${f.excerpt}"` : ''}`);
+const blocks = findings.filter((f) => f.severity === 'block').length;
+console.log(`\n${findings.length} finding(s), ${blocks} blocking, ${files.length} file(s) checked.`);
+process.exit(blocks ? 1 : 0);

package/data/harnesses/etna/skills/documentation/templates/Readme.md

@@ -0,0 +1,31 @@
+# Documentation Templates
+
+One file per template. Every template is either a **truth document** (states current absolutes, updated in place) or a **record** (dated account of activity, frozen or append-only) — the split is defined in `SKILL.md` § The Two Natures, and each template names its nature in its opening line.
+
+| Template | File | Nature |
+| --- | --- | --- |
+| Feature (LLD) | [feature.md](feature.md) | Truth |
+| Architecture Decision (AD) | [architecture-decision.md](architecture-decision.md) | Truth (Decision Changelog tail sanctioned) |
+| System overview | [system-overview.md](system-overview.md) | Truth |
+| Domain model | [domain-model.md](domain-model.md) | Truth |
+| Glossary | [glossary.md](glossary.md) | Truth |
+| Non-goals | [non-goals.md](non-goals.md) | Truth |
+| API reference | [api-reference.md](api-reference.md) | Truth |
+| Environment registry | [environment-registry.md](environment-registry.md) | Truth |
+| Security overview | [security-overview.md](security-overview.md) | Truth |
+| Testing strategy | [testing-strategy.md](testing-strategy.md) | Truth |
+| Operations procedure | [operations-procedure.md](operations-procedure.md) | Truth |
+| Protected files | [protected-files.md](protected-files.md) | Truth |
+| Project root README | [root-readme.md](root-readme.md) | Truth |
+| docs/README.md (doc index) | [docs-readme.md](docs-readme.md) | Truth |
+| docs/structure.md (authority map) | [structure.md](structure.md) | Truth (Health Log tail sanctioned) |
+| Plan | [plan.md](plan.md) | Record |
+| Changelog entry | [changelog-entry.md](changelog-entry.md) | Record |
+| Migration runbook | [migration-runbook.md](migration-runbook.md) | Record |
+| CHANGELOG master index | [changelog-index.md](changelog-index.md) | Record index (append-only) |
+| Backlog | [backlog.md](backlog.md) | Record (append-only) |
+| Memory (main agent) | [memory-main.md](memory-main.md) | Record (append-only ledger) |
+
+**Baseline scaffolds** — files that must exist after every baseline; the `maintenance` agent (baseline mode) creates any that are missing: [docs-readme.md](docs-readme.md), [structure.md](structure.md), [changelog-index.md](changelog-index.md), [backlog.md](backlog.md), [memory-main.md](memory-main.md), and [root-readme.md](root-readme.md) (never overwriting an existing root README).
+
+**Ownership.** A feature doc is the canonical reference for the code paths in its **`owns:` frontmatter** — the only ownership key. To find what a doc owns, read its `owns:` globs; to find the doc for a path, match the path against the injected ownership index (the union of every feature's `owns:` globs), narrower glob wins. See [`../references/frontmatter.md`](../references/frontmatter.md) for turning code into `owns:` globs.

package/data/harnesses/etna/skills/documentation/templates/api-reference.md

@@ -0,0 +1,20 @@
+# API Reference (docs/architecture/api.md)
+
+Truth document. Use for: the consolidated catalog of the system's HTTP surface — every live route in one place. This is the **index**: request/response shapes stay in the owning feature docs; this doc answers "what exists and where is it documented." If the repo generates an OpenAPI spec, this doc points at it and carries only what the spec can't (auth model, conventions, ownership links).
+
+Required: **Conventions**, the **route tables**. One row per live route; a route that isn't here doesn't exist.
+
+```
+# API Reference
+
+## Conventions
+
+- Base path: `/api/v{N}` · Auth: {scheme} · Envelope: `{ "status": 1, "message": "...", "data": {...} }`
+- Errors: `{ "status": 0, "message": "...", "data": null }` · Codes: 200/201/400/401/403/404/500
+
+## {Resource group}
+
+| Method | Path | Purpose | Auth | Owning doc |
+| ------ | ---- | ------- | ---- | ---------- |
+| GET | `/api/foo` | {one line} | {role} | [feature](../features/{feature}.md) |
+```

package/data/harnesses/etna/skills/documentation/templates/architecture-decision.md

@@ -0,0 +1,121 @@
+# Architecture Decision (AD)
+
+Truth document — with the one sanctioned dated tail. Use for: the standing decision on one architectural **subject** — a system shape, a contract, a substrate choice. Lives in `docs/architecture/decisions/`. The body always states the current decision and its current reasoning. When the decision moves, rewrite the affected sections to what is now true, bump `last-updated`, and append the revision to the **Decision Changelog** — the journey lives in that tail, never in the body. Head is truth; tail is provenance.
+
+### One subject per AD
+
+The unit is the subject, not the individual call. "The persistence layer", "auth", "the design-skill architecture" are subjects; every decision, reversal, and re-decision on a subject lands in that subject's one AD, however many times it moves. Write a second AD only when a genuinely separate subject emerges — never to record a revision of an existing one.
+
+### When to write an AD
+
+Write an AD when **all three** apply:
+
+1. The decision is architectural — affects system shape, contracts, or substrate choice, not internal implementation
+2. Alternatives were genuinely considered and rejected
+3. Future maintainers will ask "why is it this way?"
+
+Don't write an AD for:
+
+- Standing principles or style preferences (those are stances, not decisions — put them in `docs/architecture/`)
+- Routine implementation choices with no rejected alternatives
+- Anything you'd be happy reversing without ceremony
+
+### Lifecycle
+
+`Proposed` → `Accepted` → `Deprecated`
+
+Frontmatter `status:` is the single lifecycle source of truth. An AD stays `Accepted` for as long as its subject is live — revisions rewrite the body and never change the status, and there is **no `Superseded` state**: supersession is an edit plus a changelog entry, not a new document. Set `Deprecated` only when the subject itself is retired (the component is gone, the contract no longer exists); state where the replacement lives, if any.
+
+### Naming
+
+`AD-NNN-short-title.md` — three-digit zero-padded number, kebab-case subject. Numbers are assigned sequentially across the project and never reused.
+
+### Structure
+
+Three sections are required: **Decision**, **Context**, **Consequences** — plus the **Decision Changelog** once the AD has been revised at least once. Everything else is optional — include only when warranted. Decision-first: readers should see the answer in the first paragraph.
+
+### Template
+
+```markdown
+---
+title: "AD-NNN: Short title in sentence case"
+status: Accepted # Proposed | Accepted | Deprecated
+created: YYYY-MM-DD
+last-updated: YYYY-MM-DD # bump on every revision
+decision-owner: Name
+reviewers: [] # optional
+tags: [ad]
+---
+
+# AD-NNN: Short Title
+
+## Decision
+
+[One paragraph, active voice. "We will…" Lead with the answer — the current answer, whatever the journey was.]
+
+## Context
+
+[The forces in play. What is the problem? Why does it need a decision? Technical, political, social, and project-local pressures — stated as present-tense forces, not as a history of the subject.]
+
+## Consequences
+
+**Positive:**
+
+- [What becomes easier]
+
+**Negative:**
+
+- [What becomes harder, what we accept reluctantly]
+
+**Risks:**
+
+- [Second-order effects you can already see, with mitigations if known]
+
+<!-- Optional sections below. Include only when warranted by the decision's weight. -->
+
+## Decision Drivers
+
+[Hard non-negotiables vs. strong levers. Include when alternatives exist and the criteria aren't self-evident from Context.]
+
+## Options Considered
+
+| Option       | Pros | Cons | Outcome               |
+| ------------ | ---- | ---- | --------------------- |
+| **Option A** | …    | …    | **CHOSEN**            |
+| Option B     | …    | …    | Eliminated — [reason] |
+
+## Deep Comparison
+
+[Honest framing of the strongest alternative(s). Include when the table doesn't make the reasoning obvious. State the *real* reason each was rejected — not a strawman.]
+
+## Architecture in Detail
+
+[Diagrams, code shape, layer responsibilities. Include when the decision implies non-trivial structure that readers need to understand alongside the *why*. Execution belongs in a plan doc (`docs/history/plans/`) — link to it, don't embed an implementation plan here.]
+
+## Open Questions
+
+1. **[Question]** — _Default_: [stated default until resolved].
+
+## References
+
+- [External link or cross-reference]
+
+## Decision Changelog
+
+<!-- The provenance tail — append-only, newest first. One entry per revision: what changed, the trigger, the previous choice, and the plan that implemented it. Added on the first revision; the initial acceptance is the last entry. -->
+
+- YYYY-MM-DD — [What changed] because [trigger]. Implemented by [plan link]. (Previously: [old choice].)
+- YYYY-MM-DD — Initial decision accepted. Implemented by [plan link].
+```
+
+### Rules
+
+- **One subject per AD; all its revisions stay inside it.** Two genuinely different subjects means two ADs — a revision of an existing subject never does.
+- **The body is always the current truth.** Rewrite affected sections on every revision; never leave a superseded choice narrated in the body — the Decision Changelog carries the journey, with each entry naming the old choice and the trigger.
+- Decision-first. The first paragraph after the heading is the answer; readers should not need to scroll.
+- **Consequences lists positives, negatives, AND risks.** Pros-only Consequences is the genre's classic failure — one AD's honest resulting context is the input context for the next.
+- **Options Considered keeps every genuinely rejected alternative with the real reason.** Informed rejections are the most expensive knowledge to lose; a rejection made with strong prior art in view says so explicitly.
+- **Keep it short — one to two pages.** Long decision docs don't get updated. How-it-works detail belongs in the owning feature doc; execution in a plan. Link, don't embed.
+- No section numbering (`§5.1.1`). Use markdown headings only — inserting a section shouldn't renumber everything.
+- Frontmatter `status` is the single source of truth for lifecycle. Don't also write "Status: Accepted" in the body.
+- The Decision Changelog is append-only, newest first. Typo and formatting fixes don't get entries.

package/data/harnesses/etna/skills/documentation/templates/backlog.md

@@ -0,0 +1,33 @@
+# Scaffold: docs/history/backlog.md
+
+Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/history/backlog.md`.
+
+```
+# Backlog
+
+Tracked work items, technical debt, and planned improvements. Append new items under the appropriate priority.
+
+---
+
+## Format
+
+- **[P0]** Description — discovered by [plan-name or agent-name]
+
+---
+
+## P0 — Critical
+
+{items here}
+
+## P1 — High
+
+{items here}
+
+## P2 — Medium
+
+{items here}
+
+## P3 — Low
+
+{items here}
+```

package/data/harnesses/etna/skills/documentation/templates/changelog-entry.md

@@ -0,0 +1,62 @@
+# Changelog
+
+Record. Use for: recording code changes with function-level detail. Entries are frozen once written — they describe the change as it shipped, and are never edited to match later reality.
+
+Change categories follow the Keep a Changelog vocabulary — **Added / Changed / Deprecated / Removed / Fixed / Security** — the same six the master `CHANGELOG.md` scaffold instructs. Include only the categories that apply; all six share the same bullet shape (function/file, then detail lines).
+
+```
+# YYYY-MM-DD - [Title]
+
+## Summary
+
+Brief description of what changed and why.
+
+## Changes
+
+### Added
+- `newFunction(params)` in `path/to/file.js`
+  - Purpose: What it does
+  - Used by: Where it's called
+
+### Changed
+- `existingFunction()` in `path/to/file.js`
+  - Changed: What's different
+  - Reason: Why it changed
+  - Migration: What callers must do
+
+### Removed
+- `oldFunction()` from `path/to/file.js`
+  - Replaced by: `newFunction()`
+
+### Fixed
+- `buggyFunction()` in `path/to/file.js`
+  - Bug: What was wrong, when it manifested
+  - Fix: What changed
+
+(Deprecated / Security follow the same shape.)
+
+## Breaking Changes
+
+⚠️ **[Change description]**
+- Old: Previous behavior
+- New: Current behavior
+- Impact: What breaks
+- Migration: How to fix
+
+## Migration Steps
+
+Numbered instructions for whoever applies the change — not a tracked task list (the entry is frozen once written):
+
+1. {Step}
+2. {Step}
+
+## Verified
+
+- What was exercised end-to-end and the observed result — real runs, real fixtures, measured timings
+- A future agent diagnosing a regression starts from this evidence
+
+## Files Changed
+
+- `src/path/file1.js` - Core changes
+- `src/path/file2.js` - Supporting updates
+```

package/data/harnesses/etna/skills/documentation/templates/changelog-index.md

@@ -0,0 +1,41 @@
+# Scaffold: docs/history/CHANGELOG.md
+
+Baseline scaffold — created if missing (the `maintenance` agent's baseline calls this). Target file: `docs/history/CHANGELOG.md`.
+
+```
+# Changelog
+
+All notable changes to {Project Name} will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+---
+
+## [Unreleased]
+
+{entries added here as work proceeds; promoting them under a release heading is the one sanctioned edit to this index — the dated entry files themselves stay frozen}
+
+---
+
+## Links
+
+- [Setup Guide](../operations/setup.md)
+- [Architecture](../architecture/)
+
+---
+
+## How to Update This Changelog
+
+1. Create a dated change file in `docs/history/changelog/`:
+   `docs/history/changelog/YYYY-MM-DD-feature-name.md`
+
+2. Update this CHANGELOG.md with a high-level summary linking to the detail file
+
+3. Follow Keep a Changelog categories:
+   - **Added** for new features
+   - **Changed** for changes in existing functionality
+   - **Deprecated** for soon-to-be removed features
+   - **Removed** for now removed features
+   - **Fixed** for bug fixes
+   - **Security** for security improvements
+```

package/data/harnesses/etna/skills/documentation/templates/docs-readme.md

@@ -0,0 +1,70 @@
+# docs/README.md (Documentation Root)
+
+Truth document. Use for: the entry point for all documentation in a repo. Created during baseline audit.
+
+```
+# {Project Name} Documentation
+
+Technical documentation for {project description}.
+
+> For documentation organization, authority map, and folder rules, see **[structure.md](structure.md)**.
+
+---
+
+## Quick Links
+
+| Document                          | Description                          |
+| --------------------------------- | ------------------------------------ |
+| [Structure](structure.md)         | Documentation entry point and rules  |
+| [Setup](operations/setup.md)      | Installation and configuration guide |
+
+---
+
+## Architecture
+
+System design, steering docs, and standing decisions — the truth layer.
+
+- [system-design.md](architecture/system-design.md) - System overview: subsystems and key flows
+- [domain-model.md](architecture/domain-model.md) - Entities, relationships, state ownership
+- [glossary.md](architecture/glossary.md) - Project vocabulary
+- [non-goals.md](architecture/non-goals.md) - What this system deliberately does not do
+- [decisions/](architecture/decisions/Readme.md) - Architecture Decisions (ADs)
+{list other architecture docs — api.md, security.md — when present}
+
+---
+
+## Features
+
+Living reference docs for implemented features (how things currently work).
+
+- [feature-name.md](features/feature-name.md) - Feature description
+{list all feature docs}
+
+---
+
+## Operations
+
+How to run, develop, and deploy.
+
+- [setup.md](operations/setup.md) - Installation and configuration guide
+{list all operations docs — environment.md when present}
+
+---
+
+## History
+
+The records — everything dated, frozen, or append-only.
+
+- [CHANGELOG.md](history/CHANGELOG.md) - Master changelog index
+- [changelog/](history/changelog/) - Individual changelog entries
+- [plans/](history/plans/) - Implementation plans (frozen at completion)
+- [migrations/](history/migrations/) - One-shot migration runbooks (frozen once executed)
+- [research/](history/research/) - Deep-research artifacts (one folder per topic)
+- [backlog.md](history/backlog.md) - Tracked work items and technical debt
+
+---
+
+## Contributing
+
+See [CLAUDE.md](../CLAUDE.md) for documentation guidelines.
+```

package/data/harnesses/etna/skills/documentation/templates/domain-model.md

@@ -0,0 +1,30 @@
+# Domain Model (docs/architecture/domain-model.md)
+
+Truth document. Use for: the entities the system is about — what they are, how they relate, and who owns their state. The vocabulary here must match the glossary and the code; when they disagree, fix the disagreement, don't document around it.
+
+Required: **Entities**, **Relationships**. Optional: Lifecycle states, Invariants.
+
+```
+# Domain Model
+
+## Entities
+
+| Entity | What it is | State lives in |
+| ------ | ---------- | -------------- |
+| {Entity} | {one line} | {table / slice / service} |
+
+## Relationships
+
+- {EntityA} 1—N {EntityB} — {the meaning of the link}
+- {EntityB} N—N {EntityC} via {join} — {meaning}
+
+## Lifecycle states
+
+{Only for entities with real state machines.}
+
+- **{Entity}**: draft → active → archived — {what moves it between states}
+
+## Invariants
+
+- {A relationship or state rule that must always hold, stated as a constraint}
+```

package/data/harnesses/etna/skills/documentation/templates/environment-registry.md

@@ -0,0 +1,15 @@
+# Environment Registry (docs/operations/environment.md)
+
+Truth document. Use for: the config surface — every variable the code reads, in one table. `.env.example` mirrors this doc's variable list.
+
+**Placeholders only, never real values.** A real-looking password, account ID, or personal profile name in a doc is a leak, and one developer's local setup written as the canonical value is a trap for everyone else. Values in this doc are `{placeholder}` descriptions.
+
+```
+# Environment Registry
+
+Every variable the code reads. `.env.example` mirrors this list.
+
+| Variable | Purpose | Required | Where set | Secret |
+| -------- | ------- | -------- | --------- | ------ |
+| `DATABASE_URL` | {one line} | yes / default: `{value}` | local `.env` / CI / prod | yes |
+```