geneseed 5.5.0 → 5.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +9 -9
  3. package/SHIPPED.md +1 -1
  4. package/docs/concepts/enforcement-table.md +1 -1
  5. package/docs/concepts/foreman-mode.md +1 -1
  6. package/docs/concepts/hooks.md +1 -1
  7. package/docs/extending.md +1 -1
  8. package/docs/guides/install.md +5 -5
  9. package/docs/reference/profiles.md +84 -0
  10. package/harness.config.json +1 -1
  11. package/js/build/export.mjs +11 -16
  12. package/js/hosts/hooks.mjs +20 -6
  13. package/package.json +1 -1
  14. package/profiles/autonomous.json +14 -0
  15. package/profiles/corporate.json +14 -0
  16. package/profiles/mentor.json +13 -0
  17. package/profiles/minimal.json +15 -0
  18. package/src/agents/devops-engineer.md +6 -5
  19. package/src/agents/kubernetes-specialist.md +3 -1
  20. package/src/agents/spring-boot-engineer.md +3 -3
  21. package/src/agents/spring-reviewer.md +4 -2
  22. package/src/skills/codebase-design.md +2 -2
  23. package/src/skills/commit.md +4 -0
  24. package/src/skills/diagram-design/SKILL.md +12 -7
  25. package/src/skills/diagram-design/VENDOR.md +19 -14
  26. package/src/skills/diagram-design/references/layout-budget.md +7 -1
  27. package/src/skills/diagram-design/references/onboarding.md +1 -1
  28. package/src/skills/diagram-design/references/primitives-core.md +1 -1
  29. package/src/skills/diagram-design/references/semantic-patterns.md +1 -1
  30. package/src/skills/diagram-design/references/style-guide.md +1 -1
  31. package/src/skills/diagram-design/references/type-dependency.md +69 -0
  32. package/src/skills/diagram-design/references/type-event-modeling.md +36 -0
  33. package/src/skills/diagram-design/references/type-requirement-traceability.md +45 -0
  34. package/src/skills/diagram-design/references/type-sbgn.md +80 -0
  35. package/src/skills/diagram-design/references/type-scatter.md +1 -1
  36. package/src/skills/diagram-design/references/type-steps.md +180 -0
  37. package/src/skills/diagram-design/references/type-unit-grid.md +63 -0
  38. package/src/skills/geneseed-code-review.md +2 -1
  39. package/src/skills/parallel-agents.md +1 -1
  40. package/src/skills/react-view-transitions/AGENTS.md +26 -26
  41. package/src/skills/react-view-transitions/SKILL.md +1 -1
  42. package/src/skills/react-view-transitions/VENDOR.md +12 -3
  43. package/src/skills/spring-boot/cloud.md +19 -1
  44. package/src/skills/spring-boot/logging.md +5 -3
  45. package/src/skills/spring-boot/web.md +27 -2
  46. package/src/skills/spring-boot.md +4 -2
  47. package/src/skills/spring-data-jpa.md +18 -4
  48. package/src/skills/spring-testing.md +4 -0
  49. package/src/upstreams.json +4 -4
  50. package/web/dist/assets/{Activity-LKsDzsnK.js → Activity-bUSPM3Dl.js} +1 -1
  51. package/web/dist/assets/{ActivityDetail-DhwTfPm6.js → ActivityDetail-AHRoXeFN.js} +1 -1
  52. package/web/dist/assets/{Bonsai-CePMLrpr.js → Bonsai-B5XY9pid.js} +1 -1
  53. package/web/dist/assets/{CopyButton-CuoaJ6k7.js → CopyButton-C0wwRR9H.js} +1 -1
  54. package/web/dist/assets/{Dashboard-D1VKuvLe.js → Dashboard-DPAA96EI.js} +2 -2
  55. package/web/dist/assets/{Docs-CUrHJKaU.js → Docs-CpGDq165.js} +1 -1
  56. package/web/dist/assets/{Factories-Ci1XfmSy.js → Factories-cNhETa5Q.js} +1 -1
  57. package/web/dist/assets/{GreenhouseView-CNfH2lPK.js → GreenhouseView-DO3ADmT9.js} +1 -1
  58. package/web/dist/assets/{Installs-ZHQZM1iS.js → Installs-D3dDyq10.js} +1 -1
  59. package/web/dist/assets/{JournalView-CMsWahkS.js → JournalView--W-Lw_V9.js} +1 -1
  60. package/web/dist/assets/{Kits-CkliyK0n.js → Kits-ChfehxY6.js} +1 -1
  61. package/web/dist/assets/Laws-CNxYmV36.js +4 -0
  62. package/web/dist/assets/{LibRows-Brv0Hmkr.js → LibRows-CiPvsRYB.js} +1 -1
  63. package/web/dist/assets/{Library-BYmiLjJr.js → Library-BxQvbwVU.js} +1 -1
  64. package/web/dist/assets/{Loops-ytm-xJ68.js → Loops-DAblKkyq.js} +1 -1
  65. package/web/dist/assets/{OperatorHudView-KaqCx_HP.js → OperatorHudView-QtSaSyYm.js} +1 -1
  66. package/web/dist/assets/{Personal-CmcnRKYE.js → Personal-DxSGv638.js} +1 -1
  67. package/web/dist/assets/{Settings-tUrpdOfq.js → Settings-CgTbhvRv.js} +1 -1
  68. package/web/dist/assets/{Tabs-CD7etcGD.js → Tabs-Cf4X1hdz.js} +1 -1
  69. package/web/dist/assets/{index-COKbhFNo.js → index-B_pTwZra.js} +3 -3
  70. package/web/dist/assets/index-CzfImiYb.css +1 -0
  71. package/web/dist/index.html +2 -2
  72. package/web/dist/assets/Laws-hh4O3HZ4.js +0 -4
  73. package/web/dist/assets/index-Ba_Kg3Af.css +0 -1
@@ -0,0 +1,180 @@
1
+ # Steps
2
+
3
+ **Best for:** a short, ordered sequence of stages where the order is the claim and each stage needs a number, a compact visual cue, a title, and one brief explanation. Use it for methods, playbooks, onboarding paths, launch checklists, and “how it works” explainers.
4
+
5
+ Prefer **Timeline** when spacing encodes real elapsed time, **Flowchart** when the route branches, **Swimlane** when ownership and handoffs matter, and **Process** when each stage must expose actors, tools, or input/output payloads. Steps has one rail, no branches, no time scale, and no actor lanes.
6
+
7
+ ---
8
+
9
+ ## 1. Inputs
10
+
11
+ ```yaml
12
+ steps: # 3..7, left to right
13
+ - number: "01"
14
+ title: "Frame"
15
+ description: ["Define the decision", "and its success signal"]
16
+ icon: file # optional; from primitive-icons.md
17
+ - number: "02"
18
+ title: "Research"
19
+ description: ["Gather evidence from", "customers and operators"]
20
+ icon: users
21
+ - number: "03"
22
+ title: "Synthesize"
23
+ description: ["Turn observations into", "one testable direction"]
24
+ icon: search
25
+ focal: true
26
+ - number: "04"
27
+ title: "Decide"
28
+ description: ["Commit the scope and", "name the trade-offs"]
29
+ icon: database
30
+ - number: "05"
31
+ title: "Ship"
32
+ description: ["Release, measure, and", "feed learning forward"]
33
+ icon: container
34
+ dark: false
35
+ ```
36
+
37
+ Rules:
38
+
39
+ - `steps` contains 3–7 entries. Fewer than three is a list; more than seven needs grouping or a second diagram.
40
+ - Exactly one step is `focal: true`. It is the decision, transformation, or risk the figure exists to emphasize.
41
+ - `number` is two digits for fewer than 100 steps (`01`, `02`, …) so the rail scans evenly.
42
+ - `description` is one or two short lines, each no longer than 26 characters at the standard ramp. Rewrite rather than shrink.
43
+ - `icon` is optional and must come from [`primitive-icons.md`](primitive-icons.md). Omit icons from every step if a coherent set is unavailable; never mix line icons, emoji, and brand marks.
44
+
45
+ ---
46
+
47
+ ## 2. Layout grammar
48
+
49
+ The canonical `doc-wide` canvas is `1280×720`. All structural coordinates sit on the 4px grid.
50
+
51
+ ```text
52
+ outer_x = 80
53
+ rail_y = 240
54
+ rail_h = 48
55
+ n = len(steps)
56
+ usable_w = 1280 - 2 * outer_x
57
+ stage_w = min(224, 4 * floor(usable_w / (4 * n)))
58
+ content_w = n * stage_w
59
+ start_x = (1280 - content_w) / 2
60
+ stage_x(i) = start_x + i * stage_w
61
+ stage_cx(i) = stage_x(i) + stage_w / 2
62
+ medallion_cy = rail_y + rail_h / 2
63
+ medallion_r = 36
64
+ number_y = 164
65
+ number_rule_y = 184..220
66
+ title_y = 360
67
+ description_y = 388, 408
68
+ legend_rule_y = 600
69
+ legend_y = 636
70
+ ```
71
+
72
+ This yields a 224px stage for 3–5 steps, 184px for 6, and 160px for 7. Keep `stage_w` on the 4px grid, center the combined rail, and preserve at least 24px between description columns. If copy does not fit the narrower six- or seven-stage columns, widen the canvas or rewrite the copy; do not reduce the type ramp.
73
+
74
+ ### Rail
75
+
76
+ - Draw one contiguous horizontal rail from `stage_x(0)` to `stage_x(n-1) + stage_w`.
77
+ - Each stage owns one `stage_w × 48` segment. Alternate `ink @ 0.05` and `ink @ 0.09` fills to make the segmentation visible without introducing a series palette.
78
+ - The focal segment uses `accent-tint` with a 1px `accent` top and bottom rule.
79
+ - The rail itself expresses order. Do not add arrows between adjacent stages; they duplicate the layout.
80
+
81
+ ### Number and guide
82
+
83
+ - Number: `{eyebrow}` role, 8px, weight 600, letter-spacing `0.14em`, centered at `stage_cx(i)`.
84
+ - Guide: 1px vertical rule from `y=184` to `y=220`, `rule-solid`; focal guide uses `accent`.
85
+ - The number is `muted` by default and `accent` for the focal step.
86
+
87
+ ### Icon medallion
88
+
89
+ - Circle center `(stage_cx(i), 264)`, radius 36.
90
+ - Draw an opaque `paper` circle first so the rail does not show through, then a 1px outline.
91
+ - Default outline and icon use `ink`; focal outline and icon use `accent` and the circle may use `accent-tint`.
92
+ - Place one 24×24 primitive at `(stage_cx(i)-12, 252)`. Icons are decorative (`aria-hidden="true"`); the accessible name comes from the SVG title and description.
93
+
94
+ ### Copy block
95
+
96
+ - Title: `{node-name}` role, 12px, weight 600, centered at `y=360`.
97
+ - Description: `{sublabel}` role, 9px, centered, at most two lines at `y=388` and `y=408`.
98
+ - Titles use `ink`; descriptions use `muted`. The focal title may use `accent`; the description remains `muted`.
99
+
100
+ ---
101
+
102
+ ## 3. Focal and color rules
103
+
104
+ One step is focal. Treat its number, guide, rail segment, medallion outline/icon, and title as one visual unit. All remaining steps stay neutral.
105
+
106
+ Do not assign a different hue to every step. The familiar five-color infographic treatment turns sequence into a legend-reading task and conflicts with the global 1–2 accent rule. If stages genuinely encode categories rather than order, use a chart or another type whose color carries data.
107
+
108
+ ---
109
+
110
+ ## 4. Legend
111
+
112
+ Use a bottom strip only when the focal state needs explanation. The canonical examples show:
113
+
114
+ - neutral outlined medallion — `Stage`
115
+ - accent outlined medallion — `Focal stage`
116
+ - italic note — `Equal spacing shows order, not elapsed time.`
117
+
118
+ If the title or subtitle already names the focal stage and the distinction is obvious, remove the legend.
119
+
120
+ ---
121
+
122
+ ## 5. Reproducibility checklist
123
+
124
+ 1. Step count is 3–7 and exactly one entry is focal.
125
+ 2. Step origins, segment widths, medallion centers, and copy anchors derive from §2.
126
+ 3. The rail is contiguous; there are no gaps, arrowheads, or diagonal connectors.
127
+ 4. Every medallion has an opaque paper mask beneath its outline.
128
+ 5. Every step either has one icon from `primitive-icons.md` or all icons are omitted.
129
+ 6. Titles stay at 12px and descriptions at 9px; long copy is rewritten, not shrunk.
130
+ 7. The focal step is the only accent-bearing stage.
131
+ 8. The SVG uses the accessible SVG contract and the wrapper owns horizontal scrolling.
132
+
133
+ ---
134
+
135
+ ## 6. What `verify-steps.py` requires
136
+
137
+ The checker reads attributes, so every mark binds itself to its stage and draws exactly what it states.
138
+
139
+ - **Bindings.** Each stage has one rail `<rect data-role="rail">`, one medallion `<circle data-role="medallion">` and one number `<text data-role="number">`, all with the same unique `data-step`. Rails also carry `data-index` 1..n in left-to-right order. Exactly one rail and its medallion carry `data-focal="true"`.
140
+ - **Geometry.** Rails share `y`, `width` and `height` and touch end to end. Medallions are centered on their segment with one shared radius; numbers are centered on it at `x` and print the two-digit index. Every mark stays inside the viewBox.
141
+ - **Allowed attributes.** A rail may carry only `x y width height fill fill-opacity`, a medallion only `cx cy r fill stroke stroke-width`, a number only `x y fill font-size font-weight font-family text-anchor`, plus their `data-*` bindings. No `style`, `class`, `id`, `transform`, `dx`/`dy`, `opacity` or anything else. A number contains only its text.
142
+ - **Groups.** Marks sit only inside plain `<g>` groups of the one root `<svg>`, never inside `defs`, a nested `svg` or any other element. A group above a mark may carry only `aria-hidden fill stroke stroke-width stroke-linecap stroke-linejoin font-family font-size font-weight letter-spacing text-anchor`. No attribute may appear twice on any element.
143
+ - **Paint and type.** The first `<rect>` in the SVG is the paper (`#f5f5f5` light, `#2d3142` dark). Rails fill with a non-paper house ink above zero alpha. Medallion outlines and numbers use a house ink at 0.4 alpha or more. Numbers resolve to font-size 8 or more, a font family starting with Geist, Geist Mono or Instrument Serif, and `text-anchor="middle"`. Strokes are at most 4 wide.
144
+ - **Page and CSS.** Style marks with presentation attributes. Stylesheet rules that can reach the SVG may set only `box-sizing`, `margin`, `padding` and custom properties; nothing may move or hide the diagram. CONTRIBUTING.md lists the page rules in full.
145
+
146
+ A minimal three-stage figure that passes, with the second stage focal:
147
+
148
+ ```html
149
+ <svg viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="steps-min-title steps-min-desc">
150
+ <title id="steps-min-title">Plan, build, ship</title>
151
+ <desc id="steps-min-desc">Three equal stages on one rail; build is the focal stage.</desc>
152
+ <rect width="100%" height="100%" fill="#f5f5f5"/>
153
+ <g aria-hidden="true">
154
+ <rect x="304" y="240" width="224" height="48" fill="rgba(45,49,66,0.05)" data-role="rail" data-step="plan" data-index="1"/>
155
+ <rect x="528" y="240" width="224" height="48" fill="rgba(191,69,32,0.08)" data-role="rail" data-step="build" data-index="2" data-focal="true"/>
156
+ <rect x="752" y="240" width="224" height="48" fill="rgba(45,49,66,0.05)" data-role="rail" data-step="ship" data-index="3"/>
157
+ </g>
158
+ <g font-family="'Geist Mono', monospace" font-size="8" font-weight="600" letter-spacing="0.14em" text-anchor="middle">
159
+ <text x="416" y="164" fill="#4f5d75" data-role="number" data-step="plan">01</text>
160
+ <text x="640" y="164" fill="#bf4520" data-role="number" data-step="build">02</text>
161
+ <text x="864" y="164" fill="#4f5d75" data-role="number" data-step="ship">03</text>
162
+ </g>
163
+ <g aria-hidden="true" fill="#f5f5f5" stroke-width="1">
164
+ <circle cx="416" cy="264" r="36" stroke="#2d3142" data-role="medallion" data-step="plan"/>
165
+ <circle cx="640" cy="264" r="36" stroke="none"/>
166
+ <circle cx="640" cy="264" r="36" fill="rgba(191,69,32,0.08)" stroke="#bf4520" data-role="medallion" data-step="build" data-focal="true"/>
167
+ <circle cx="864" cy="264" r="36" stroke="#2d3142" data-role="medallion" data-step="ship"/>
168
+ </g>
169
+ </svg>
170
+ ```
171
+
172
+ ---
173
+
174
+ ## 7. Anti-patterns
175
+
176
+ - Rainbow stage bands with no categorical meaning.
177
+ - Using Steps for dated events, branching decisions, actor handoffs, or feedback loops.
178
+ - Paragraphs under each stage; two short lines is the ceiling.
179
+ - A different icon style per stage, emoji mixed with line icons, or icons that repeat the title without adding recognition.
180
+ - Arrowheads between every adjacent segment. The left-to-right rail already says “next.”
@@ -0,0 +1,63 @@
1
+ # Unit Grid
2
+
3
+ **Best for:** one bounded whole expressed as equal, discrete units: completion, capacity, survey responses, inventory, or a checklist. Use the canonical waffle form when the reader needs to see an exact count out of 100.
4
+
5
+ Not for: category-by-category comparison (use a **bar chart**), a part-of-whole with unequal pieces (use a **treemap**), continuous change (use a **line chart**), or a matrix where row and column positions carry meaning (the future punch-card variant).
6
+
7
+ ## Input contract
8
+
9
+ ```yaml
10
+ title: "Release readiness"
11
+ total: 100
12
+ filled: 64
13
+ unit_label: "release check"
14
+ focal_index: 63
15
+ source_note: "Illustrative checklist"
16
+ ```
17
+
18
+ Validation rules:
19
+
20
+ 1. Version 1 is a 10 by 10 grid with exactly 100 cells.
21
+ 2. `total` is exactly `100`; `filled` is an integer from `0` through `100`.
22
+ 3. Every cell represents one unit. Do not use fractional cells, scaled cells, or merged cells.
23
+ 4. At most one completed cell is focal. Accent is editorial emphasis, never a larger unit.
24
+ 5. Cells fill in reading order, left to right and top to bottom. A different order needs an explicit future variant.
25
+ 6. Rows and columns carry no category meaning in the canonical waffle form.
26
+
27
+ ## Layout conventions
28
+
29
+ - Use a 10 by 10 grid of equal 20px cells with a 4px gutter. The shipped examples begin at `(382, 86)`, making the grid 236px square inside a `1000 × 390` viewBox.
30
+ - Every chart root carries `data-unit-grid="true"`, `data-unit-total="100"`, `data-unit-filled`, `data-unit-rows="10"`, and `data-unit-columns="10"`.
31
+ - Every cell is a `<rect>` with `data-unit-cell="filled"` or `data-unit-cell="empty"` and a unique `data-unit-index` from 0 through 99. `scripts/verify-unit-grid.py` checks count, geometry, indices, the declared filled value, and printed labels.
32
+ - Use one ink fill for completed cells, a quieter paper-relative fill for remaining cells, and no more than one accent completed cell. The count, not color, carries the value. Set each cell's literal fill on the `<rect>` (or a parent `<g>`): completed cells must match the page's `:root` `--ink` or `--accent`, and remaining cells share one other fill well away from both. Cells sit directly in the chart `<svg>` or in plain `<g>`/`<a>` groups with no `style`, `transform` or conditional attributes; cell strokes stay at or under 2px and corner radii at or under a quarter of the cell. The verifier rejects opacity, visibility, display, filter, mask, clip-path, paint-order and mix-blend-mode on cells or their ancestors, paint, stroke or hiding rules in `<style>` (after decoding escapes), `@import`, any linked stylesheet but Google Fonts, SMIL animation, and any element drawn after the first cell whose box touches the grid or cannot be computed from plain numeric attributes. It does not see HTML wrappers around the SVG or scripts.
33
+ - Mark the percentage text with `data-unit-percent="true"` and the count text with `data-unit-count="true"`. They must read `64%` and `64 complete · 36 remaining` for `filled: 64`; both are checked against `data-unit-filled`. Each label is plain visible `<text>` inside the chart SVG (no child elements, no hiding or `style` attributes), painted `--ink` or `--muted`, at least 8px, and inside the viewBox.
34
+ - Do not apply transforms to cells or their SVG/group ancestors, or move geometry through CSS. Bake movement into the coordinates so the verifier checks the rendered positions.
35
+ - Put the exact count in text near the grid and state the unit in the source line. The grid must remain understandable in grayscale.
36
+ - Keep the legend block below the grid. Label the focal cell as editorial emphasis, so it cannot be mistaken for a special unit.
37
+
38
+ ## Honest-data rule
39
+
40
+ A unit grid claims that one mark equals one unit. Never round a 63.4% result to 64 filled cells without saying that the display is rounded. Never use a partial fill, larger focal cell, gradient, or area-sized mark to recover precision. If the denominator is not naturally bounded to 100, choose a number of whole cells that makes the unit honest or choose a different chart.
41
+
42
+ ## Complexity budget
43
+
44
+ - Exactly 100 cells in a 10 by 10 grid.
45
+ - One count and one optional focal completed cell.
46
+ - One legend and one source note.
47
+ - Static output only.
48
+ - No categorical row or column axes in version 1.
49
+
50
+ ## Anti-patterns
51
+
52
+ - Partial, merged, oversized, or differently shaped cells.
53
+ - Rainbow status fills or multiple accent cells.
54
+ - Using the grid for a denominator other than 100 without an explicit future variant.
55
+ - Treating rows and columns as categories. That is the later punch-card variant, not this canonical waffle form.
56
+ - Gradients, heatmap ramps, 3-D treatments, or shadows.
57
+ - Filling in a non-reading order without explaining that order.
58
+
59
+ ## Examples
60
+
61
+ - `assets/example-unit-grid.html` - minimal light.
62
+ - `assets/example-unit-grid-dark.html` - minimal dark with the same dataset and geometry.
63
+ - `assets/example-unit-grid-full.html` - full editorial with unchanged grid geometry.
@@ -21,7 +21,8 @@
21
21
  4. For a large change, consider dispatching the
22
22
  [reviewer {{AGENT}}](../{{DIR_AGENTS}}/reviewer.md) to keep the main context clean.
23
23
  When a spec exists and the diff spans more than a few files, run pass 3 in its own
24
- subagent, handed only the diff command and the spec, alongside passes 1–2: a pass
24
+ subagent — started fresh, never a fork of your own context — handed only the diff
25
+ command and the spec, alongside passes 1–2: a pass
25
26
  that has already filled up on code findings stops reading the spec closely, and
26
27
  kept apart, one axis's findings never mask the other's.
27
28
  5. Pass 1 — correctness: logic errors, edge cases, error handling, race
@@ -11,7 +11,7 @@
11
11
  ## Procedure
12
12
  1. Confirm independence: the subtasks must not depend on each other's output or write the same files ({{DOCTRINE:one-writer-per-file}}). Write down each unit's **write set** — the files or globs it may change — and intersect them; an overlap runs in sequence or goes to one owner, and shared append files (registries, index tables, lockfiles, generated bundles) stay with you. If they're sequential or share state, use [plan](plan.md) instead.
13
13
  2. Split the work into self-contained units, each with one clear goal and a defined output contract — what it must return. Several small edits of one kind (the same fix, constant or field across files) form ONE unit with the union write set and get one review.
14
- 3. Dispatch each unit to its own subagent in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (a unit in the shared tree never commits or pushes; a slice on its own branch (step 6) commits only there, never pushes — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
14
+ 3. Dispatch each unit to its own fresh subagent (never a fork: a fork carries your context and model tier) in one batch — units that call one rationed resource run in sequence instead ({{DOCTRINE:serialize-against-a-rationed-resource}}) — each under a handoff envelope: the unit's goal, the inputs it needs, its **write set** (edit nothing outside it; return rows for a shared file instead of writing it), the observable check that proves it done, its output contract — naming every file it changed — and the inherited constraints (a unit in the shared tree never commits or pushes; a slice on its own branch (step 6) commits only there, never pushes — {{DOCTRINE:consent-before-push}} stays with you; no sub-agents of its own — review comes from you; gaps reported, never invented). Hand each unit only the access its goal needs ({{LAW:least-privilege}}). Prefer the read-only [explorer {{AGENT}}](../{{DIR_AGENTS}}/explorer.md) for investigation so the heavy reading stays out of the main context ({{DOCTRINE:context-economy}}). Where no subagent capability exists, run the units sequentially as personas instead, converging the same way.
15
15
 
16
16
  **Brief checklist** — the envelope also states:
17
17
  - **Git state:** the ref to measure (`HEAD` or `origin/main`, after a fetch) and whether the diff is staged, on disk or committed; after a restart, `git log` before redoing "uncommitted" work — a stale ref redoes every finding.
@@ -44,7 +44,7 @@ Reserve directional slides for hierarchical navigation (list → detail) and ord
44
44
  ## Availability
45
45
 
46
46
  - **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
47
- - **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
47
+ - **Without Next.js:** Use stable `react` and `react-dom` 19.3 or newer (`ViewTransition` and `addTransitionType` became stable in React 19.3). Earlier stable React versions do not include these APIs.
48
48
  - Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
49
49
 
50
50
  ---
@@ -363,7 +363,7 @@ For each shared element (`name` prop), note every navigation where a pair forms
363
363
 
364
364
  ## Step 2: Add CSS Recipes
365
365
 
366
- Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.
366
+ Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](references/css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.
367
367
 
368
368
  Customize timing after the structure works. Keep ordinary crossfades opacity-only; scope blur to a specific shared morph when it is intentional.
369
369
 
@@ -375,7 +375,7 @@ For every persistent element identified in Step 1, add a `viewTransitionName` st
375
375
  <header style={{ viewTransitionName: "site-header" }}>...</header>
376
376
  ```
377
377
 
378
- Then add the [Persistent Element Isolation](css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround) instead.
378
+ Then add the [Persistent Element Isolation](references/css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround) instead.
379
379
 
380
380
  If a Suspense fallback mirrors a persistent control (e.g., a skeleton search input), give both the real control and the skeleton the same `viewTransitionName` so they morph in place.
381
381
 
@@ -410,7 +410,7 @@ Then wrap each **page component** (not layout) in a type-keyed `<ViewTransition>
410
410
  </ViewTransition>
411
411
  ```
412
412
 
413
- The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
413
+ The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](references/css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.
414
414
 
415
415
  Extract this into a reusable component so every page doesn't repeat the verbose type map:
416
416
 
@@ -460,7 +460,7 @@ This example uses `slide-down` / `slide-up` for directional vertical motion. For
460
460
  - Always use `default="none"` on the content `<ViewTransition>` to prevent re-animation on revalidation or unrelated transitions.
461
461
  - Use simple string props (not type maps) on Suspense `<ViewTransition>`s — Suspense resolves fire as separate transitions with no type, so type-keyed props won't match.
462
462
  - A fallback/content `share` pair morphs between snapshots. Use it only when that interpolation is desired and does not distort layout or geometry.
463
- - If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](patterns.md#suspense-reveal-flicker).
463
+ - If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](references/patterns.md#suspense-reveal-flicker).
464
464
 
465
465
  ## Step 6: Add Shared Element Transitions
466
466
 
@@ -478,9 +478,9 @@ For every shared visual element identified in Step 1, add matching named `<ViewT
478
478
  </ViewTransition>
479
479
  ```
480
480
 
481
- The `share="morph"` class uses the [Shared Element Morph](css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
481
+ The `share="morph"` class uses the [Shared Element Morph](references/css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).
482
482
 
483
- When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](../SKILL.md#composing-shared-elements-with-list-identity).
483
+ When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](SKILL.md#composing-shared-elements-with-list-identity).
484
484
 
485
485
  **Rules:**
486
486
  - Names must be globally unique — use prefixes like `photo-${id}`.
@@ -497,9 +497,9 @@ Walk through every row in the navigation map from Step 1 and confirm:
497
497
  - Do persistent elements stay static (not sliding with page content)?
498
498
  - Do Suspense reveals animate independently from directional navigations?
499
499
 
500
- If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](troubleshooting.md).
500
+ If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](references/troubleshooting.md).
501
501
 
502
- For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](nextjs.md).
502
+ For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](references/nextjs.md).
503
503
 
504
504
  ---
505
505
 
@@ -621,10 +621,10 @@ Use `key` when content identity changes (state resets). Omit for cross-fades (ta
621
621
 
622
622
  ## Isolate Elements from Parent Animations
623
623
 
624
- Pull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](css-recipes.md#persistent-element-isolation)).
624
+ Pull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](references/css-recipes.md#persistent-element-isolation)).
625
625
 
626
626
  - **Persistent chrome** (nav, sidebar, player bar): `<nav style={{ viewTransitionName: 'persistent-nav' }}>` + isolation CSS. `<ViewTransition default="none">` works too, but its auto-name can't take `z-index`/backdrop `display:none` — hand-name when you need those.
627
- - **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.
627
+ - **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](references/css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.
628
628
  - **Naming an interactive element has a cost:** named participants are skipped by hit-testing while a transition runs ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)) — clicks and hover fall through to whatever is beneath. Portal named popovers/menus; rendered inline in a clickable row, mid-transition clicks activate the row and read as outside-clicks that close the popover.
629
629
  - **Third-party floating components** (toast libraries, portals you don't render): put the name on an always-mounted wrapper you own — `<div style={{ viewTransitionName: 'toaster' }} className="pointer-events-none fixed inset-0">`. Library containers often unmount when empty, so naming them directly leaves the group unpinned exactly when a toast appears mid-transition. Name a dialog's backdrop separately from its panel so each pins independently.
630
630
 
@@ -641,7 +641,7 @@ Don't put a manual `viewTransitionName` on the root DOM node inside `<ViewTransi
641
641
 
642
642
  ## Sliding Indicator (tabs)
643
643
 
644
- One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](nextjs.md#routing-driven-tabs)).
644
+ One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](references/css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)).
645
645
 
646
646
  ```tsx
647
647
  import { useState, useTransition, ViewTransition } from 'react';
@@ -668,7 +668,7 @@ export function Tabs({ tabs, indicatorName = 'tab-indicator' }) {
668
668
  }
669
669
  ```
670
670
 
671
- Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.
671
+ Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.
672
672
 
673
673
  ## Layout Displacement Morph
674
674
 
@@ -719,7 +719,7 @@ function AnimatedCollapse({ open, children }) {
719
719
  </Activity>
720
720
  ```
721
721
 
722
- Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](nextjs.md#layout-level-viewtransition)).
722
+ Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](references/nextjs.md#layout-level-viewtransition)).
723
723
 
724
724
  ## Exclude Elements with `useOptimistic`
725
725
 
@@ -790,9 +790,9 @@ The `types` array (second argument) lets you vary animation based on transition
790
790
 
791
791
  **Scrolling hangs while a transition animates:** the `::view-transition` overlay is `position: fixed` and its snapshots don't scroll — a browser limitation, not fixable in React (skipping snaps to the end). Keep reveal durations short; for scroll-driven UI use gesture transitions (experimental `useSwipeTransition`, if available).
792
792
 
793
- **Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations).
793
+ **Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations).
794
794
 
795
- **Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.
795
+ **Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.
796
796
 
797
797
  **Shared morph silently not firing:** `share` resolved to `none`. Either the VT has `default="none"` with no explicit `share` prop, or `share` is type-keyed and the navigation never adds the type — the link needs `transitionTypes` (or `addTransitionType` in the transition).
798
798
 
@@ -800,7 +800,7 @@ The `types` array (second argument) lets you vary animation based on transition
800
800
 
801
801
  **An enter animation runs even though Suspense never showed its fallback:** The content-side VT became the topmost entering subtree during navigation. At that call site, add a host DOM element immediately outside `Suspense`. The host suppresses the nested enter during warm navigation but remains mounted so the VT can enter on a later fallback-to-content reveal. Keep the host outside `Suspense`, not inside the reusable crossfade; do nothing when a direct host already exists.
802
802
 
803
- **Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](patterns.md#layout-displacement-morph).
803
+ **Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](references/patterns.md#layout-displacement-morph).
804
804
 
805
805
  **`router.back()` and browser back/forward skip the directional slide:** traversals carry no transition types, so type-keyed maps resolve to `default` — untyped shared-element morphs still apply. Use `router.push()` for typed animations.
806
806
 
@@ -820,7 +820,7 @@ The `types` array (second argument) lets you vary animation based on transition
820
820
 
821
821
  **Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.
822
822
 
823
- **Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround).
823
+ **Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround).
824
824
 
825
825
  **`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.
826
826
 
@@ -1050,7 +1050,7 @@ The `::view-transition` overlay captures all pointer events. React shrinks it to
1050
1050
  }
1051
1051
  ```
1052
1052
 
1053
- Trade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)).
1053
+ Trade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)).
1054
1054
 
1055
1055
  ---
1056
1056
 
@@ -1155,13 +1155,13 @@ Read the current [Next.js View Transitions guide](https://nextjs.org/docs/app/gu
1155
1155
 
1156
1156
  Because every link click is a transition, any VT with `default="auto"` fires on **every** navigation — use `default="none"` to prevent competing animations.
1157
1157
 
1158
- For unexpected or broken animation behavior, see [troubleshooting.md](troubleshooting.md).
1158
+ For unexpected or broken animation behavior, see [troubleshooting.md](references/troubleshooting.md).
1159
1159
 
1160
1160
  ---
1161
1161
 
1162
1162
  ## Next.js Implementation Additions
1163
1163
 
1164
- When following [implementation.md](implementation.md), apply these additions:
1164
+ When following [implementation.md](references/implementation.md), apply these additions:
1165
1165
 
1166
1166
  **Step 4:** Use `transitionTypes` on `<Link>` — see [The `transitionTypes` Prop](#the-transitiontypes-prop-on-nextlink). If the animation depends on dynamic destination content, also see [When Content Must Be Ready](#when-content-must-be-ready).
1167
1167
 
@@ -1171,11 +1171,11 @@ When following [implementation.md](implementation.md), apply these additions:
1171
1171
 
1172
1172
  ## Layout-Level ViewTransition
1173
1173
 
1174
- **Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](../SKILL.md#composing-shared-elements-with-list-identity).
1174
+ **Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](SKILL.md#composing-shared-elements-with-list-identity).
1175
1175
 
1176
1176
  A bare `<ViewTransition>` in layout works only if pages have **no** VTs of their own.
1177
1177
 
1178
- **Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](patterns.md#composing-with-activity)).
1178
+ **Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](references/patterns.md#composing-with-activity)).
1179
1179
 
1180
1180
  ---
1181
1181
 
@@ -1260,15 +1260,15 @@ function SortControl() {
1260
1260
  }
1261
1261
  ```
1262
1262
 
1263
- List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](patterns.md#searchable-grid-with-usedeferredvalue) pattern.
1263
+ List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](references/patterns.md#searchable-grid-with-usedeferredvalue) pattern.
1264
1264
 
1265
- For immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](patterns.md#exclude-elements-with-useoptimistic).
1265
+ For immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](references/patterns.md#exclude-elements-with-useoptimistic).
1266
1266
 
1267
1267
  ---
1268
1268
 
1269
1269
  ## Routing-Driven Tabs
1270
1270
 
1271
- The generalized sliding indicator ([Sliding Indicator](patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.
1271
+ The generalized sliding indicator ([Sliding Indicator](references/patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.
1272
1272
 
1273
1273
  ```tsx
1274
1274
  'use client';
@@ -44,7 +44,7 @@ Reserve directional slides for hierarchical navigation (list → detail) and ord
44
44
  ## Availability
45
45
 
46
46
  - **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
47
- - **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
47
+ - **Without Next.js:** Use stable `react` and `react-dom` 19.3 or newer (`ViewTransition` and `addTransitionType` became stable in React 19.3). Earlier stable React versions do not include these APIs.
48
48
  - Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
49
49
 
50
50
  ---
@@ -10,14 +10,16 @@ listed in the generator's `VENDORED_SKILL_DIRS`.
10
10
  - **Credit:** {{CREDIT:react-view-transitions:skills/react-view-transitions}}
11
11
 
12
12
  The licence is MIT, declared in the upstream repo README's `## License`. Upstream ships no LICENSE
13
- file (neither at the pinned commit nor on `main`; re-checked at 063bee94), so there is no license text to carry here
13
+ file (neither at the pinned commit nor on `main`; re-checked at 1a2c79d4), so there is no license text to carry here
14
14
  and the entry's `licenseFile` is null; the README's declaration is the whole grant.
15
15
 
16
16
  The skill follows the [Agent Skills](https://agentskills.io/) format (`SKILL.md` +
17
17
  `references/`). Its internal links point at the upstream project's own files; do not
18
- "fix" them to Geneseed paths — that is why the folder is gate-exempt. To update,
18
+ "fix" them to Geneseed paths — that is why the folder is gate-exempt. Deviation 4 below only
19
+ repoints links that miss a sibling file of this folder. To update,
19
20
  re-copy the upstream folder (new or removed files included, e.g. `references/troubleshooting.md`), re-apply the deviations below, and bump the entry's `commit`
20
- in `src/upstreams.json`.
21
+ in `src/upstreams.json`. Afterwards every relative link in every `.md` here must resolve to a
22
+ file inside this folder.
21
23
 
22
24
  **Deviation 1:** upstream's frontmatter says `name: vercel-react-view-transitions`;
23
25
  here it is `name: react-view-transitions`. The Agent Skills format requires the name to
@@ -29,6 +31,13 @@ here it is `` `ViewTransition` ``. The Agent Skills spec forbids XML tags in a d
29
31
  `checkBuild`'s description arm reports one for every first-party skill — the tag would be the
30
32
  only one left in any install's catalogue.
31
33
 
34
+ **Deviation 4:** upstream's `AGENTS.md` is compiled from `SKILL.md` and the `references/` files,
35
+ and keeps the references' sibling-relative links, which miss at the folder root. In `AGENTS.md`
36
+ only, `](<name>.md` becomes `](references/<name>.md` for `<name>` in `css-recipes`,
37
+ `implementation`, `nextjs`, `patterns` and `troubleshooting` (any `#anchor` kept), and
38
+ `](../SKILL.md` becomes `](SKILL.md`. Links already written `](references/…` are left alone.
39
+ The other files keep upstream's links byte for byte: they already resolve.
40
+
32
41
  **Deliberately not copied:** upstream's `README.md` (the repo-facing readme: install
33
42
  command and folder tree, nothing an agent reads). `AGENTS.md`, upstream's compiled
34
43
  all-in-one copy, IS kept — `SKILL.md`'s closing section points the agent at it.
@@ -78,7 +78,7 @@ spring:
78
78
  The `CircuitBreaker` filter needs a Spring Cloud CircuitBreaker starter (for example the reactor-Resilience4j one) on the classpath. Gateway is WebFlux; do not put it in the same module as a Spring MVC service.
79
79
 
80
80
  ## Observability
81
- - Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest.
81
+ - Health: `/actuator/health/liveness` and `/actuator/health/readiness` are on by default (`management.endpoint.health.probes.enabled=false` disables them); point the Kubernetes probes at those, and permit `/actuator/health/**` in the security chain. Expose only what you need (`management.endpoints.web.exposure.include`), and protect the rest. `management.endpoint.health.show-components: always` with `show-details: when-authorized` tells an anonymous caller which component is down without leaking hosts or versions.
82
82
  - Metrics: add `micrometer-registry-prometheus` and expose `prometheus`.
83
83
  - Traces over OTLP: add `org.springframework.boot:spring-boot-starter-opentelemetry` and configure `management.opentelemetry.tracing.export.otlp.endpoint` (the old `management.otlp.tracing.*` keys are not the Boot 4 names). Boot samples 10% by default; set `management.tracing.sampling.probability: 1.0` only where the volume allows.
84
84
  - Custom spans: `Observation.createNotStarted("order.process", registry).lowCardinalityKeyValue(...).observe(() -> ...)` (Micrometer Observation, unchanged by Boot 4 as far as the docs show).
@@ -99,5 +99,23 @@ Add a short Kubernetes `preStop` sleep so the endpoint leaves the load balancer
99
99
  - GraalVM native: fast start and low memory, at the cost of build time and reflection hints; adopt it deliberately, not by default.
100
100
  - Use whatever CI the project already has; do not introduce a new one.
101
101
 
102
+ ## Local dependencies
103
+ Give each Docker Compose dependency a healthcheck, and make the services that need it wait with `depends_on: { <dep>: { condition: service_healthy } }`; `docker compose up -d --wait` then also returns only once everything is usable. Write a shell check as `["CMD-SHELL", "<script>"]`, never `["CMD", "bash", "-c", "<script>"]`: Podman splits that array on spaces and reports the service healthy before it starts.
104
+
102
105
  ## Kubernetes manifest essentials
103
106
  Liveness and readiness probes on the actuator paths, a startup probe for slow starts, resource requests and limits, `runAsNonRoot`, config from ConfigMap and Secret. For TLS, let the platform terminate it (Ingress plus cert-manager) or mount the certificate and use an SSL bundle ([spring-boot/security.md](security.md)).
107
+
108
+ No committed manifest names a cluster, host, registry, namespace or secret value: no `namespace:` (it comes from `-n`), the image is a bare name (Skaffold `--default-repo`), Secrets are referenced by name and created out of band.
109
+
110
+ Dependencies deployed in the same namespace get the same three probes, or a redeploy routes traffic to a pod that is not ready:
111
+ - PostgreSQL: `pg_isready -h 127.0.0.1` (over TCP: during the first `initdb` the server listens only on its socket), a fast startup probe; data on a PVC with `strategy: Recreate`, or every redeploy starts empty.
112
+ - Keycloak: `KC_HEALTH_ENABLED=true`, then `/health/started`, `/health/ready`, `/health/live` on management port 9000, not 8080.
113
+
114
+ Prove a new probe can fail: watch the service start and see Warning events before it is up (`kubectl get events --field-selector type=Warning`), with no restarts in the pods that depend on it.
115
+
116
+ ## One set of manifests for several platforms
117
+ When one service deploys to a local cluster, plain Kubernetes and OpenShift, use Kustomize overlays (deployed with Skaffold or `kubectl -k`):
118
+ - `deploy/base` is plain Kubernetes, valid anywhere; `deploy/overlays/<platform>` adds only what that platform needs (Routes on OpenShift, Ingresses elsewhere); environment overlays with hosts and TLS stay out of git.
119
+ - Stay within the kustomize 3.8 features that Skaffold, `kubectl -k` and `oc -k` all support (`resources`, `patches`, generators); no `labels`, `replacements` or `components`.
120
+ - Selectors stay `app: <name>`: a selector cannot change after the first deploy.
121
+ - CI runs `kustomize build` on every overlay, so a broken patch fails the build, not the deploy.
@@ -41,8 +41,9 @@ log.error("Payment failed for order {}", order.id(), e); //
41
41
  ```
42
42
  - Placeholders, never string concatenation. Guard only genuinely expensive arguments with `isDebugEnabled()`.
43
43
  - Pass the exception as the final argument; do not log `e.getMessage()` alone.
44
- - Log an exception once, where it is handled, not at every layer it passes through.
45
- - Never log secrets, tokens, passwords or personal data; log identifiers.
44
+ - Log an exception once, where the flow ends (the exception handler, listener or job), not at every layer it passes through: a lower layer wraps it with context and rethrows, without logging. Expected business errors (404, validation) are `WARN` or `DEBUG` without a stack trace; only unexpected failures are `ERROR` with the throwable.
45
+ - For fields a log platform should filter on, use the SLF4J 2 fluent API: `log.atError().addKeyValue("orderId", id).setCause(e).log("Order processing failed")`. Boot's structured formats write each pair as a JSON field.
46
+ - Never log secrets, tokens, passwords, `Authorization` or `Cookie` headers, card data or personal data; log identifiers. A record prints every component in `toString()`: log its id, not the record, when it carries personal data. No full request or response bodies in production.
46
47
  - Lombok's `@Slf4j` is fine where the project uses Lombok; otherwise declare the logger as above.
47
48
 
48
49
  | Level | Meaning |
@@ -76,7 +77,7 @@ class MdcFilter extends OncePerRequestFilter {
76
77
  }
77
78
  ```
78
79
 
79
- MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run.
80
+ MDC is thread-local, so it does not follow work handed to another thread (virtual or platform). For executor tasks, copy the context with a `TaskDecorator` (`MDC.getCopyOfContextMap()` before, `MDC.setContextMap(...)` inside the task, `MDC.clear()` in `finally`) and register it on the executor you use; check that Boot applies it to your executor in the version you run. `CompletableFuture.supplyAsync(...)` without an executor runs on the common pool and loses MDC: always pass the Spring executor.
80
81
 
81
82
  Useful fields for incident analysis: `requestId`, user or tenant id, and a duration on slow-path logs. Keep them to identifiers, not payloads.
82
83
 
@@ -86,4 +87,5 @@ Useful fields for incident analysis: `requestId`, user or tenant id, and a durat
86
87
  | JSON console | `logging.structured.format.console: logstash` |
87
88
  | Per-package level | `logging.level.com.example.orders: DEBUG` |
88
89
  | Correlate a request | MDC `requestId` set in a filter |
90
+ | One event's fields as JSON | `log.atInfo().addKeyValue("k", v).log("msg")` |
89
91
  | Follow one request in JSON logs | `jq 'select(.requestId == "abc")' app.log` (field name depends on MDC key and format) |