@lifeaitools/rdc-skills 0.25.5 → 0.25.9

package/skills/regen-media/SKILL.md

@@ -1,94 +1,94 @@
----
-name: rdc:regen-media
-description: "Usage `rdc:regen-media <generate|edit|upscale|upload> <brief-or-path>` - Primary image-generation and Regen Media asset workflow. Use for image generation, image editing/upscaling, GPT Image/gpt-image-2 requests, Codex built-in image_gen, and uploading finished images to regen-media/R2. The default path is keyless local Codex gpt-image-2 via the built-in image_gen tool; server-side regen-media MCP/API generation is fallback only."
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
-> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
-
-> **Sandbox contract:** This skill honors `RDC_TEST=1`. Under `RDC_TEST=1`, do not call Codex image generation, OpenAI, regen-media APIs, upload endpoints, clauth credentials, or external services. Print the planned command and output paths only.
-
-# rdc:regen-media
-
-Primary image-generation and asset-ingest workflow for Regen Media.
-
-## Default Decision
-
-Use local Codex built-in `image_gen` with `gpt-image-2` first when all are true:
-
-- The caller is local Codex with `codex` CLI available.
-- `codex login status` reports ChatGPT login.
-- `codex features list` includes stable `image_generation`.
-- The task is generation, editing, re-rendering, or upscaling an image.
-
-Use regen-media MCP/API generation only when the local keyless Codex path is unavailable, when running in a remote/cloud session, or when the user explicitly asks for server-side generation.
-
-Use regen-media upload/registration after the image file exists and should become a managed media asset.
-
-## Local Keyless gpt-image-2
-
-Preflight:
-
-```bash
-codex login status
-codex features list
-```
-
-Requirements for size to apply:
-
-1. Use `--enable image_generation`.
-2. Use `-c model=gpt-5.5`.
-3. Instruct Codex: `use the built-in image_gen tool DIRECTLY; do not write API keys, scripts, or MCP`.
-4. Name the target size in the instruction, such as `2048x1152`, `2048x2048`, or `3840x2160`.
-
-Text to image:
-
-```bash
-echo "Use the built-in image_gen tool DIRECTLY at size 3840x2160 (4K). No API keys/scripts/MCP. Copy the PNG to output/imagegen/<name>.png and reply with only that path + pixel dims. Prompt: <dense art-directed prompt>." | codex exec --enable image_generation --dangerously-bypass-approvals-and-sandbox --cd "$PWD" -c model=gpt-5.5
-```
-
-Image edit, re-render, or upscale:
-
-```bash
-echo "Use the built-in image_gen tool DIRECTLY to re-render the ATTACHED image at size 3840x2160 (4K), preserving its composition, subject, palette, and lighting. No API keys/scripts/MCP. Save to output/imagegen/<name>-4k.png and reply with only the path + dims." | codex exec -i "input/source.png" --enable image_generation --dangerously-bypass-approvals-and-sandbox --cd "$PWD" -c model=gpt-5.5
-```
-
-Notes:
-
-- The keyless path uses the local ChatGPT Pro OAuth in the Codex install, not `OPENAI_API_KEY`.
-- Output may land both in the requested path and under `~/.codex/generated_images/<session-id>/ig_*.png`.
-- Use a long timeout or background session; generation commonly takes 2-5 minutes.
-- Valid `gpt-image-2` sizes include `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`, `3840x2160`, `2160x3840`, and `auto`, subject to model constraints.
-
-## Upload to Regen Media
-
-After generation, upload finished images through the project uploader when available:
-
-```powershell
-powershell.exe -ExecutionPolicy Bypass -File "{PROJECT_ROOT}/scripts/upload-to-media.ps1" "output/imagegen/<name>.png"
-```
-
-The uploader obtains `regen-media-api` from clauth and posts to Regen Media. Never print credential values. If upload is not required, return the local artifact path and dimensions.
-
-## Server-Side Fallback
-
-Use the deployed regen-media MCP/API generation path only when the local Codex image tool is unavailable or inappropriate. This path is credentialed, server-side, and may require an OpenAI/API key configured for the service. Treat it as fallback for generation, not the default.
-
-## Procedure
-
-1. Classify the task: `generate`, `edit`, `upscale`, or `upload`.
-2. If `RDC_TEST=1`, print the selected path and planned commands without executing external calls.
-3. For generation/edit/upscale, attempt the local keyless Codex preflight.
-4. Build the Codex `exec` command with the requested size and explicit built-in `image_gen` instruction.
-5. Save to `output/imagegen/` or a caller-provided path.
-6. Verify the file exists and record pixel dimensions.
-7. If the artifact should be managed, upload it to Regen Media and return the media URL/slug plus local path.
-8. If local Codex is unavailable, use the server-side regen-media generation fallback and clearly say that it is the fallback path.
-
-## Boundaries
-
-- Do not write or expose API keys.
-- Do not silently downgrade from local keyless `gpt-image-2` to server-side MCP/API generation.
-- Do not use prompt-only size hints; always set the Codex command and instruction shape above.
-- Do not run generation or upload in test mode.
+---
+name: rdc:regen-media
+description: "Usage `rdc:regen-media <generate|edit|upscale|upload> <brief-or-path>` - Primary image-generation and Regen Media asset workflow. Use for image generation, image editing/upscaling, GPT Image/gpt-image-2 requests, Codex built-in image_gen, and uploading finished images to regen-media/R2. The default path is keyless local Codex gpt-image-2 via the built-in image_gen tool; server-side regen-media MCP/API generation is fallback only."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> **Sandbox contract:** This skill honors `RDC_TEST=1`. Under `RDC_TEST=1`, do not call Codex image generation, OpenAI, regen-media APIs, upload endpoints, clauth credentials, or external services. Print the planned command and output paths only.
+
+# rdc:regen-media
+
+Primary image-generation and asset-ingest workflow for Regen Media.
+
+## Default Decision
+
+Use local Codex built-in `image_gen` with `gpt-image-2` first when all are true:
+
+- The caller is local Codex with `codex` CLI available.
+- `codex login status` reports ChatGPT login.
+- `codex features list` includes stable `image_generation`.
+- The task is generation, editing, re-rendering, or upscaling an image.
+
+Use regen-media MCP/API generation only when the local keyless Codex path is unavailable, when running in a remote/cloud session, or when the user explicitly asks for server-side generation.
+
+Use regen-media upload/registration after the image file exists and should become a managed media asset.
+
+## Local Keyless gpt-image-2
+
+Preflight:
+
+```bash
+codex login status
+codex features list
+```
+
+Requirements for size to apply:
+
+1. Use `--enable image_generation`.
+2. Use `-c model=gpt-5.5`.
+3. Instruct Codex: `use the built-in image_gen tool DIRECTLY; do not write API keys, scripts, or MCP`.
+4. Name the target size in the instruction, such as `2048x1152`, `2048x2048`, or `3840x2160`.
+
+Text to image:
+
+```bash
+echo "Use the built-in image_gen tool DIRECTLY at size 3840x2160 (4K). No API keys/scripts/MCP. Copy the PNG to output/imagegen/<name>.png and reply with only that path + pixel dims. Prompt: <dense art-directed prompt>." | codex exec --enable image_generation --dangerously-bypass-approvals-and-sandbox --cd "$PWD" -c model=gpt-5.5
+```
+
+Image edit, re-render, or upscale:
+
+```bash
+echo "Use the built-in image_gen tool DIRECTLY to re-render the ATTACHED image at size 3840x2160 (4K), preserving its composition, subject, palette, and lighting. No API keys/scripts/MCP. Save to output/imagegen/<name>-4k.png and reply with only the path + dims." | codex exec -i "input/source.png" --enable image_generation --dangerously-bypass-approvals-and-sandbox --cd "$PWD" -c model=gpt-5.5
+```
+
+Notes:
+
+- The keyless path uses the local ChatGPT Pro OAuth in the Codex install, not `OPENAI_API_KEY`.
+- Output may land both in the requested path and under `~/.codex/generated_images/<session-id>/ig_*.png`.
+- Use a long timeout or background session; generation commonly takes 2-5 minutes.
+- Valid `gpt-image-2` sizes include `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `2048x1152`, `3840x2160`, `2160x3840`, and `auto`, subject to model constraints.
+
+## Upload to Regen Media
+
+After generation, upload finished images through the project uploader when available:
+
+```powershell
+powershell.exe -ExecutionPolicy Bypass -File "{PROJECT_ROOT}/scripts/upload-to-media.ps1" "output/imagegen/<name>.png"
+```
+
+The uploader obtains `regen-media-api` from clauth and posts to Regen Media. Never print credential values. If upload is not required, return the local artifact path and dimensions.
+
+## Server-Side Fallback
+
+Use the deployed regen-media MCP/API generation path only when the local Codex image tool is unavailable or inappropriate. This path is credentialed, server-side, and may require an OpenAI/API key configured for the service. Treat it as fallback for generation, not the default.
+
+## Procedure
+
+1. Classify the task: `generate`, `edit`, `upscale`, or `upload`.
+2. If `RDC_TEST=1`, print the selected path and planned commands without executing external calls.
+3. For generation/edit/upscale, attempt the local keyless Codex preflight.
+4. Build the Codex `exec` command with the requested size and explicit built-in `image_gen` instruction.
+5. Save to `output/imagegen/` or a caller-provided path.
+6. Verify the file exists and record pixel dimensions.
+7. If the artifact should be managed, upload it to Regen Media and return the media URL/slug plus local path.
+8. If local Codex is unavailable, use the server-side regen-media generation fallback and clearly say that it is the fallback path.
+
+## Boundaries
+
+- Do not write or expose API keys.
+- Do not silently downgrade from local keyless `gpt-image-2` to server-side MCP/API generation.
+- Do not use prompt-only size hints; always set the Codex command and instruction shape above.
+- Do not run generation or upload in test mode.

package/skills/release/SKILL.md

@@ -1,140 +1,140 @@
----
-name: rdc:release
-description: "Usage `rdc:release <repo> [version|--patch|--minor|--major|--dry-run]` — bump, commit, tag, push, wait for CI/publish, install, and verify a package or project using repo-local release metadata."
----
-
-> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
-> Checklist-only output. No tool-call narration. No raw git/npm/CI dumps.
-> One checklist upfront, updated in place, shown again at end with 1-line verdict.
-
-> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
-
-# rdc:release — Generic Release
-
-## When to Use
-
-- The user explicitly asks to release, publish, promote, ship, tag, or bump a repo.
-- A package or app needs versioning plus verification.
-- A repo provides release metadata in `package.json`, `.rdc/release.json`, README release instructions, or CI config.
-
-Never release without explicit user authorization.
-
-## Inputs
-
-- `rdc:release <repo>` — patch release by default.
-- `rdc:release <repo> <version>` — explicit version.
-- `rdc:release <repo> --patch|--minor|--major`
-- `rdc:release <repo> --dry-run`
-
-If `<repo>` is not resolvable from the current workspace, ask for its local path or GitHub slug.
-
-## Checklist
-
-```
-rdc:release: <repo> vX.Y.Z -> vA.B.C
-[ ] PUBLISH.md status gate: status=active AND prod in environments (block if not)
-[ ] Source path resolved
-[ ] Release metadata read
-[ ] Working tree clean or user-approved dirty scope identified
-[ ] Current version detected
-[ ] New version computed
-[ ] Dry-run gate handled
-[ ] Version files updated
-[ ] Tests/self-test passed
-[ ] Mandatory release code-review (pr-review-toolkit:code-reviewer on `git diff <last-released-tag>..HEAD`). Block release on `critical`/`high` findings; record `medium`/`low` in the release notes and proceed.
-[ ] Commit created
-[ ] Tag created
-[ ] Branch and tag pushed
-[ ] CI/publish status verified
-[ ] Registry/package/deploy target shows vA.B.C, if applicable
-[ ] Local install/update executed, if applicable
-[ ] Installed/runtime version verified
-[ ] Smoke test passed
-✅ rdc:release <repo>: vA.B.C live and verified
-```
-
-## PUBLISH.md Status Gate (Step 0 — before any production-touching step)
-
-Before touching any production system, read `PUBLISH.md` from the app root and validate promotion eligibility.
-
-```bash
-PUBLISH_MD="<monorepo_path>/PUBLISH.md"
-```
-
-**Block promotion if ANY of the following are true:**
-
-1. **PUBLISH.md is missing AND the app has a row in `app_deployments`** — emit warn and continue (during rollout period); becomes a hard block after Option A rollout is complete.
-2. **PUBLISH.md exists AND `status` field is NOT `active`** — hard block regardless of rollout status.
-   - `status: draft` → `BLOCKED: PUBLISH.md status=draft for <slug> — promote requires status=active`
-   - `status: deprecated` → `BLOCKED: PUBLISH.md status=deprecated for <slug> — promote requires status=active`
-3. **PUBLISH.md exists AND `environments` array does not include `prod`** → `BLOCKED: PUBLISH.md environments=[dev] for <slug> — prod must be declared before promotion`
-4. **Any required surface field is missing** (`source_dir` or `path` absent on any surface) → `BLOCKED: PUBLISH.md surface <id> missing required field for <slug>`
-
-If blocked, abort immediately with the message above. Do NOT proceed to the version bump, commit, or any Coolify call.
-
-If PUBLISH.md is absent and app has no `app_deployments` row (library/package), skip this gate.
-
-## Resolution Order
-
-1. Current repo if `<repo>` is `.` or omitted and the user clearly refers to the current workspace.
-2. Sibling directory matching `<repo>`.
-3. GitHub slug `<owner>/<repo>`.
-4. Repo-local `.rdc/release.json` if present.
-5. Ask for the missing path or release mechanism.
-
-## Generic Commands
-
-Use repo-local package tooling when available. Examples:
-
-```bash
-npm version patch --no-git-tag-version
-npm test
-git add package.json package-lock.json
-git commit -m "chore(release): vA.B.C"
-git tag vA.B.C
-git push origin HEAD
-git push origin vA.B.C
-npm view <package-name> version
-```
-
-Never use `--force` or bypass hooks. If a hook fails, fix the cause.
-
-## ⛔ Standalone-repo staging guard (no `git add -A`)
-
-Standalone repos (`rdc-skills`, `clauth`, `build-corpus`) have NO pre-commit
-doc-sync/scope guard to catch contamination. In them:
-
-- **REFUSE `git add -A` / `git add .`.** Stage explicit declared paths only
-  (`git add skills/<name>/SKILL.md package.json ...`).
-- Run `git status --porcelain` FIRST. If untracked files exist that are not part
-  of the declared change, STOP — list or stash them; do not sweep them in.
-- **Pre-tag guard: refuse to tag if `git diff --cached --name-only` includes any
-  path outside the declared change set.** A broad add swept 4 pre-existing
-  untracked skill files into a tagged release that CI published before anyone
-  noticed (lesson 2026-06-08-release-git-add-all-swept-untracked-wip). Same
-  dirty-tree contamination class as a lockfile generated against a dirty tree.
-
-## ⛔ Cross-platform prepack + verify the PUBLISHED tarball
-
-- **Prepack must be OS-agnostic.** A bash-style `prepack` chain (`node A || true && node B || true && node stamp`) short-circuits under Windows **cmd.exe** (npm runs lifecycle scripts via cmd, not bash; `true` is not a cmd builtin and `||`/`&&` evaluate differently), so an appended step silently never runs (lesson 2026-06-13-release-windows-cmd-prepack-shortcircuit). When a prepack step must run cross-platform, use a node wrapper / `shx` / `cross-env` — never rely on `|| true` shell semantics that differ between cmd and bash.
-- **Validate the PUBLISHED artifact, not a local Windows `npm pack`.** A local Windows `npm pack` is NOT a faithful rehearsal of the CI (ubuntu/bash) publish. After publish, verify the real tarball:
-  ```bash
-  npm pack <pkg>@<version>            # downloads the PUBLISHED tarball
-  tar -xzOf <pkg>-<version>.tgz package/<file>   # inspect the shipped file
-  ```
-  Confirm the published artifact carries what CI's prepack was supposed to stamp (e.g. `git_sha == tag commit`).
-
-## RDC Skills Package
-
-For this package, prefer the npm installer binary after publish:
-
-```bash
-npm install -g @lifeaitools/rdc-skills@latest
-rdc-skills-install --profile core
-```
-
-Use `--profile lifeai` only on a workstation that intentionally has the LIFEAI project layout and services.
-
-## Capture lessons (exit step)
-
-Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-release-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.
+---
+name: rdc:release
+description: "Usage `rdc:release <repo> [version|--patch|--minor|--major|--dry-run]` — bump, commit, tag, push, wait for CI/publish, install, and verify a package or project using repo-local release metadata."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw git/npm/CI dumps.
+> One checklist upfront, updated in place, shown again at end with 1-line verdict.
+
+> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
+
+# rdc:release — Generic Release
+
+## When to Use
+
+- The user explicitly asks to release, publish, promote, ship, tag, or bump a repo.
+- A package or app needs versioning plus verification.
+- A repo provides release metadata in `package.json`, `.rdc/release.json`, README release instructions, or CI config.
+
+Never release without explicit user authorization.
+
+## Inputs
+
+- `rdc:release <repo>` — patch release by default.
+- `rdc:release <repo> <version>` — explicit version.
+- `rdc:release <repo> --patch|--minor|--major`
+- `rdc:release <repo> --dry-run`
+
+If `<repo>` is not resolvable from the current workspace, ask for its local path or GitHub slug.
+
+## Checklist
+
+```
+rdc:release: <repo> vX.Y.Z -> vA.B.C
+[ ] PUBLISH.md status gate: status=active AND prod in environments (block if not)
+[ ] Source path resolved
+[ ] Release metadata read
+[ ] Working tree clean or user-approved dirty scope identified
+[ ] Current version detected
+[ ] New version computed
+[ ] Dry-run gate handled
+[ ] Version files updated
+[ ] Tests/self-test passed
+[ ] Mandatory release code-review (pr-review-toolkit:code-reviewer on `git diff <last-released-tag>..HEAD`). Block release on `critical`/`high` findings; record `medium`/`low` in the release notes and proceed.
+[ ] Commit created
+[ ] Tag created
+[ ] Branch and tag pushed
+[ ] CI/publish status verified
+[ ] Registry/package/deploy target shows vA.B.C, if applicable
+[ ] Local install/update executed, if applicable
+[ ] Installed/runtime version verified
+[ ] Smoke test passed
+✅ rdc:release <repo>: vA.B.C live and verified
+```
+
+## PUBLISH.md Status Gate (Step 0 — before any production-touching step)
+
+Before touching any production system, read `PUBLISH.md` from the app root and validate promotion eligibility.
+
+```bash
+PUBLISH_MD="<monorepo_path>/PUBLISH.md"
+```
+
+**Block promotion if ANY of the following are true:**
+
+1. **PUBLISH.md is missing AND the app has a row in `app_deployments`** — emit warn and continue (during rollout period); becomes a hard block after Option A rollout is complete.
+2. **PUBLISH.md exists AND `status` field is NOT `active`** — hard block regardless of rollout status.
+   - `status: draft` → `BLOCKED: PUBLISH.md status=draft for <slug> — promote requires status=active`
+   - `status: deprecated` → `BLOCKED: PUBLISH.md status=deprecated for <slug> — promote requires status=active`
+3. **PUBLISH.md exists AND `environments` array does not include `prod`** → `BLOCKED: PUBLISH.md environments=[dev] for <slug> — prod must be declared before promotion`
+4. **Any required surface field is missing** (`source_dir` or `path` absent on any surface) → `BLOCKED: PUBLISH.md surface <id> missing required field for <slug>`
+
+If blocked, abort immediately with the message above. Do NOT proceed to the version bump, commit, or any Coolify call.
+
+If PUBLISH.md is absent and app has no `app_deployments` row (library/package), skip this gate.
+
+## Resolution Order
+
+1. Current repo if `<repo>` is `.` or omitted and the user clearly refers to the current workspace.
+2. Sibling directory matching `<repo>`.
+3. GitHub slug `<owner>/<repo>`.
+4. Repo-local `.rdc/release.json` if present.
+5. Ask for the missing path or release mechanism.
+
+## Generic Commands
+
+Use repo-local package tooling when available. Examples:
+
+```bash
+npm version patch --no-git-tag-version
+npm test
+git add package.json package-lock.json
+git commit -m "chore(release): vA.B.C"
+git tag vA.B.C
+git push origin HEAD
+git push origin vA.B.C
+npm view <package-name> version
+```
+
+Never use `--force` or bypass hooks. If a hook fails, fix the cause.
+
+## ⛔ Standalone-repo staging guard (no `git add -A`)
+
+Standalone repos (`rdc-skills`, `clauth`, `build-corpus`) have NO pre-commit
+doc-sync/scope guard to catch contamination. In them:
+
+- **REFUSE `git add -A` / `git add .`.** Stage explicit declared paths only
+  (`git add skills/<name>/SKILL.md package.json ...`).
+- Run `git status --porcelain` FIRST. If untracked files exist that are not part
+  of the declared change, STOP — list or stash them; do not sweep them in.
+- **Pre-tag guard: refuse to tag if `git diff --cached --name-only` includes any
+  path outside the declared change set.** A broad add swept 4 pre-existing
+  untracked skill files into a tagged release that CI published before anyone
+  noticed (lesson 2026-06-08-release-git-add-all-swept-untracked-wip). Same
+  dirty-tree contamination class as a lockfile generated against a dirty tree.
+
+## ⛔ Cross-platform prepack + verify the PUBLISHED tarball
+
+- **Prepack must be OS-agnostic.** A bash-style `prepack` chain (`node A || true && node B || true && node stamp`) short-circuits under Windows **cmd.exe** (npm runs lifecycle scripts via cmd, not bash; `true` is not a cmd builtin and `||`/`&&` evaluate differently), so an appended step silently never runs (lesson 2026-06-13-release-windows-cmd-prepack-shortcircuit). When a prepack step must run cross-platform, use a node wrapper / `shx` / `cross-env` — never rely on `|| true` shell semantics that differ between cmd and bash.
+- **Validate the PUBLISHED artifact, not a local Windows `npm pack`.** A local Windows `npm pack` is NOT a faithful rehearsal of the CI (ubuntu/bash) publish. After publish, verify the real tarball:
+  ```bash
+  npm pack <pkg>@<version>            # downloads the PUBLISHED tarball
+  tar -xzOf <pkg>-<version>.tgz package/<file>   # inspect the shipped file
+  ```
+  Confirm the published artifact carries what CI's prepack was supposed to stamp (e.g. `git_sha == tag commit`).
+
+## RDC Skills Package
+
+For this package, prefer the npm installer binary after publish:
+
+```bash
+npm install -g @lifeaitools/rdc-skills@latest
+rdc-skills-install --profile core
+```
+
+Use `--profile lifeai` only on a workstation that intentionally has the LIFEAI project layout and services.
+
+## Capture lessons (exit step)
+
+Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-release-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.