diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a29307e..50bfd4e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -103,7 +103,7 @@ jobs:
           node scripts/render-cv-reference.mjs revision-002
 
   skill-fixtures:
-    name: skill-fixtures (GraphCompose 1.6.7 via Maven Central)
+    name: skill-fixtures (GraphCompose 1.7.0 via Maven Central)
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
diff --git a/AGENTS.md b/AGENTS.md
index fe550aa..a381839 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,7 +10,7 @@ GraphCompose AI Template Flow turns a visual document reference (a
 PNG screenshot of a CV, invoice, proposal, cover letter, report,
 brochure, datasheet — ANY single-page or multi-page document
 GraphCompose primitives can express) into a maintainable Java
-template that targets GraphCompose 1.6.7 — with a strict visual
+template that targets GraphCompose 1.7.0 — with a strict visual
 parity contract, a typed data spec the user can edit without
 touching Java, a per-revision asset bundle (Iconify icons + Google
 Fonts), a clean and a debug render, and a publish-quality bundle
@@ -23,7 +23,7 @@ change creates a new revision; nothing is overwritten.
 
 **Document-kind contract.** The four canonical upstream surfaces
 are `cv`, `coverletter`, `invoice`, `proposal`, with three distinct
-generations as of GraphCompose 1.6.7:
+generations as of GraphCompose 1.7.0:
 
 - `cv` — V2 layered (data → theme → components → widgets → preset
   orchestrator).
@@ -204,7 +204,8 @@ docs/                                 long-form reference
 
 skills/                               versioned skill packs
   skill-manifest.json
-  versions/graphcompose-1.6/*.md      one skill per topic, tied to GraphCompose 1.6.x (verified against 1.6.7)
+  versions/graphcompose-1.7/*.md      active skill pack, tied to GraphCompose 1.7.x (verified against 1.7.0)
+  versions/graphcompose-1.6/*.md      frozen 1.6.x snapshot (retained for projects pinned back to 1.6.x)
 
 tools/
   asset-resolver/                     Iconify + Google Fonts CLI (Node)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3c2775e..b1697e0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,39 @@ the full visual-baseline pass is the gate to `1.0.0`.
 
 ## Unreleased
 
+### GraphCompose 1.7.0
+- **Dependency bumped 1.6.7 → 1.7.0.** All render-runner, skill-fixture,
+  and preview-renderer poms now resolve
+  `io.github.demchaav:graph-compose:1.7.0` from Maven Central; every live
+  example `template-project.json` (`targetGraphComposeVersion`) and the
+  `graphcompose-flow init` scaffold default move with them. 1.7.0 is
+  additive over 1.6.x (zero breaking changes), so existing generated
+  templates compile and render unchanged.
+- **New `skills/versions/graphcompose-1.7/` pack.** A port of the 1.6
+  pack (the frozen `graphcompose-1.6/` snapshot is retained for projects
+  pinned back) with the v1.7.0 additive primitives folded into the topic
+  skills: inline shape runs (rating dots / bullets / arrows / checkboxes
+  drawn from geometry, no font glyph), polygon `ShapeOutline` geometry,
+  composite inline figures + swappable tick/arrow styles, per-corner
+  `roundedRect(...)`, vertical text alignment
+  (`verticalAlign(TextVerticalAlign)`), semantic timelines
+  (`addTimeline(...)`), dashed/dotted lines (`LineBuilder.dashed(...)`),
+  `headingBar(...)`, `softPanel(..., stroke)`, `FontName.JETBRAINS_MONO`,
+  `DocumentSession.availableHeight()`, and the nested-stack
+  `position(...)` offset fix. The `spacing-and-alignment` "no per-line
+  vertical centring" note was corrected for the new `verticalAlign`.
+- **Manifest repointed to 1.7.x.** `skill-manifest.json` →
+  `skillsVersion 0.3.0`, `defaultGraphComposeVersion 1.7.x`,
+  `supportedGraphComposeVersions [1.6.x, 1.7.x]`, all 14 entries
+  `verifiedAgainst 1.7.0` (`status: needs-validation` until the render +
+  visual-diff loop runs on 1.7.0).
+- **Prompts + docs refreshed.** The Architecture Mapper gains mapping
+  rows for the 1.7.0 primitives; the Template Coder lists them as Stable,
+  surface-agnostic idioms; `AGENTS.md`, the quickstart / overview /
+  roadmap / limitations / implementation-status / skill-validation /
+  integration docs, README, and CONTRIBUTING move their "current target"
+  to 1.7.0 (the pre-1.6.7 JitPack boundary is left intact as history).
+
 ### Live preview
 - **`live/` mirror.** Every render now also writes a single stable copy of the
   latest output to `live/current.pdf` (plus `current-debug.pdf`, `current.png`,
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 230af9e..5dce660 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,9 +12,9 @@ honest about its limitations.
 Phases 1 through 7 of the project plan are shipped. See
 [docs/roadmap.md](docs/roadmap.md) for the per-phase table and
 [docs/implementation-status.md](docs/implementation-status.md) for the
-honest claim-vs-reality matrix. GraphCompose 1.6.7 is reachable for
+honest claim-vs-reality matrix. GraphCompose 1.7.0 is reachable for
 fixture validation through Maven Central as
-`io.github.demchaav:graph-compose:1.6.7` (older pins ≤ 1.6.5 still
+`io.github.demchaav:graph-compose:1.7.0` (older pins ≤ 1.6.5 still
 resolve via JitPack as `com.github.DemchaAV:GraphCompose:vX.Y.Z`), and
 the five committed skill fixtures compile and run against it. The
 preview renderer now executes compiled templates and writes
diff --git a/README.md b/README.md
index a1f07aa..504448a 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ setup.
 **Works for any document kind** GraphCompose primitives can express — CV,
 cover letter, invoice, proposal, report, brochure, datasheet, single-page
 brand collateral. The four canonical template surfaces upstream are
-first-class targets as of GraphCompose 1.6.7:
+first-class targets as of GraphCompose 1.7.0:
 
 | Surface | Generation | Shape |
 |---|---|---|
@@ -63,7 +63,7 @@ Source reference: [`examples/cv-reference/`](examples/cv-reference/) → publish
 | Published template bundle (`mint-editorial-cv`) | Available |
 | GitHub Actions CI matrix | Green (Node 20 + Java 21 + Maven) |
 | Full visual baseline orchestration | In progress |
-| Skills under `skills/versions/graphcompose-1.6/` | `needs-validation` until baseline pass lands |
+| Skills under `skills/versions/graphcompose-1.7/` | `needs-validation` until baseline pass lands |
 
 Full claim-vs-reality matrix: [`docs/implementation-status.md`](docs/implementation-status.md).
 
@@ -266,8 +266,8 @@ and a Node
 visual-diff CLI ([`visual-diff`](tools/visual-diff/)). All three ship
 with passing test suites and are wired to GitHub Actions CI.
 
-GraphCompose 1.6.7 is reachable for fixture validation through
-Maven Central as `io.github.demchaav:graph-compose:1.6.7`
+GraphCompose 1.7.0 is reachable for fixture validation through
+Maven Central as `io.github.demchaav:graph-compose:1.7.0`
 (JitPack `com.github.DemchaAV:GraphCompose:vX.Y.Z` still resolves for
 pre-1.6.7 pins). The five fixture projects under
 [`examples/skill-fixtures/`](examples/skill-fixtures/) compile and
diff --git a/docs/implementation-status.md b/docs/implementation-status.md
index efacd20..de55064 100644
--- a/docs/implementation-status.md
+++ b/docs/implementation-status.md
@@ -12,14 +12,14 @@ The repository is no longer only documentation. The workflow
 scaffold, revision tooling, preview tooling, visual diff tooling,
 repository-contract checks, and five GraphCompose skill fixtures all
 exist on disk. The Java fixture projects compile and run against
-GraphCompose 1.6.7 through Maven Central using:
+GraphCompose 1.7.0 through Maven Central using:
 
 ```text
-io.github.demchaav:graph-compose:1.6.7
+io.github.demchaav:graph-compose:1.7.0
 ```
 
 Older pins (≤ v1.6.5) continue to resolve via JitPack as
-`com.github.DemchaAV:GraphCompose:vX.Y.Z`. GraphCompose 1.6.7 is
+`com.github.DemchaAV:GraphCompose:vX.Y.Z`. GraphCompose 1.7.0 is
 compiled for Java 21, so GraphCompose-backed Maven jobs run on Java
 21 in CI. The invoice and CV reference examples
 both render through local render-runner projects.
@@ -39,7 +39,7 @@ visual review loop completes against committed baselines.
 |---|---|---|
 | Documentation MVP | README, docs, AGENTS, prompts, contributing guide, limitations, roadmap | REAL |
 | Agent prompt pack | 10 prompt files under `prompts/` | REAL |
-| Versioned skill pack | 14 files under `skills/versions/graphcompose-1.6/` with manifest/frontmatter checks | REAL, still `needs-validation` |
+| Versioned skill pack | 14 files under `skills/versions/graphcompose-1.7/` with manifest/frontmatter checks | REAL, still `needs-validation` |
 | Manual invoice example | Three revisions under `examples/invoice-reference/`, render-runner, committed `output.pdf`/`output.png` | REAL-WITH-CAVEAT: visual baseline absent |
 | Manual CV example | Two two-page drafts under `examples/cv-reference/`, render-runner, committed `output.pdf`, `output.png`, and `output-page-2.png` for the current draft | REAL-WITH-CAVEAT: visual baseline absent |
 | Revision statuses | `DRAFT`, `APPROVED`, `REJECTED`, `SUPERSEDED`, `FAILED`, `REVERTED` in `tools/revision-manager/src/types.ts` | REAL |
diff --git a/docs/integration-with-graphcompose.md b/docs/integration-with-graphcompose.md
index 0afe338..dd35650 100644
--- a/docs/integration-with-graphcompose.md
+++ b/docs/integration-with-graphcompose.md
@@ -9,11 +9,12 @@ workflow that uses GraphCompose as the target language.
 GraphCompose itself is maintained at
 [https://github.com/DemchaAV/GraphCompose](https://github.com/DemchaAV/GraphCompose).
 The skill packs in this repository currently target GraphCompose
-`1.6.x` (the `defaultGraphComposeVersion` in `skills/skill-manifest.json`).
-A `1.5.x` skill pack is also planned per the structure in
-[versioned-skills.md](versioned-skills.md). When GraphCompose ships a
-new minor version, a new skill pack directory is added under
-`skills/versions/` rather than mutating the existing one.
+`1.7.x` (the `defaultGraphComposeVersion` in `skills/skill-manifest.json`),
+with the frozen `1.6.x` pack retained under `skills/versions/` for
+projects that pin back. When GraphCompose ships a new minor version, a
+new skill pack directory is added under `skills/versions/` rather than
+mutating the existing one — the `1.6.x` → `1.7.x` port followed exactly
+this rule (see [versioned-skills.md](versioned-skills.md)).
 
 ## How this strengthens GraphCompose positioning
 
diff --git a/docs/limitations.md b/docs/limitations.md
index 2f77157..612ca2b 100644
--- a/docs/limitations.md
+++ b/docs/limitations.md
@@ -45,8 +45,8 @@ Three tools ship under [`../tools/`](../tools/) and pass CI:
   21 unit tests; functional.
 - The five fixture projects under
   [`../examples/skill-fixtures/`](../examples/skill-fixtures/) compile
-  and run with Maven against GraphCompose 1.6.7 from Maven Central:
-  `io.github.demchaav:graph-compose:1.6.7`. Pre-1.6.7 pins still
+  and run with Maven against GraphCompose 1.7.0 from Maven Central:
+  `io.github.demchaav:graph-compose:1.7.0`. Pre-1.6.7 pins still
   resolve via JitPack as `com.github.DemchaAV:GraphCompose:vX.Y.Z`.
 
 What is intentionally NOT in this repository today:
diff --git a/docs/overview.md b/docs/overview.md
index 7f5c4ac..54f70bc 100644
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -110,8 +110,8 @@ and a `render` path for compiled GraphCompose templates), and a Node
 visual-diff CLI. All three have passing test suites and are wired to
 GitHub Actions CI.
 
-GraphCompose 1.6.7 is reachable through Maven Central as
-`io.github.demchaav:graph-compose:1.6.7` (JitPack
+GraphCompose 1.7.0 is reachable through Maven Central as
+`io.github.demchaav:graph-compose:1.7.0` (JitPack
 `com.github.DemchaAV:GraphCompose:vX.Y.Z` still resolves for
 pre-1.6.7 pins), and the five fixture projects under
 [`examples/skill-fixtures/`](../examples/skill-fixtures/) compile
diff --git a/docs/quickstart.md b/docs/quickstart.md
index a7994c1..227a4b8 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -39,10 +39,10 @@ npm --version
 git --version
 ```
 
-GraphCompose 1.6.7 is resolved by Maven through Maven Central as:
+GraphCompose 1.7.0 is resolved by Maven through Maven Central as:
 
 ```text
-io.github.demchaav:graph-compose:1.6.7
+io.github.demchaav:graph-compose:1.7.0
 ```
 
 Older pins (≤ v1.6.5) continue to resolve through JitPack as
@@ -255,7 +255,7 @@ That runner shows how to:
 
 - copy the selected revision's `generated-template.java` into Maven
   generated sources
-- compile it against GraphCompose 1.6.7
+- compile it against GraphCompose 1.7.0
 - provide sample business data through a spec provider
 - call `tools/preview-renderer` to write `output.pdf` and `output.png`
 
diff --git a/docs/revision-model.md b/docs/revision-model.md
index b82853d..df87ec0 100644
--- a/docs/revision-model.md
+++ b/docs/revision-model.md
@@ -20,7 +20,7 @@ Example:
   "projectName": "invoice-reference",
   "referenceImage": "reference/reference.png",
   "targetGraphComposeVersion": "1.6.0",
-  "skillPack": "skills/versions/graphcompose-1.6",
+  "skillPack": "skills/versions/graphcompose-1.7",
   "currentApprovedRevisionId": "revision-001",
   "currentDraftRevisionId": "revision-002",
   "createdAt": "2026-05-12T16:00:00Z",
@@ -50,7 +50,7 @@ Example:
   "status": "DRAFT",
   "userRequest": "Make the table darker and move the footer down",
   "targetGraphComposeVersion": "1.6.0",
-  "skillPack": "skills/versions/graphcompose-1.6",
+  "skillPack": "skills/versions/graphcompose-1.7",
   "changedComponents": [
     "LineItemsTable",
     "Footer"
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 3cb1649..0a0831c 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -5,9 +5,9 @@ and one manual example. Tooling starts at Phase 5.
 
 ## Current phase
 
-All seven phases of the project plan are shipped. GraphCompose 1.6.7
+All seven phases of the project plan are shipped. GraphCompose 1.7.0
 is reachable for fixture validation through Maven Central as
-`io.github.demchaav:graph-compose:1.6.7` (JitPack
+`io.github.demchaav:graph-compose:1.7.0` (JitPack
 `com.github.DemchaAV:GraphCompose:vX.Y.Z` remains the fallback for
 pre-1.6.7 pins), and the five skill fixtures compile and run against
 it. `preview-renderer render` can
diff --git a/docs/skill-validation.md b/docs/skill-validation.md
index 8b8df97..721e899 100644
--- a/docs/skill-validation.md
+++ b/docs/skill-validation.md
@@ -5,8 +5,8 @@ documents the validation discipline. Phase 4 has shipped the
 [`validation/`](../validation/) folder (templates, checklists, the
 baseline report) and the
 [`examples/skill-fixtures/`](../examples/skill-fixtures/) projects.
-The fixture projects now compile and run against GraphCompose 1.6.7
-from Maven Central (`io.github.demchaav:graph-compose:1.6.7`; older
+The fixture projects now compile and run against GraphCompose 1.7.0
+from Maven Central (`io.github.demchaav:graph-compose:1.7.0`; older
 pre-1.6.7 pins remain resolvable via JitPack as
 `com.github.DemchaAV:GraphCompose:vX.Y.Z`). The remaining validation
 work is the full render + preview + visual-diff loop that promotes
@@ -153,7 +153,7 @@ Phase 4 has shipped:
   the historical baseline report from before fixture execution.
 - [`validation/reports/fixture-smoke-2026-05-18.md`](../validation/reports/fixture-smoke-2026-05-18.md) —
   the first compile/run smoke report against GraphCompose 1.6.0 via
-  JitPack (historical; the fixtures now resolve 1.6.7 from Maven Central).
+  JitPack (historical; the fixtures now resolve 1.7.0 from Maven Central).
 - Five fixture projects under
   [`examples/skill-fixtures/`](../examples/skill-fixtures/):
   `row-basic`, `section-basic`, `table-basic`, `layer-stack-badge`,
@@ -162,7 +162,7 @@ Phase 4 has shipped:
   are not part of the Phase 4 scope.
 
 The fixture smoke proves the covered DSL calls compile and run against
-the real 1.6.7 artifact. As of 2026-06-03 the render + visual-diff loop
+the real 1.7.0 artifact. As of 2026-06-03 the render + visual-diff loop
 is built too: `scripts/validate-skills.mjs` renders each fixture
 through `tools/preview-renderer` (a no-arg `*FixtureDocument` adapter
 per fixture) and compares the PNG against a committed
diff --git a/docs/versioned-skills.md b/docs/versioned-skills.md
index c23ebd5..0109cc7 100644
--- a/docs/versioned-skills.md
+++ b/docs/versioned-skills.md
@@ -56,6 +56,11 @@ skills/
       visual-regression.md
       revision-discipline.md
       troubleshooting.md
+
+    graphcompose-1.7/
+      (same 14 files — the active pack, ported to 1.7.x and verified
+       against 1.7.0; graphcompose-1.6/ is retained as the frozen
+       1.6.x snapshot)
 ```
 
 Skills are physically duplicated per supported GraphCompose version
diff --git a/examples/cover-letter-reference/README.md b/examples/cover-letter-reference/README.md
index 2f799e6..1e6e14c 100644
--- a/examples/cover-letter-reference/README.md
+++ b/examples/cover-letter-reference/README.md
@@ -15,8 +15,8 @@ kick-off gesture that opens `revision-001`.
 ## Surface
 
 V2 layered (`com.demcha.compose.document.templates.coverletter.v2.*`)
-on GraphCompose 1.6.7 — the only surface upstream for cover letters
-as of the 1.6.7 release. See the upstream
+on GraphCompose 1.7.0 — the only surface upstream for cover letters
+as of the 1.7.0 release. See the upstream
 [v2-layered authoring cheatsheet](https://github.com/DemchaAV/GraphCompose/blob/main/docs/templates/v2-layered/authoring-presets.md)
 for the canonical reference.
 
diff --git a/examples/cover-letter-reference/template-project.json b/examples/cover-letter-reference/template-project.json
index bad01ee..76c2252 100644
--- a/examples/cover-letter-reference/template-project.json
+++ b/examples/cover-letter-reference/template-project.json
@@ -4,8 +4,8 @@
   "tagline": "Scaffold project for the first cover-letter run through the GraphCompose AI Template Flow. Pairs with a CV preset via shared CvIdentity + CvTheme on the V2 layered surface (coverletter.v2).",
   "referenceImage": "reference/reference.png",
   "referenceDescription": "reference/PLACEHOLDER.md",
-  "targetGraphComposeVersion": "1.6.7",
-  "skillPack": "skills/versions/graphcompose-1.6",
+  "targetGraphComposeVersion": "1.7.0",
+  "skillPack": "skills/versions/graphcompose-1.7",
   "currentApprovedRevisionId": null,
   "currentDraftRevisionId": null,
   "createdAt": "2026-06-01T12:30:00.000Z",
diff --git a/examples/cv-reference/render-runner/pom.xml b/examples/cv-reference/render-runner/pom.xml
index 91b3cc8..279ea3c 100644
--- a/examples/cv-reference/render-runner/pom.xml
+++ b/examples/cv-reference/render-runner/pom.xml
@@ -12,7 +12,7 @@
     <maven.compiler.source>21</maven.compiler.source>
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
     <revision.id>revision-002</revision.id>
     <revision.generated.sources>${project.build.directory}/generated-sources/revision</revision.generated.sources>
   </properties>
diff --git a/examples/cv-reference/template-project.json b/examples/cv-reference/template-project.json
index 6259c3e..7301594 100644
--- a/examples/cv-reference/template-project.json
+++ b/examples/cv-reference/template-project.json
@@ -4,8 +4,8 @@
   "tagline": "Two-page editorial-style resume for a graphic designer, with a mint accent rule and Iconify-backed contact and social glyphs.",
   "referenceImage": "reference/reference.png",
   "referenceDescription": "reference/reference.md",
-  "targetGraphComposeVersion": "1.6.7",
-  "skillPack": "skills/versions/graphcompose-1.6",
+  "targetGraphComposeVersion": "1.7.0",
+  "skillPack": "skills/versions/graphcompose-1.7",
   "currentApprovedRevisionId": "revision-009",
   "currentDraftRevisionId": "revision-008",
   "previouslyApprovedRevisionId": "revision-008",
diff --git a/examples/invoice-reference/render-runner/pom.xml b/examples/invoice-reference/render-runner/pom.xml
index 7a51f93..abb6e75 100644
--- a/examples/invoice-reference/render-runner/pom.xml
+++ b/examples/invoice-reference/render-runner/pom.xml
@@ -12,7 +12,7 @@
     <maven.compiler.source>21</maven.compiler.source>
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
     <revision.id>revision-003</revision.id>
     <revision.generated.sources>${project.build.directory}/generated-sources/revision</revision.generated.sources>
   </properties>
diff --git a/examples/invoice-reference/template-project.json b/examples/invoice-reference/template-project.json
index f42c7f1..cb8e8c9 100644
--- a/examples/invoice-reference/template-project.json
+++ b/examples/invoice-reference/template-project.json
@@ -2,8 +2,8 @@
   "projectName": "invoice-reference",
   "referenceImage": "reference/reference.png",
   "referenceDescription": "reference/reference.md",
-  "targetGraphComposeVersion": "1.6.7",
-  "skillPack": "skills/versions/graphcompose-1.6",
+  "targetGraphComposeVersion": "1.7.0",
+  "skillPack": "skills/versions/graphcompose-1.7",
   "currentApprovedRevisionId": "revision-003",
   "currentDraftRevisionId": null,
   "createdAt": "2026-05-18T12:00:00Z",
diff --git a/examples/noir-corporate-cv/render-runner/pom.xml b/examples/noir-corporate-cv/render-runner/pom.xml
index 2eef347..3f98cce 100644
--- a/examples/noir-corporate-cv/render-runner/pom.xml
+++ b/examples/noir-corporate-cv/render-runner/pom.xml
@@ -12,7 +12,7 @@
     <maven.compiler.source>21</maven.compiler.source>
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
     <revision.id>revision-001</revision.id>
     <revision.generated.sources>${project.build.directory}/generated-sources/revision</revision.generated.sources>
   </properties>
diff --git a/examples/noir-corporate-cv/template-project.json b/examples/noir-corporate-cv/template-project.json
index 4f77e14..949aa01 100644
--- a/examples/noir-corporate-cv/template-project.json
+++ b/examples/noir-corporate-cv/template-project.json
@@ -4,8 +4,8 @@
   "tagline": "Single-page corporate-style resume / CV with a dark aubergine sidebar plate, circular CV avatar badge, dark section header bars, rating-dot skills and languages blocks, and Iconify-backed contact and interest glyphs.",
   "referenceImage": "reference/reference.png",
   "referenceDescription": "reference/reference.md",
-  "targetGraphComposeVersion": "1.6.7",
-  "skillPack": "skills/versions/graphcompose-1.6",
+  "targetGraphComposeVersion": "1.7.0",
+  "skillPack": "skills/versions/graphcompose-1.7",
   "currentApprovedRevisionId": null,
   "currentDraftRevisionId": "revision-007",
   "previouslyApprovedRevisionId": null,
diff --git a/examples/proposal-reference/README.md b/examples/proposal-reference/README.md
index 8721012..3eb3216 100644
--- a/examples/proposal-reference/README.md
+++ b/examples/proposal-reference/README.md
@@ -15,7 +15,7 @@ kick-off gesture that opens `revision-001`.
 ## Surface
 
 `com.demcha.compose.document.templates.proposal.*` on GraphCompose
-1.6.7 — single-preset V2 architecture upstream (`ModernProposal` +
+1.7.0 — single-preset V2 architecture upstream (`ModernProposal` +
 `ProposalSpec`). New presets live in the same package and share
 `ProposalSpec` as the typed input.
 
diff --git a/examples/proposal-reference/reference/PLACEHOLDER.md b/examples/proposal-reference/reference/PLACEHOLDER.md
index d0efafa..769a2cd 100644
--- a/examples/proposal-reference/reference/PLACEHOLDER.md
+++ b/examples/proposal-reference/reference/PLACEHOLDER.md
@@ -20,7 +20,7 @@ The orchestrator routes that gesture through the 11-agent chain.
 
 ## Surface
 
-GraphCompose 1.6.7 ships a single proposal preset upstream:
+GraphCompose 1.7.0 ships a single proposal preset upstream:
 
 - Package: `com.demcha.compose.document.templates.proposal`
 - Preset: `ModernProposal`
diff --git a/examples/proposal-reference/template-project.json b/examples/proposal-reference/template-project.json
index f764045..15c0afa 100644
--- a/examples/proposal-reference/template-project.json
+++ b/examples/proposal-reference/template-project.json
@@ -4,8 +4,8 @@
   "tagline": "Scaffold project for the first proposal run through the GraphCompose AI Template Flow. Targets the V2 proposal surface (single-preset upstream: ModernProposal).",
   "referenceImage": "reference/reference.png",
   "referenceDescription": "reference/PLACEHOLDER.md",
-  "targetGraphComposeVersion": "1.6.7",
-  "skillPack": "skills/versions/graphcompose-1.6",
+  "targetGraphComposeVersion": "1.7.0",
+  "skillPack": "skills/versions/graphcompose-1.7",
   "currentApprovedRevisionId": null,
   "currentDraftRevisionId": null,
   "createdAt": "2026-06-01T12:45:00.000Z",
diff --git a/examples/skill-fixtures/README.md b/examples/skill-fixtures/README.md
index 8a2ce6a..d7e03c1 100644
--- a/examples/skill-fixtures/README.md
+++ b/examples/skill-fixtures/README.md
@@ -4,7 +4,7 @@ This folder is the home of the Phase 4 skill validation fixtures.
 
 A *skill fixture* is a small, self-contained Maven project that exercises
 one GraphCompose primitive documented by the
-[`skills/versions/graphcompose-1.6/`](../../skills/versions/graphcompose-1.6/)
+[`skills/versions/graphcompose-1.7/`](../../skills/versions/graphcompose-1.7/)
 skill pack. Each fixture proves, at the smallest possible scope, that the
 primitive the skill documents is real GraphCompose API surface and not
 fantasy documentation. The fixtures are the on-disk receipts for the
diff --git a/examples/skill-fixtures/layer-stack-badge/README.md b/examples/skill-fixtures/layer-stack-badge/README.md
index edd433b..725fe15 100644
--- a/examples/skill-fixtures/layer-stack-badge/README.md
+++ b/examples/skill-fixtures/layer-stack-badge/README.md
@@ -40,22 +40,42 @@ overlap), so the layer stack is the correct primitive.
 ## How to run
 
 1. `cd examples/skill-fixtures/layer-stack-badge`
-2. `mvn test`
+2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not
+   throw
 3. inspect `expected-output/layout-snapshot.json` for the intended
    layer order, region shapes, and anchor
 
-Phase 6 will additionally write `expected-output/output.pdf` and
-`expected-output/output.png` on every run.
+The committed render baseline is captured separately from the JUnit
+test. A no-arg
+[`LayerStackBadgeFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/layerstackbadge/LayerStackBadgeFixtureDocument.java)
+exposes the same `compose(DocumentSession)` the test exercises, and
+`tools/preview-renderer` drives it to `expected-output/output.pdf` and
+`output.png`. Run the loop from the repo root:
 
-## Deferred checks
+- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG
+  against the committed baseline (expects `IDENTICAL`).
+- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the
+  `expected-output/output.{pdf,png}` baseline.
 
-The JUnit test currently asserts only that `compose(...)` does not
-throw. Three checks are pending the Phase 6 renderer and the Phase 7
-visual-diff tool:
+## Checks
 
-- layout-snapshot equality against
-  `expected-output/layout-snapshot.json`
-- PDF byte sanity (non-empty, valid header) on
-  `expected-output/output.pdf`
-- preview-image visual diff against a committed
-  `expected-output/output.png` baseline
+The JUnit test still asserts only that `compose(...)` does not throw. The
+render and visual-diff now run through the `LayerStackBadgeFixtureDocument`
+adapter and `node scripts/validate-skills.mjs`, not the test:
+
+- preview-image visual diff against the committed
+  `expected-output/output.png` — wired. `node scripts/validate-skills.mjs`
+  re-renders via `tools/preview-renderer` and compares the PNG with
+  `tools/visual-diff`, expecting `IDENTICAL` (AE == 0).
+- rendered-output sanity — wired. The runner asserts the render produced a
+  non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since
+  PNG rasterisation is platform-specific). Full PDF byte equality is
+  intentionally skipped: PDFs carry timestamps, so parity is judged on the
+  PNG.
+- layout-snapshot equality against `expected-output/layout-snapshot.json`
+  — still not enforced. `layout-snapshot.json` stays illustrative; it
+  documents intent, not a measured engine run.
+
+The captured baseline sizes and the `IDENTICAL` result for all five
+fixtures are recorded in
+[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md).
diff --git a/examples/skill-fixtures/layer-stack-badge/expected-output/README.md b/examples/skill-fixtures/layer-stack-badge/expected-output/README.md
index 83fe3c9..51f16db 100644
--- a/examples/skill-fixtures/layer-stack-badge/expected-output/README.md
+++ b/examples/skill-fixtures/layer-stack-badge/expected-output/README.md
@@ -1,30 +1,37 @@
 # expected-output for layer-stack-badge
 
-This folder is where the Phase 6 render-and-preview tool will write the
-rendered artifacts for this fixture. Until that lands, only
-`layout-snapshot.json` is present, and it is illustrative — the values
-describe the layout shape the fixture intends to produce, not values
-measured by a real engine run.
+This folder holds the committed render baseline for this fixture.
+`output.pdf` and `output.png` are produced by `tools/preview-renderer`
+driving the fixture's no-arg `LayerStackBadgeFixtureDocument` adapter.
+`layout-snapshot.json` is still illustrative — its values describe the
+layout shape the fixture intends to produce, not values measured by a
+real engine run.
 
 ## Files
 
 | File | Status | Populated by |
 |---|---|---|
-| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 |
-| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool |
-| `output.png` | absent, Phase 6 deferred | preview-renderer tool |
+| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) |
+| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `LayerStackBadgeFixtureDocument` |
+| `output.png` | present (committed baseline) | `tools/preview-renderer` via `LayerStackBadgeFixtureDocument` |
 
-## What lands when
+## How the baseline was captured
 
-- **Phase 6** (preview-renderer): every `mvn test` regenerates
-  `layout-snapshot.json` from the real engine, writes
-  `output.pdf`, and converts the first page to `output.png`. The
-  illustrative `notes` field on the snapshot will be removed at that
-  point.
-- **Phase 7** (visual-diff): introduces a committed `output.png`
-  baseline and a tool that compares a new render against both
-  `layout-snapshot.json` and that baseline. Diffs are classified per
+The render plus visual-diff loop is built (see
+[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs)
+and the run recorded in
+[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)):
+
+- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs
+  --update-baseline` instantiates the no-arg `LayerStackBadgeFixtureDocument`,
+  calls its `compose(DocumentSession)`, writes `output.pdf`, and converts
+  the first page to `output.png` here.
+- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs`
+  re-renders and compares the new PNG against this committed `output.png`,
+  expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is
+  judged on the PNG, not the PDF bytes. Diffs are classified per
   [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md).
 
-Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it
-will be regenerated. Do edit it by hand now — it documents intent.
+`layout-snapshot.json` is not part of that loop. It stays hand-authored
+and illustrative, so it is safe to edit by hand; the render loop never
+regenerates it.
diff --git a/examples/skill-fixtures/layer-stack-badge/pom.xml b/examples/skill-fixtures/layer-stack-badge/pom.xml
index 3ac70e4..8c9bf58 100644
--- a/examples/skill-fixtures/layer-stack-badge/pom.xml
+++ b/examples/skill-fixtures/layer-stack-badge/pom.xml
@@ -12,7 +12,7 @@
     <maven.compiler.source>21</maven.compiler.source>
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
   </properties>
 
   <!--
diff --git a/examples/skill-fixtures/row-basic/README.md b/examples/skill-fixtures/row-basic/README.md
index d7de35b..7887eeb 100644
--- a/examples/skill-fixtures/row-basic/README.md
+++ b/examples/skill-fixtures/row-basic/README.md
@@ -38,25 +38,44 @@ composes its `Header` row.
 ## How to run
 
 1. `cd examples/skill-fixtures/row-basic`
-2. `mvn test`
+2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not
+   throw
 3. inspect `expected-output/layout-snapshot.json` for the intended
    region shape
 
-Phase 6 will additionally write `expected-output/output.pdf` and
-`expected-output/output.png` on every run.
-
-## Deferred checks
-
-The JUnit test currently asserts only that `compose(...)` does not
-throw. Three checks are pending the Phase 6 renderer and the Phase 7
-visual-diff tool:
-
-- layout-snapshot equality against
-  `expected-output/layout-snapshot.json`
-- PDF byte sanity (non-empty, valid header) on
-  `expected-output/output.pdf`
-- preview-image visual diff against a committed
-  `expected-output/output.png` baseline
-
-Each deferred check is listed in a comment block inside
+The committed render baseline is captured separately from the JUnit
+test. A no-arg
+[`RowBasicFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/rowbasic/RowBasicFixtureDocument.java)
+exposes the same `compose(DocumentSession)` the test exercises, and
+`tools/preview-renderer` drives it to `expected-output/output.pdf` and
+`output.png`. Run the loop from the repo root:
+
+- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG
+  against the committed baseline (expects `IDENTICAL`).
+- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the
+  `expected-output/output.{pdf,png}` baseline.
+
+## Checks
+
+The JUnit test still asserts only that `compose(...)` does not throw. The
+render and visual-diff now run through the `RowBasicFixtureDocument`
+adapter and `node scripts/validate-skills.mjs`, not the test:
+
+- preview-image visual diff against the committed
+  `expected-output/output.png` — wired. `node scripts/validate-skills.mjs`
+  re-renders via `tools/preview-renderer` and compares the PNG with
+  `tools/visual-diff`, expecting `IDENTICAL` (AE == 0).
+- rendered-output sanity — wired. The runner asserts the render produced a
+  non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since
+  PNG rasterisation is platform-specific). Full PDF byte equality is
+  intentionally skipped: PDFs carry timestamps, so parity is judged on the
+  PNG.
+- layout-snapshot equality against `expected-output/layout-snapshot.json`
+  — still not enforced. `layout-snapshot.json` stays illustrative; it
+  documents intent, not a measured engine run.
+
+The captured baseline sizes and the `IDENTICAL` result for all five
+fixtures are recorded in
+[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md).
+The same three checks are noted in a comment block inside
 [`RowBasicFixtureTest`](src/test/java/com/demcha/compose/document/fixtures/rowbasic/RowBasicFixtureTest.java).
diff --git a/examples/skill-fixtures/row-basic/expected-output/README.md b/examples/skill-fixtures/row-basic/expected-output/README.md
index 437d837..62393dc 100644
--- a/examples/skill-fixtures/row-basic/expected-output/README.md
+++ b/examples/skill-fixtures/row-basic/expected-output/README.md
@@ -1,30 +1,37 @@
 # expected-output for row-basic
 
-This folder is where the Phase 6 render-and-preview tool will write the
-rendered artifacts for this fixture. Until that lands, only
-`layout-snapshot.json` is present, and it is illustrative — the values
-describe the layout shape the fixture intends to produce, not values
-measured by a real engine run.
+This folder holds the committed render baseline for this fixture.
+`output.pdf` and `output.png` are produced by `tools/preview-renderer`
+driving the fixture's no-arg `RowBasicFixtureDocument` adapter.
+`layout-snapshot.json` is still illustrative — its values describe the
+layout shape the fixture intends to produce, not values measured by a
+real engine run.
 
 ## Files
 
 | File | Status | Populated by |
 |---|---|---|
-| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 |
-| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool |
-| `output.png` | absent, Phase 6 deferred | preview-renderer tool |
+| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) |
+| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `RowBasicFixtureDocument` |
+| `output.png` | present (committed baseline) | `tools/preview-renderer` via `RowBasicFixtureDocument` |
 
-## What lands when
+## How the baseline was captured
 
-- **Phase 6** (preview-renderer): every `mvn test` regenerates
-  `layout-snapshot.json` from the real engine, writes
-  `output.pdf`, and converts the first page to `output.png`. The
-  illustrative `notes` field on the snapshot will be removed at that
-  point.
-- **Phase 7** (visual-diff): introduces a committed `output.png`
-  baseline and a tool that compares a new render against both
-  `layout-snapshot.json` and that baseline. Diffs are classified per
+The render plus visual-diff loop is built (see
+[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs)
+and the run recorded in
+[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)):
+
+- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs
+  --update-baseline` instantiates the no-arg `RowBasicFixtureDocument`,
+  calls its `compose(DocumentSession)`, writes `output.pdf`, and converts
+  the first page to `output.png` here.
+- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs`
+  re-renders and compares the new PNG against this committed `output.png`,
+  expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is
+  judged on the PNG, not the PDF bytes. Diffs are classified per
   [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md).
 
-Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it
-will be regenerated. Do edit it by hand now — it documents intent.
+`layout-snapshot.json` is not part of that loop. It stays hand-authored
+and illustrative, so it is safe to edit by hand; the render loop never
+regenerates it.
diff --git a/examples/skill-fixtures/row-basic/pom.xml b/examples/skill-fixtures/row-basic/pom.xml
index 058284e..88eef6b 100644
--- a/examples/skill-fixtures/row-basic/pom.xml
+++ b/examples/skill-fixtures/row-basic/pom.xml
@@ -12,7 +12,7 @@
     <maven.compiler.source>21</maven.compiler.source>
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
   </properties>
 
   <!--
diff --git a/examples/skill-fixtures/section-basic/README.md b/examples/skill-fixtures/section-basic/README.md
index 12d60f5..bd028eb 100644
--- a/examples/skill-fixtures/section-basic/README.md
+++ b/examples/skill-fixtures/section-basic/README.md
@@ -37,22 +37,42 @@ panel section in the backgrounds-and-panels skill.
 ## How to run
 
 1. `cd examples/skill-fixtures/section-basic`
-2. `mvn test`
+2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not
+   throw
 3. inspect `expected-output/layout-snapshot.json` for the intended
    region shape, padding, and background token
 
-Phase 6 will additionally write `expected-output/output.pdf` and
-`expected-output/output.png` on every run.
+The committed render baseline is captured separately from the JUnit
+test. A no-arg
+[`SectionBasicFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/sectionbasic/SectionBasicFixtureDocument.java)
+exposes the same `compose(DocumentSession)` the test exercises, and
+`tools/preview-renderer` drives it to `expected-output/output.pdf` and
+`output.png`. Run the loop from the repo root:
 
-## Deferred checks
+- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG
+  against the committed baseline (expects `IDENTICAL`).
+- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the
+  `expected-output/output.{pdf,png}` baseline.
 
-The JUnit test currently asserts only that `compose(...)` does not
-throw. Three checks are pending the Phase 6 renderer and the Phase 7
-visual-diff tool:
+## Checks
 
-- layout-snapshot equality against
-  `expected-output/layout-snapshot.json`
-- PDF byte sanity (non-empty, valid header) on
-  `expected-output/output.pdf`
-- preview-image visual diff against a committed
-  `expected-output/output.png` baseline
+The JUnit test still asserts only that `compose(...)` does not throw. The
+render and visual-diff now run through the `SectionBasicFixtureDocument`
+adapter and `node scripts/validate-skills.mjs`, not the test:
+
+- preview-image visual diff against the committed
+  `expected-output/output.png` — wired. `node scripts/validate-skills.mjs`
+  re-renders via `tools/preview-renderer` and compares the PNG with
+  `tools/visual-diff`, expecting `IDENTICAL` (AE == 0).
+- rendered-output sanity — wired. The runner asserts the render produced a
+  non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since
+  PNG rasterisation is platform-specific). Full PDF byte equality is
+  intentionally skipped: PDFs carry timestamps, so parity is judged on the
+  PNG.
+- layout-snapshot equality against `expected-output/layout-snapshot.json`
+  — still not enforced. `layout-snapshot.json` stays illustrative; it
+  documents intent, not a measured engine run.
+
+The captured baseline sizes and the `IDENTICAL` result for all five
+fixtures are recorded in
+[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md).
diff --git a/examples/skill-fixtures/section-basic/expected-output/README.md b/examples/skill-fixtures/section-basic/expected-output/README.md
index 7f4b938..bc20122 100644
--- a/examples/skill-fixtures/section-basic/expected-output/README.md
+++ b/examples/skill-fixtures/section-basic/expected-output/README.md
@@ -1,30 +1,37 @@
 # expected-output for section-basic
 
-This folder is where the Phase 6 render-and-preview tool will write the
-rendered artifacts for this fixture. Until that lands, only
-`layout-snapshot.json` is present, and it is illustrative — the values
-describe the layout shape the fixture intends to produce, not values
-measured by a real engine run.
+This folder holds the committed render baseline for this fixture.
+`output.pdf` and `output.png` are produced by `tools/preview-renderer`
+driving the fixture's no-arg `SectionBasicFixtureDocument` adapter.
+`layout-snapshot.json` is still illustrative — its values describe the
+layout shape the fixture intends to produce, not values measured by a
+real engine run.
 
 ## Files
 
 | File | Status | Populated by |
 |---|---|---|
-| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 |
-| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool |
-| `output.png` | absent, Phase 6 deferred | preview-renderer tool |
+| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) |
+| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `SectionBasicFixtureDocument` |
+| `output.png` | present (committed baseline) | `tools/preview-renderer` via `SectionBasicFixtureDocument` |
 
-## What lands when
+## How the baseline was captured
 
-- **Phase 6** (preview-renderer): every `mvn test` regenerates
-  `layout-snapshot.json` from the real engine, writes
-  `output.pdf`, and converts the first page to `output.png`. The
-  illustrative `notes` field on the snapshot will be removed at that
-  point.
-- **Phase 7** (visual-diff): introduces a committed `output.png`
-  baseline and a tool that compares a new render against both
-  `layout-snapshot.json` and that baseline. Diffs are classified per
+The render plus visual-diff loop is built (see
+[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs)
+and the run recorded in
+[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)):
+
+- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs
+  --update-baseline` instantiates the no-arg `SectionBasicFixtureDocument`,
+  calls its `compose(DocumentSession)`, writes `output.pdf`, and converts
+  the first page to `output.png` here.
+- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs`
+  re-renders and compares the new PNG against this committed `output.png`,
+  expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is
+  judged on the PNG, not the PDF bytes. Diffs are classified per
   [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md).
 
-Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it
-will be regenerated. Do edit it by hand now — it documents intent.
+`layout-snapshot.json` is not part of that loop. It stays hand-authored
+and illustrative, so it is safe to edit by hand; the render loop never
+regenerates it.
diff --git a/examples/skill-fixtures/section-basic/pom.xml b/examples/skill-fixtures/section-basic/pom.xml
index e79f2e8..e916e84 100644
--- a/examples/skill-fixtures/section-basic/pom.xml
+++ b/examples/skill-fixtures/section-basic/pom.xml
@@ -12,7 +12,7 @@
     <maven.compiler.source>21</maven.compiler.source>
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
   </properties>
 
   <!--
diff --git a/examples/skill-fixtures/shape-container-card/README.md b/examples/skill-fixtures/shape-container-card/README.md
index 58a820e..4df314c 100644
--- a/examples/skill-fixtures/shape-container-card/README.md
+++ b/examples/skill-fixtures/shape-container-card/README.md
@@ -39,22 +39,42 @@ canvas paint.
 ## How to run
 
 1. `cd examples/skill-fixtures/shape-container-card`
-2. `mvn test`
+2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not
+   throw
 3. inspect `expected-output/layout-snapshot.json` for the intended
    corner radius and child content
 
-Phase 6 will additionally write `expected-output/output.pdf` and
-`expected-output/output.png` on every run.
+The committed render baseline is captured separately from the JUnit
+test. A no-arg
+[`ShapeContainerCardFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/shapecontainercard/ShapeContainerCardFixtureDocument.java)
+exposes the same `compose(DocumentSession)` the test exercises, and
+`tools/preview-renderer` drives it to `expected-output/output.pdf` and
+`output.png`. Run the loop from the repo root:
 
-## Deferred checks
+- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG
+  against the committed baseline (expects `IDENTICAL`).
+- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the
+  `expected-output/output.{pdf,png}` baseline.
 
-The JUnit test currently asserts only that `compose(...)` does not
-throw. Three checks are pending the Phase 6 renderer and the Phase 7
-visual-diff tool:
+## Checks
 
-- layout-snapshot equality against
-  `expected-output/layout-snapshot.json`
-- PDF byte sanity (non-empty, valid header) on
-  `expected-output/output.pdf`
-- preview-image visual diff against a committed
-  `expected-output/output.png` baseline
+The JUnit test still asserts only that `compose(...)` does not throw. The
+render and visual-diff now run through the `ShapeContainerCardFixtureDocument`
+adapter and `node scripts/validate-skills.mjs`, not the test:
+
+- preview-image visual diff against the committed
+  `expected-output/output.png` — wired. `node scripts/validate-skills.mjs`
+  re-renders via `tools/preview-renderer` and compares the PNG with
+  `tools/visual-diff`, expecting `IDENTICAL` (AE == 0).
+- rendered-output sanity — wired. The runner asserts the render produced a
+  non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since
+  PNG rasterisation is platform-specific). Full PDF byte equality is
+  intentionally skipped: PDFs carry timestamps, so parity is judged on the
+  PNG.
+- layout-snapshot equality against `expected-output/layout-snapshot.json`
+  — still not enforced. `layout-snapshot.json` stays illustrative; it
+  documents intent, not a measured engine run.
+
+The captured baseline sizes and the `IDENTICAL` result for all five
+fixtures are recorded in
+[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md).
diff --git a/examples/skill-fixtures/shape-container-card/expected-output/README.md b/examples/skill-fixtures/shape-container-card/expected-output/README.md
index 61dd700..265938a 100644
--- a/examples/skill-fixtures/shape-container-card/expected-output/README.md
+++ b/examples/skill-fixtures/shape-container-card/expected-output/README.md
@@ -1,30 +1,37 @@
 # expected-output for shape-container-card
 
-This folder is where the Phase 6 render-and-preview tool will write the
-rendered artifacts for this fixture. Until that lands, only
-`layout-snapshot.json` is present, and it is illustrative — the values
-describe the layout shape the fixture intends to produce, not values
-measured by a real engine run.
+This folder holds the committed render baseline for this fixture.
+`output.pdf` and `output.png` are produced by `tools/preview-renderer`
+driving the fixture's no-arg `ShapeContainerCardFixtureDocument` adapter.
+`layout-snapshot.json` is still illustrative — its values describe the
+layout shape the fixture intends to produce, not values measured by a
+real engine run.
 
 ## Files
 
 | File | Status | Populated by |
 |---|---|---|
-| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 |
-| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool |
-| `output.png` | absent, Phase 6 deferred | preview-renderer tool |
+| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) |
+| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `ShapeContainerCardFixtureDocument` |
+| `output.png` | present (committed baseline) | `tools/preview-renderer` via `ShapeContainerCardFixtureDocument` |
 
-## What lands when
+## How the baseline was captured
 
-- **Phase 6** (preview-renderer): every `mvn test` regenerates
-  `layout-snapshot.json` from the real engine, writes
-  `output.pdf`, and converts the first page to `output.png`. The
-  illustrative `notes` field on the snapshot will be removed at that
-  point.
-- **Phase 7** (visual-diff): introduces a committed `output.png`
-  baseline and a tool that compares a new render against both
-  `layout-snapshot.json` and that baseline. Diffs are classified per
+The render plus visual-diff loop is built (see
+[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs)
+and the run recorded in
+[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)):
+
+- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs
+  --update-baseline` instantiates the no-arg `ShapeContainerCardFixtureDocument`,
+  calls its `compose(DocumentSession)`, writes `output.pdf`, and converts
+  the first page to `output.png` here.
+- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs`
+  re-renders and compares the new PNG against this committed `output.png`,
+  expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is
+  judged on the PNG, not the PDF bytes. Diffs are classified per
   [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md).
 
-Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it
-will be regenerated. Do edit it by hand now — it documents intent.
+`layout-snapshot.json` is not part of that loop. It stays hand-authored
+and illustrative, so it is safe to edit by hand; the render loop never
+regenerates it.
diff --git a/examples/skill-fixtures/shape-container-card/pom.xml b/examples/skill-fixtures/shape-container-card/pom.xml
index beeccb1..3a62c69 100644
--- a/examples/skill-fixtures/shape-container-card/pom.xml
+++ b/examples/skill-fixtures/shape-container-card/pom.xml
@@ -12,7 +12,7 @@
     <maven.compiler.source>21</maven.compiler.source>
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
   </properties>
 
   <!--
diff --git a/examples/skill-fixtures/table-basic/README.md b/examples/skill-fixtures/table-basic/README.md
index 1be22ef..941bcca 100644
--- a/examples/skill-fixtures/table-basic/README.md
+++ b/examples/skill-fixtures/table-basic/README.md
@@ -46,22 +46,42 @@ engine).
 ## How to run
 
 1. `cd examples/skill-fixtures/table-basic`
-2. `mvn test`
+2. `mvn test` — the JUnit smoke test; asserts `compose(...)` does not
+   throw
 3. inspect `expected-output/layout-snapshot.json` for the intended
    columns, header config, and data rows
 
-Phase 6 will additionally write `expected-output/output.pdf` and
-`expected-output/output.png` on every run.
+The committed render baseline is captured separately from the JUnit
+test. A no-arg
+[`TableBasicFixtureDocument`](src/main/java/com/demcha/compose/document/fixtures/tablebasic/TableBasicFixtureDocument.java)
+exposes the same `compose(DocumentSession)` the test exercises, and
+`tools/preview-renderer` drives it to `expected-output/output.pdf` and
+`output.png`. Run the loop from the repo root:
 
-## Deferred checks
+- `node scripts/validate-skills.mjs` — re-render and visual-diff the PNG
+  against the committed baseline (expects `IDENTICAL`).
+- `node scripts/validate-skills.mjs --update-baseline` — (re)capture the
+  `expected-output/output.{pdf,png}` baseline.
 
-The JUnit test currently asserts only that `compose(...)` does not
-throw. Three checks are pending the Phase 6 renderer and the Phase 7
-visual-diff tool:
+## Checks
 
-- layout-snapshot equality against
-  `expected-output/layout-snapshot.json`
-- PDF byte sanity (non-empty, valid header) on
-  `expected-output/output.pdf`
-- preview-image visual diff against a committed
-  `expected-output/output.png` baseline
+The JUnit test still asserts only that `compose(...)` does not throw. The
+render and visual-diff now run through the `TableBasicFixtureDocument`
+adapter and `node scripts/validate-skills.mjs`, not the test:
+
+- preview-image visual diff against the committed
+  `expected-output/output.png` — wired. `node scripts/validate-skills.mjs`
+  re-renders via `tools/preview-renderer` and compares the PNG with
+  `tools/visual-diff`, expecting `IDENTICAL` (AE == 0).
+- rendered-output sanity — wired. The runner asserts the render produced a
+  non-empty `output.pdf` and `output.png` (CI runs `--render-only`, since
+  PNG rasterisation is platform-specific). Full PDF byte equality is
+  intentionally skipped: PDFs carry timestamps, so parity is judged on the
+  PNG.
+- layout-snapshot equality against `expected-output/layout-snapshot.json`
+  — still not enforced. `layout-snapshot.json` stays illustrative; it
+  documents intent, not a measured engine run.
+
+The captured baseline sizes and the `IDENTICAL` result for all five
+fixtures are recorded in
+[`../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../validation/reports/skill-render-validation-2026-06-03.md).
diff --git a/examples/skill-fixtures/table-basic/expected-output/README.md b/examples/skill-fixtures/table-basic/expected-output/README.md
index 04fe5c4..9b26091 100644
--- a/examples/skill-fixtures/table-basic/expected-output/README.md
+++ b/examples/skill-fixtures/table-basic/expected-output/README.md
@@ -1,30 +1,37 @@
 # expected-output for table-basic
 
-This folder is where the Phase 6 render-and-preview tool will write the
-rendered artifacts for this fixture. Until that lands, only
-`layout-snapshot.json` is present, and it is illustrative — the values
-describe the layout shape the fixture intends to produce, not values
-measured by a real engine run.
+This folder holds the committed render baseline for this fixture.
+`output.pdf` and `output.png` are produced by `tools/preview-renderer`
+driving the fixture's no-arg `TableBasicFixtureDocument` adapter.
+`layout-snapshot.json` is still illustrative — its values describe the
+layout shape the fixture intends to produce, not values measured by a
+real engine run.
 
 ## Files
 
 | File | Status | Populated by |
 |---|---|---|
-| `layout-snapshot.json` | present, illustrative | placeholder for Phase 6 |
-| `output.pdf` | absent, Phase 6 deferred | preview-renderer tool |
-| `output.png` | absent, Phase 6 deferred | preview-renderer tool |
+| `layout-snapshot.json` | present, illustrative | hand-authored (documents intent) |
+| `output.pdf` | present (committed baseline) | `tools/preview-renderer` via `TableBasicFixtureDocument` |
+| `output.png` | present (committed baseline) | `tools/preview-renderer` via `TableBasicFixtureDocument` |
 
-## What lands when
+## How the baseline was captured
 
-- **Phase 6** (preview-renderer): every `mvn test` regenerates
-  `layout-snapshot.json` from the real engine, writes
-  `output.pdf`, and converts the first page to `output.png`. The
-  illustrative `notes` field on the snapshot will be removed at that
-  point.
-- **Phase 7** (visual-diff): introduces a committed `output.png`
-  baseline and a tool that compares a new render against both
-  `layout-snapshot.json` and that baseline. Diffs are classified per
+The render plus visual-diff loop is built (see
+[`../../../../scripts/validate-skills.mjs`](../../../../scripts/validate-skills.mjs)
+and the run recorded in
+[`../../../../validation/reports/skill-render-validation-2026-06-03.md`](../../../../validation/reports/skill-render-validation-2026-06-03.md)):
+
+- **Render** (`tools/preview-renderer`): `node scripts/validate-skills.mjs
+  --update-baseline` instantiates the no-arg `TableBasicFixtureDocument`,
+  calls its `compose(DocumentSession)`, writes `output.pdf`, and converts
+  the first page to `output.png` here.
+- **Visual-diff** (`tools/visual-diff`): `node scripts/validate-skills.mjs`
+  re-renders and compares the new PNG against this committed `output.png`,
+  expecting `IDENTICAL` (AE == 0). PDFs carry timestamps, so parity is
+  judged on the PNG, not the PDF bytes. Diffs are classified per
   [`../../../../docs/visual-accuracy-contract.md`](../../../../docs/visual-accuracy-contract.md).
 
-Do not edit `layout-snapshot.json` by hand once Phase 6 is wired; it
-will be regenerated. Do edit it by hand now — it documents intent.
+`layout-snapshot.json` is not part of that loop. It stays hand-authored
+and illustrative, so it is safe to edit by hand; the render loop never
+regenerates it.
diff --git a/examples/skill-fixtures/table-basic/pom.xml b/examples/skill-fixtures/table-basic/pom.xml
index fb74993..534a00b 100644
--- a/examples/skill-fixtures/table-basic/pom.xml
+++ b/examples/skill-fixtures/table-basic/pom.xml
@@ -12,7 +12,7 @@
     <maven.compiler.source>21</maven.compiler.source>
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
   </properties>
 
   <!--
diff --git a/prompts/architecture-mapper-agent.md b/prompts/architecture-mapper-agent.md
index aaf538e..24f8625 100644
--- a/prompts/architecture-mapper-agent.md
+++ b/prompts/architecture-mapper-agent.md
@@ -170,7 +170,7 @@ overlays add review-time value for this template:
 | section header anchors              | yes / no / partial | "yes — banner variants need consistent baseline"          |
 | row baselines                       | yes / no / partial | "no — single-column flow, baselines never drift"          |
 | layer-stack frames                  | yes / no / partial | "yes — badge sits half-off the card, frame proves clip"   |
-| pageBackgrounds bands               | yes / no / partial | "yes — multi-rect masthead per 1.6.7"                     |
+| pageBackgrounds bands               | yes / no / partial | "yes — multi-rect masthead per 1.7.0"                     |
 
 The debug PDF stays in the revision folder
 (`<revision>/output-debug.pdf` + per-page PNGs). Visual Review reads
@@ -228,7 +228,7 @@ Rules:
   is already V2 — do not author a `proposal/v2/` parallel package.
 - **New invoice → V1 classic.** Implement the canonical
   `InvoiceTemplate` interface; render through `InvoiceDocumentSpec`.
-  The V2 invoice stack is not landed upstream as of 1.6.7 — flag this
+  The V2 invoice stack is not landed upstream as of 1.7.0 — flag this
   in `Known Limitations` so a future migration has a clear
   starting point.
 - **Existing revision chain → stick with whatever the prior revision
@@ -255,6 +255,18 @@ edge cases rather than guessing.
 | Background shape | page background / shape container |
 | Accent border | theme token / section accent |
 | Exact decoration | `CanvasLayer` only if needed |
+| Skill rating dots / inline status mark | inline shape run — `ParagraphBuilder.dot(...)` / `shape(ShapeOutline, ...)` (1.7.0) |
+| Work history / milestones / numbered steps | `addTimeline(...)` with `TimelineMarker` (1.7.0) |
+| Dashed divider / cut-here rule | `LineBuilder.dashed(...)` (1.7.0) |
+| Section title on a filled plaque | `headingBar(text, ...)` (1.7.0) |
+| Card rounded on some corners only | `roundedRect(w, h, DocumentCornerRadius)` (1.7.0) |
+| Label centred in a tall pill | `verticalAlign(TextVerticalAlign.CENTER)` + centred layer (1.7.0) |
+
+These 1.7.0 primitives are additive — see
+[`skills/versions/graphcompose-1.7/`](../skills/versions/graphcompose-1.7/)
+(`typography`, `shapes-and-containers`, `layout-primitives`,
+`spacing-and-alignment`) for the usage rules and the
+no-invented-API caveat.
 
 ## Shape ownership mapping
 
@@ -278,14 +290,16 @@ version cannot express the relationship with a shape container,
 record a `Known Limitation` and stop the implementation path rather
 than inventing a visual overlay workaround.
 
-## @Beta surfaces (1.6.7+): record before picking
+## @Beta surfaces (1.7.0+): record before picking
 
 A `@Beta`-marked GraphCompose API is an **Extension SPI** — the
 library lets callers implement or reach it, but its shape MAY evolve
 between minor releases (one minor of `@Deprecated` warning then break).
-As of 1.6.7 the only `@Beta` surface is
+As of 1.7.0 the only `@Beta` surface is
 `com.demcha.compose.document.layout.NodeDefinition` (the custom
-node-type seam).
+node-type seam). The 1.7.0 additive primitives (inline shape runs,
+timelines, dashed lines, `headingBar`, per-corner `roundedRect`,
+vertical text align) are all `Stable`, not `@Beta`.
 
 When the Architecture Mapper picks a `@Beta` surface, the plan MUST:
 
@@ -293,7 +307,7 @@ When the Architecture Mapper picks a `@Beta` surface, the plan MUST:
    [`docs/architecture/package-map.md`](https://github.com/DemchaAV/GraphCompose/blob/main/docs/architecture/package-map.md)
    could express the same relationship. The decision order is the
    one from
-   [`skills/versions/graphcompose-1.6/layer-stacks-and-overlays.md`](../skills/versions/graphcompose-1.6/layer-stacks-and-overlays.md)
+   [`skills/versions/graphcompose-1.7/layer-stacks-and-overlays.md`](../skills/versions/graphcompose-1.7/layer-stacks-and-overlays.md)
    § "Custom node types are an @Beta SPI": documented primitive →
    `LayerStack` → `ShapeContainer` → `CanvasLayer` → `NodeDefinition`.
 2. Add a `Known Limitation` entry that records (a) which `@Beta`
diff --git a/prompts/orchestrator-agent.md b/prompts/orchestrator-agent.md
index 24f201d..a018ba9 100644
--- a/prompts/orchestrator-agent.md
+++ b/prompts/orchestrator-agent.md
@@ -199,7 +199,7 @@ continuing. Halt the loop ONLY when one of these is true:
 | "Add a new section" / "new badge in the header" | Revision | `visual-change` |
 | "Rename the helper / extract this method" | Revision | `refactor-only` |
 | "Split the spec into nested records" | Revision | `refactor-only` |
-| "Upgrade to GraphCompose 1.6.7" | Revision | `refactor-only` |
+| "Upgrade to GraphCompose 1.7.0" | Revision | `refactor-only` |
 | "Re-resolve assets, output should match" | Revision | `refactor-only` |
 | "Previous version was better" | Undo last change | — (no new revision) |
 | "Return to approved version" | Revert to approved | — (no new revision) |
diff --git a/prompts/template-coder-agent.md b/prompts/template-coder-agent.md
index 45a5e73..4c2c590 100644
--- a/prompts/template-coder-agent.md
+++ b/prompts/template-coder-agent.md
@@ -407,7 +407,7 @@ public final class AiGeneratedInvoiceTemplate implements DocumentTemplate<Invoic
 
 The Architecture Mapper records the target surface under
 `Target GraphCompose Version`. The Template Coder MUST follow it
-verbatim. Two surfaces exist on the canonical side as of 1.6.7:
+verbatim. Two surfaces exist on the canonical side as of 1.7.0:
 
 - **V2 layered** (`com.demcha.compose.document.templates.cv.v2.*`,
   `com.demcha.compose.document.templates.coverletter.v2.*`) is
@@ -464,7 +464,20 @@ Helpers, type imports, and DSL idioms that are surface-agnostic
 `ShapeContainerBuilder`, `DocumentTextStyle`, `BusinessTheme`,
 `FontName`) are free to use regardless of surface.
 
-## @Beta SPI usage (1.6.7+)
+The GraphCompose 1.7.0 additive primitives are likewise
+surface-agnostic and `Stable` (not `@Beta`): inline shape runs
+(`ParagraphBuilder` / `RichText` `dot(...)` / `arrow(...)` /
+`checkbox(...)` / `shape(ShapeOutline, ...)`), `addTimeline(...)`,
+`LineBuilder.dashed(...)`, `headingBar(...)`, per-corner
+`roundedRect(w, h, DocumentCornerRadius)`,
+`verticalAlign(TextVerticalAlign)`, `FontName.JETBRAINS_MONO`, and
+`DocumentSession.availableHeight()`. Prefer them over the workarounds
+the 1.6.x pack described (font-glyph rating dots, hand-placed timeline
+bullets, CLIP_PATH-parent per-corner cards); the usage rules and the
+no-invented-API caveat live in the `skills/versions/graphcompose-1.7/`
+topic skills.
+
+## @Beta SPI usage (1.7.0+)
 
 When `architecture-plan.md` records a `@Beta` surface (currently only
 `com.demcha.compose.document.layout.NodeDefinition` — the custom
@@ -480,8 +493,8 @@ node-type seam), the Template Coder MUST:
    ```java
    /**
     * Custom timeline-spine overlay built on the @Beta NodeDefinition SPI.
-    * Verified against GraphCompose {@code io.github.demchaav:graph-compose:1.6.7}.
-    * The SPI shape may evolve in 1.7.x — see architecture-plan.md
+    * Verified against GraphCompose {@code io.github.demchaav:graph-compose:1.7.0}.
+    * The SPI shape may evolve in a future minor — see architecture-plan.md
     * "Known Limitations" for the recorded migration risk.
     */
    private void renderTimelineSpineBetaSpi(...) { ... }
diff --git a/scripts/lib/skill-validation-gate.mjs b/scripts/lib/skill-validation-gate.mjs
index a09113b..c5a2126 100644
--- a/scripts/lib/skill-validation-gate.mjs
+++ b/scripts/lib/skill-validation-gate.mjs
@@ -163,7 +163,7 @@ function readSkillIdsFromManifest(repoRoot) {
 
 function deriveTargetCoordinate(project) {
   const raw = project?.targetGraphComposeVersion;
-  if (!raw) return "io.github.demchaav:graph-compose:1.6.7";
+  if (!raw) return "io.github.demchaav:graph-compose:1.7.0";
   const cleaned = String(raw).replace(/^v/, "");
   // 1.6.7+ ships on Maven Central; pre-1.6.7 lives on JitPack.
   if (compareSemver(cleaned, "1.6.7") >= 0) {
@@ -274,7 +274,7 @@ function buildAutoPopulatedReport({
     "## Notes\n" +
     "\n" +
     "- The fixture matrix runs `mvn -B test` against each module,\n" +
-    "  picking up `io.github.demchaav:graph-compose:1.6.7` from Maven\n" +
+    "  picking up `io.github.demchaav:graph-compose:1.7.0` from Maven\n" +
     "  Central. A failing fixture would block the merge that produced\n" +
     "  this revision, so by induction the fixture-backed list is\n" +
     "  honest as long as the run is reproducible from main.\n" +
diff --git a/scripts/publish-template.mjs b/scripts/publish-template.mjs
index 66faacc..02d2826 100644
--- a/scripts/publish-template.mjs
+++ b/scripts/publish-template.mjs
@@ -81,6 +81,11 @@ mkdirp(targetSrcDir, targetDataDir, targetAssetsDir, targetIconsDir, targetPrevi
 
 const sourceClassFile = path.join(revisionDir, "generated-template.java");
 const targetClassFile = path.join(targetSrcDir, `${className}.java`);
+const sourceClassName =
+  simpleClassName(projectMeta.render && projectMeta.render.templateClass)
+  || simpleClassName(projectMeta.templateClass)
+  || inferPublicClassName(sourceClassFile)
+  || "GeneratedCvTemplate";
 // The template class carries the agent's editorial Javadoc polish on
 // top of the renamed source. Subsequent publishes preserve that work
 // by default — pass --force-template to overwrite (e.g. after a real
@@ -89,7 +94,7 @@ if (fs.existsSync(targetClassFile) && !args["force-template"]) {
   console.log(`[publish-template] ${path.relative(repoRoot, targetClassFile)} already exists; preserving the agent's Javadoc polish. Pass --force-template to overwrite.`);
 } else {
   copyJavaClass(sourceClassFile, targetClassFile, {
-    oldClassName: "GeneratedCvTemplate",
+    oldClassName: sourceClassName,
     newClassName: className,
   });
 }
@@ -263,6 +268,24 @@ function pascalCase(s) {
     .join("");
 }
 
+function simpleClassName(fqcn) {
+  if (typeof fqcn !== "string" || fqcn.trim() === "") {
+    return null;
+  }
+  const parts = fqcn.trim().split(".");
+  return parts[parts.length - 1] || null;
+}
+
+function inferPublicClassName(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  const content = fs.readFileSync(filePath, "utf8");
+  const match = content.match(/\bpublic\s+final\s+class\s+([A-Za-z_$][\w$]*)\b/)
+      || content.match(/\bpublic\s+class\s+([A-Za-z_$][\w$]*)\b/);
+  return match ? match[1] : null;
+}
+
 function readJsonIfExists(filePath) {
   if (!fs.existsSync(filePath)) {
     return null;
diff --git a/scripts/validate-skills.mjs b/scripts/validate-skills.mjs
index 761231f..fc3085d 100644
--- a/scripts/validate-skills.mjs
+++ b/scripts/validate-skills.mjs
@@ -48,8 +48,8 @@ const STUB_REVISION = JSON.stringify({
   parentRevisionId: null,
   status: 'DRAFT',
   userRequest: 'skill fixture render',
-  targetGraphComposeVersion: '1.6.7',
-  skillPack: 'skills/versions/graphcompose-1.6',
+  targetGraphComposeVersion: '1.7.0',
+  skillPack: 'skills/versions/graphcompose-1.7',
   createdAt: '2026-01-01T00:00:00Z',
   artifacts: { userRequest: 'user-request.md' },
   pendingArtifacts: ['output.pdf', 'output.png'],
diff --git a/skills/README.md b/skills/README.md
index 4bb4bfb..0da591f 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -21,12 +21,15 @@ first and load only the skill files it references.
 
 ## Current status
 
-Phase 2 has shipped the first skill pack under
-[`versions/graphcompose-1.6/`](versions/graphcompose-1.6/). It contains 14
-skill files, all listed in [`skill-manifest.json`](skill-manifest.json) with
+The active skill pack is
+[`versions/graphcompose-1.7/`](versions/graphcompose-1.7/) — a port of the
+1.6.x pack first shipped in Phase 2 (retained as a frozen snapshot under
+[`versions/graphcompose-1.6/`](versions/graphcompose-1.6/) for projects
+pinned back to 1.6.x). It contains 14 skill files, all listed in
+[`skill-manifest.json`](skill-manifest.json) with
 `status: needs-validation`. Five fixture projects now compile and run
-against GraphCompose 1.6.7 from Maven Central
-(`io.github.demchaav:graph-compose:1.6.7`; JitPack remains a fallback
+against GraphCompose 1.7.0 from Maven Central
+(`io.github.demchaav:graph-compose:1.7.0`; JitPack remains a fallback
 for pre-1.6.7 pins), which proves the covered API calls resolve
 against the real library. Full skill validation still requires the
 render + preview + visual-diff loop, so no skill is promoted to
@@ -61,7 +64,7 @@ agent MUST consult the hosted Javadoc rather than guess or grep an
 unverified copy of the GraphCompose source:
 
 - **Pinned-version Javadoc (current target):**
-  [javadoc.io/doc/io.github.demchaav/graph-compose/1.6.7](https://javadoc.io/doc/io.github.demchaav/graph-compose/1.6.7)
+  [javadoc.io/doc/io.github.demchaav/graph-compose/1.7.0](https://javadoc.io/doc/io.github.demchaav/graph-compose/1.7.0)
 - **Stable-version alias:**
   [javadoc.io/doc/io.github.demchaav/graph-compose](https://javadoc.io/doc/io.github.demchaav/graph-compose)
 
diff --git a/skills/skill-manifest.json b/skills/skill-manifest.json
index 1cc9d8a..ddb5b86 100644
--- a/skills/skill-manifest.json
+++ b/skills/skill-manifest.json
@@ -1,95 +1,96 @@
 {
-  "skillsVersion": "0.2.0",
+  "skillsVersion": "0.3.0",
   "targetLibrary": "GraphCompose",
   "supportedGraphComposeVersions": [
-    "1.6.x"
+    "1.6.x",
+    "1.7.x"
   ],
-  "defaultGraphComposeVersion": "1.6.x",
+  "defaultGraphComposeVersion": "1.7.x",
   "skills": [
     {
       "id": "graphcompose-basics",
-      "file": "versions/graphcompose-1.6/graphcompose-basics.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/graphcompose-basics.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "visual-to-graphcompose-mapping",
-      "file": "versions/graphcompose-1.6/visual-to-graphcompose-mapping.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/visual-to-graphcompose-mapping.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "layout-primitives",
-      "file": "versions/graphcompose-1.6/layout-primitives.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/layout-primitives.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "tables",
-      "file": "versions/graphcompose-1.6/tables.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/tables.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "themes-and-colors",
-      "file": "versions/graphcompose-1.6/themes-and-colors.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/themes-and-colors.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "typography",
-      "file": "versions/graphcompose-1.6/typography.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/typography.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "spacing-and-alignment",
-      "file": "versions/graphcompose-1.6/spacing-and-alignment.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/spacing-and-alignment.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "backgrounds-and-panels",
-      "file": "versions/graphcompose-1.6/backgrounds-and-panels.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/backgrounds-and-panels.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "layer-stacks-and-overlays",
-      "file": "versions/graphcompose-1.6/layer-stacks-and-overlays.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/layer-stacks-and-overlays.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "shapes-and-containers",
-      "file": "versions/graphcompose-1.6/shapes-and-containers.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/shapes-and-containers.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "pagination",
-      "file": "versions/graphcompose-1.6/pagination.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/pagination.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "visual-regression",
-      "file": "versions/graphcompose-1.6/visual-regression.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/visual-regression.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "revision-discipline",
-      "file": "versions/graphcompose-1.6/revision-discipline.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/revision-discipline.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     },
     {
       "id": "troubleshooting",
-      "file": "versions/graphcompose-1.6/troubleshooting.md",
-      "verifiedAgainst": "1.6.7",
+      "file": "versions/graphcompose-1.7/troubleshooting.md",
+      "verifiedAgainst": "1.7.0",
       "status": "needs-validation"
     }
   ],
-  "notes": "Skill pack written for graphcompose-1.6.x. Five fixture projects compile and run against GraphCompose 1.6.7 from Maven Central (io.github.demchaav:graph-compose:1.6.7; pre-1.6.7 pins remain resolvable via JitPack as com.github.DemchaAV:GraphCompose:vX.Y.Z). All skills remain needs-validation until full render, preview, and visual-diff validation passes."
+  "notes": "Active skill pack targets graphcompose-1.7.x (verified against 1.7.0 from Maven Central: io.github.demchaav:graph-compose:1.7.0). v1.7.0 is additive over 1.6.x (zero breaking changes), so the pack is a port of graphcompose-1.6 plus the new 1.7 primitives (inline shape runs, polygon geometry, composite inline figures + checkboxes, swappable tick/arrow styles, softPanel stroke overloads, per-corner radius, vertical text alignment, JetBrains Mono, dashed/dotted lines, semantic timelines, availableHeight(), headingBar(...)) and the nested-stack position() fix. The frozen graphcompose-1.6 snapshot is retained on disk under versions/graphcompose-1.6/ so a project that pins back to 1.6.x still resolves a version-accurate pack; pre-1.6.7 pins remain resolvable via JitPack as com.github.DemchaAV:GraphCompose:vX.Y.Z. All skills remain needs-validation until the full render, preview, and visual-diff loop passes against 1.7.0."
 }
diff --git a/skills/versions/graphcompose-1.6/spacing-and-alignment.md b/skills/versions/graphcompose-1.6/spacing-and-alignment.md
index 480e253..29466ee 100644
--- a/skills/versions/graphcompose-1.6/spacing-and-alignment.md
+++ b/skills/versions/graphcompose-1.6/spacing-and-alignment.md
@@ -55,19 +55,37 @@ token without touching unrelated spacing.
 
 ## Alignment grids and how primitives enforce them
 
-Rows align their children horizontally; sections align their
-children vertically. Both primitives expose alignment options that
-should be the first tool reached for, not bespoke offsets.
-
-- A row primitive aligns children along a shared baseline (top,
-  center, baseline-of-text, or bottom). Use the alignment option
-  rather than inserting blank space to fake vertical balance.
-- A section primitive aligns children along a shared edge (left,
-  right, center, or stretch). Use the section's alignment, not
-  per-child padding hacks.
+Rows arrange their children horizontally (side by side); sections
+stack their children vertically. Neither primitive exposes a
+cross-axis alignment option in 1.6 — there is no row-level "centre
+the children vertically" knob and no section-level "centre the
+children horizontally" knob. Reach for the right structural tool
+instead of faking balance with blank space.
+
+- A row places children along the horizontal axis by weight or
+  width. It does NOT vertically align children of different heights
+  — `RowBuilder` has no top / center / baseline / bottom option. To
+  put an icon and a text label on a shared vertical axis, give them
+  the same height, or wrap the pair in a shape container / layer
+  stack and centre each layer with `.center(...)` / `LayerAlign`
+  (see [`layer-stacks-and-overlays`](layer-stacks-and-overlays.md)
+  and [`shapes-and-containers`](shapes-and-containers.md)).
+- A section stacks children vertically at the content width. It has
+  no left / right / center / stretch child-alignment option; a
+  child's horizontal position comes from its own width and, for
+  text, the paragraph's `TextAlign`. For a centred badge or label
+  inside a box, use a shape container / layer-stack layer with a
+  `LayerAlign` anchor, not a section option.
 - When two adjacent regions must share a visual edge (a header
-  bottom flush with a hero top), align them through the parent
-  primitive rather than per-region padding fudges.
+  bottom flush with a hero top), align them by matching their
+  measured heights / widths and the parent gap, not by per-region
+  padding fudges.
+
+Note: 1.6 has no per-line vertical-centring control on text. A
+single line dropped into a taller box sits on its font baseline,
+not optically centred — centre the whole text layer with a shape
+container / layer-stack `.center(...)` rather than nudging it with
+blank lines or padding lifts.
 
 If the reference clearly uses a column grid (12 columns, 8 columns,
 etc.), the template should express that grid through the row or
@@ -107,7 +125,7 @@ Load this skill any time:
 - the reference uses an obvious column grid
 
 This skill chains with [`layout-primitives`](layout-primitives.md)
-(for alignment options on the row and section primitives),
+(for choosing the right primitive),
 [`tables`](tables.md) (for cell padding), and
 [`themes-and-colors`](themes-and-colors.md) (for the shared naming
 discipline).
@@ -134,8 +152,8 @@ discipline).
 
 - [`graphcompose-basics`](graphcompose-basics.md) for the place of
   layout in the semantic model
-- [`layout-primitives`](layout-primitives.md) for the primitive
-  alignment options
+- [`layout-primitives`](layout-primitives.md) for choosing the
+  right primitive
 - [`tables`](tables.md) for cell padding and table-internal gaps
 - [`themes-and-colors`](themes-and-colors.md) for the shared
   naming convention
diff --git a/skills/versions/graphcompose-1.7/backgrounds-and-panels.md b/skills/versions/graphcompose-1.7/backgrounds-and-panels.md
new file mode 100644
index 0000000..8f4e2ca
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/backgrounds-and-panels.md
@@ -0,0 +1,290 @@
+---
+skillId: backgrounds-and-panels
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Backgrounds and Panels Skill
+
+Use this skill when the visual reference contains coloured surfaces
+that carry content: a tinted page, a section block on a light fill, a
+soft card behind a paragraph, an accent strip in the header, or a
+coloured band that separates two regions. The shared idea is that the
+surface is part of the document structure — it groups, anchors, or
+separates content — not a free-floating decoration.
+
+## When to load
+
+Load this skill whenever the
+[`visual-to-graphcompose-mapping`](visual-to-graphcompose-mapping.md)
+analysis lists any of the following on the reference:
+
+- a coloured or textured page background
+- a section that sits on its own coloured fill
+- a panel or card around grouped text
+- an accent strip aligned with a header, row, or section edge
+- a horizontal coloured band separating two regions
+
+If the reference only has overlapping decorations sitting on top of
+otherwise plain content, switch to
+[`layer-stacks-and-overlays`](layer-stacks-and-overlays.md) instead.
+If the reference has rounded cards or clipped shapes that themselves
+carry content, also load
+[`shapes-and-containers`](shapes-and-containers.md).
+
+## The surfaces
+
+### Page background
+
+A colour (or texture) that fills the whole page, edge to edge. Use the
+**session-level** page-background API:
+
+- `DocumentSession.pageBackground(color)` — a single full-page tint.
+- `DocumentSession.pageBackgrounds(List<PageBackgroundFill>)` — one or
+  more multi-column / partial-page fills (a pale sidebar column, an
+  accent stripe, a top/bottom band) that repeat on every page.
+
+It is purely declarative — it does not change layout, it composes
+correctly with margins, headers, and footers, and the engine repeats it
+on every page automatically.
+
+It is **not** `pageFlow().fillColor(...)`, and **not** a `fillColor` on
+a wrapper section, and never a giant rectangle drawn from a canvas
+layer. The first two are *container fills* bounded by content height —
+they stop short of the page bottom on short content (see
+[Container fill vs page background](#container-fill-vs-page-background))
+— and a canvas rectangle is opaque to pagination and snapshots.
+
+Semantic intent: "the document itself is tinted".
+
+### Section background
+
+A coloured fill scoped to one semantic block. Apply `fillColor(...)` to
+the section primitive that already groups the content
+(`section.fillColor(...)`). The fill is bounded by the section's
+laid-out content — exactly right for a block that wraps the content it
+colours (a navy header plaque, a tinted summary box). Do not introduce
+a wrapper panel just to colour a region you already have, and do not
+try to stretch a section fill to cover the rest of the page: a page
+tint is a page background, not a section fill (see
+[Container fill vs page background](#container-fill-vs-page-background)).
+
+Semantic intent: "this group of content has its own visual surface".
+
+### Soft panel
+
+A subtle fill — often near-white or pale grey — that groups a small
+piece of content (a callout, an info note, a totals box) without
+shouting. The implementation is the same as a section background; the
+distinction is one of contrast: a panel is quiet, a section background
+is part of the brand.
+
+Semantic intent: "this content reads as a single quiet block".
+
+### Card
+
+A more pronounced surface that visually lifts content above the page.
+A card may have a border, a stronger fill, or rounded corners. If the
+corners are rounded, the implementation moves to a shape container —
+see [`shapes-and-containers`](shapes-and-containers.md). If the card
+is rectangular, the same section-background primitive is enough.
+
+Semantic intent: "this is a distinct, raised object on the page".
+
+### Accent strip
+
+A thin coloured strip — usually a few millimetres tall — that runs
+along the edge of a row, section, or header. The strip is part of the
+section it accents; it should be expressed through the theme accent
+of the section, not as a stand-alone bar layered on top.
+
+Semantic intent: "this row is branded".
+
+### Coloured band
+
+A full-width horizontal band that separates two regions of the page.
+A band is a section whose only content is its background; it can be
+expressed as a thin section with the appropriate fill colour. It is
+not a layer-stack element.
+
+Semantic intent: "the document changes mode here".
+
+### Soft panel with an outline (1.7.0)
+
+A rounded, padded background that also needs a thin border used to
+require a separate wrapping node. 1.7.0 adds stroke overloads on the
+flow builder — `softPanel(color, radius, padding, stroke)` and
+`softPanel(color, cornerRadius, padding, stroke)` — that apply a border
+stroke alongside the fill on the **same** flow node (section, module,
+page flow). It is equivalent to the always-available
+`softPanel(...).stroke(...)` chain; the overload just makes the
+one-node form discoverable. Prefer it over wrapping a filled section in
+an extra bordered panel.
+
+Semantic intent: "this quiet block has a fill and a hairline outline".
+
+### Heading band — headingBar(...) (1.7.0)
+
+A filled, rounded title band with a single label — the common "section
+title on a coloured plaque" — is one call in 1.7.0:
+`headingBar(String)` or `headingBar(String, Consumer<HeadingBarStyle>)`
+on any flow / section / module. `HeadingBarStyle` tunes fill, corner
+radius, padding, margin, label text style, alignment, and an optional
+outline stroke; the default is a light-grey band with a centred bold
+label, so `bar -> bar.fill(brand).textStyle(white)` is usually enough.
+It is sugar over the `softPanel(...).addParagraph(...)` recipe — no new
+node type — added as a child above the body. Reach for it instead of
+hand-building a plaque, and source the fill from a theme token.
+
+Semantic intent: "this region opens with a branded title bar".
+
+## Container fill vs page background
+
+Two different primitives produce a coloured surface, and choosing the
+wrong one is the failure behind every "the fill doesn't reach the
+bottom of the page" bug. Decide this **before** writing the fill.
+
+- **Container fill** — `fillColor(...)` on a flow or section
+  (`pageFlow().fillColor(...)`, `section.fillColor(...)`). The engine
+  paints it over the **laid-out bounds of that container's content**.
+  Correct for a section / panel / card / band that wraps the content it
+  colours. WRONG for "tint the whole page": on content shorter than the
+  page it stops where the content ends and leaves a blank strip down to
+  the page bottom. A tail spacer that tries to "push" the fill to the
+  bottom is the same mistake in disguise — it guesses content height and
+  breaks the moment the data changes.
+- **Page background** — `DocumentSession.pageBackground(color)`, or
+  `DocumentSession.pageBackgrounds(List.of(PageBackgroundFill...))` for
+  multi-column / partial-page fills. The engine splices these in at the
+  bottom of the z-order (z=0) with geometry taken from the **canvas page
+  size**, so they reach all four edges and repeat on every page
+  automatically — independent of how much content the page carries.
+
+**Decision rule:** if the surface must reach a **page edge** (full-page
+tint, edge-to-edge sidebar column, a band that bleeds to top/bottom),
+it is a **page background**. If the surface is bounded by the **content
+it wraps**, it is a **container fill** on the section that owns that
+content.
+
+```java
+// WRONG — container fill on the flow. Stops at content height and
+// leaves a white strip at the page bottom on short pages.
+document.pageFlow(page -> page.fillColor(CREAM)
+        .addSection("Body", this::renderBody));
+
+// RIGHT — page background. Cream reaches the bottom edge regardless of
+// content height; sections (e.g. a navy header) paint on top of it.
+document.pageBackground(CREAM);
+document.pageFlow(page -> page
+        .addSection("Header", this::renderNavyHeader)   // its own fillColor(NAVY)
+        .addSection("Body",   this::renderBody));
+
+// RIGHT — multi-column chrome (pale sidebar + white main) at full
+// height, repeating on every page:
+document.pageBackgrounds(List.of(
+        PageBackgroundFill.leftColumn(0.36, SIDEBAR_FILL),
+        PageBackgroundFill.rightColumn(0.64, MAIN_FILL)));
+```
+
+`PageBackgroundFill` ships factory methods for the common shapes:
+`fullPage`, `leftColumn` / `rightColumn` / `column`, and
+`topBand` / `bottomBand` / `band`. The library's own `SidebarPortrait`
+preset paints its full-height sidebar exactly this way — mirror it
+rather than giving the sidebar section a `fillColor`.
+
+## Panel vs layer-stack overlay
+
+The most common mistake in this area is reaching for a layer stack
+when a panel would do. The distinction is one of role:
+
+- a **panel** is a surface that carries content. The content lives
+  inside it. Pagination, snapshots, and reflow respect the surface
+  because the surface is part of the layout.
+- a **layer-stack overlay** is decoration that sits on top of content
+  the layout already arranged. The overlay does not carry the
+  underlying content; it floats over it (badge, watermark, ornament).
+
+If the surface is the parent of the content, it is a panel. If the
+surface is a child painted on top, it is an overlay.
+
+## Theme tokens
+
+Backgrounds and panels are exactly the kind of surface that must come
+from the theme. See [`themes-and-colors`](themes-and-colors.md) for
+the token vocabulary. Required named tokens for this skill:
+
+- page background colour
+- panel background colour (the quiet fill)
+- card background colour (the louder fill)
+- accent colour for strips
+- band background colour
+
+Hardcoding hex values inside the template for these surfaces is a
+defect — they must come from the theme so revisions can recolour the
+document consistently.
+
+## Common mistakes
+
+1. **Using a container fill to tint the whole page.** This is the
+   headline mistake. `pageFlow().fillColor(...)` (or a `fillColor` on a
+   wrapper section, or a tail spacer that tries to "push" the fill down)
+   is bounded by content height and leaves a blank strip at the page
+   bottom whenever the content is shorter than the page. A full-page
+   tint is `DocumentSession.pageBackground(...)`; a full-height column
+   is `pageBackgrounds(...)`. See
+   [Container fill vs page background](#container-fill-vs-page-background).
+2. **Using a panel where a section background suffices.** If the
+   content is already inside a section, give the section a background
+   colour. Wrapping that section in an additional panel adds layout
+   nesting without semantic meaning and makes diffs harder to read.
+3. **Layering panels when one section background would do.** Two
+   stacked panels with the same content cannot be diffed by a snapshot
+   any better than one section background; they only add nesting.
+4. **Drawing a coloured rectangle on a canvas layer instead of using
+   the page background.** A canvas rectangle is opaque to the layout
+   engine. Pagination, layout snapshots, and visual regression cannot
+   reason about it. Use the page-background primitive.
+5. **Putting an accent strip in a layer stack on top of a header
+   row.** The strip belongs to the header section. Express it through
+   the section's accent, not as a floating overlay.
+6. **Hardcoding panel colours.** Use theme tokens so the colour
+   substitutes cleanly when the brand palette changes.
+
+## Required visual checks
+
+- a full-bleed page tint or full-height column reaches all four page
+  edges — including the **bottom edge on short content** (this requires
+  a page background; a container fill or tail spacer will fail this)
+- the surface starts and ends where the reference's surface starts
+  and ends (no half-bleed, no cut corners)
+- the surface respects page margins unless the reference clearly
+  bleeds edge-to-edge
+- the content sits inside the surface, not behind or over it
+- pagination still draws the surface correctly on every page it
+  appears on (cross-check [`pagination`](pagination.md))
+- the surface colour comes from the theme
+
+## Known limitations
+
+- Exact colour reproduction depends on the renderer. Document
+  substitutions in `visual-review.md` and tag them
+  `ACCEPTED_LIMITATION` per
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md).
+- Texture or gradient fills are not described by this skill. If the
+  reference uses a gradient, treat it as a known limitation until a
+  later skill version adds explicit gradient handling.
+
+## Cross-references
+
+- [`themes-and-colors`](themes-and-colors.md) — token vocabulary
+- [`layer-stacks-and-overlays`](layer-stacks-and-overlays.md) — when
+  the surface is decoration on top, not a panel
+- [`shapes-and-containers`](shapes-and-containers.md) — rounded cards,
+  clipped surfaces
+- [`spacing-and-alignment`](spacing-and-alignment.md) — how padding
+  inside panels relates to outer spacing
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  — mismatch classification for documented substitutions
diff --git a/skills/versions/graphcompose-1.7/graphcompose-basics.md b/skills/versions/graphcompose-1.7/graphcompose-basics.md
new file mode 100644
index 0000000..5235512
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/graphcompose-basics.md
@@ -0,0 +1,205 @@
+---
+skillId: graphcompose-basics
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# GraphCompose Basics Skill
+
+GraphCompose is a semantic Java document layout engine.
+
+The agent must understand that GraphCompose templates describe document intent, not PDF coordinates.
+
+Use:
+
+- DocumentSession for document composition
+- pageFlow for page content
+- rows for horizontal structure
+- sections for grouped content
+- tables for tabular data
+- themes for consistent styling
+- layer stacks for overlays
+- shape containers for visual containers
+- layout snapshots for testing
+- visual regression for rendered output comparison
+
+Do not use:
+
+- direct PDFBox imports
+- raw coordinates as the main layout strategy
+- one huge compose method
+- duplicated visual code
+- hardcoded magic values everywhere
+
+## When to load this skill
+
+Always. This skill is the foundation of every other skill in the
+pack. Load it before any other skill so that the agent shares the
+vocabulary the rest of the pack relies on: `DocumentSession`,
+`pageFlow`, the row primitive, the section primitive, the table
+primitive, themes, layer stacks, shape containers, layout snapshots,
+and visual regression.
+
+Loading order recommendation when the orchestrator pulls in the pack:
+
+1. `graphcompose-basics` (this file) — the shared vocabulary
+2. [`visual-to-graphcompose-mapping`](visual-to-graphcompose-mapping.md)
+   when a reference image is involved
+3. The specific primitive skill that matches the work
+   ([`layout-primitives`](layout-primitives.md),
+   [`tables`](tables.md), [`themes-and-colors`](themes-and-colors.md),
+   [`typography`](typography.md),
+   [`spacing-and-alignment`](spacing-and-alignment.md))
+4. The cross-cutting skills shipped by the parallel lane
+   (`pagination`, `backgrounds-and-panels`, `layer-stacks-and-overlays`,
+   `shapes-and-containers`, `visual-regression`,
+   `revision-discipline`, `troubleshooting`)
+
+## Core mental model
+
+GraphCompose templates declare a document, not pixels. A template is
+written once and rendered against many data inputs. The agent must
+treat the DSL as a description of semantic structure:
+
+- a document is a `DocumentSession`
+- pages are composed through `pageFlow`
+- horizontal arrangements are rows
+- semantically grouped blocks are sections
+- structured row and column data is a table
+- repeated styling is centralized through a theme
+- overlapping content is a layer stack
+- decorative containers are shape containers
+- pure decoration of last resort is a canvas layer
+
+If a visual element cannot be cleanly expressed with the above, the
+agent must document the gap rather than invent new primitives. See
+the no-invented-API rule in
+[`../../../docs/versioned-skills.md`](../../../docs/versioned-skills.md).
+
+## Why not direct PDFBox
+
+Direct PDFBox usage in a template defeats the purpose of using
+GraphCompose: it ties the template to coordinate-level code, breaks
+the semantic mapping the rest of the pack depends on, and prevents
+the visual-regression and revision tooling from understanding the
+template's structure. Use GraphCompose primitives instead.
+
+## Componentization is part of the contract
+
+Templates must be composed of small private render methods, one per
+semantic block. This is not a style preference. The
+[revision model](../../../docs/visual-accuracy-contract.md) and
+the selective rollback rules in `revision-discipline.md` rely on the
+ability to swap one component (for example `renderHeader`) from a
+previous revision while keeping another (for example
+`renderLineItems`) from the current draft. A monolithic compose
+method makes selective rollback unreliable.
+
+## Authoritative API reference
+
+When a skill page does not document the exact method signature, the
+agent MUST consult the hosted Javadoc, NOT guess and NOT grep
+unverified sources:
+
+- **Maven Central Javadoc (canonical):**
+  [javadoc.io/doc/io.github.demchaav/graph-compose/1.7.0](https://javadoc.io/doc/io.github.demchaav/graph-compose/1.7.0)
+- **Stable-version alias** (always points at the latest published
+  release): [javadoc.io/doc/io.github.demchaav/graph-compose](https://javadoc.io/doc/io.github.demchaav/graph-compose)
+
+Lookup priorities, in order:
+
+1. The relevant skill page for the resolved target version.
+2. The hosted Javadoc at the version pinned in the skill manifest's
+   `verifiedAgainst` (currently 1.7.0).
+3. A fixture project under [`examples/skill-fixtures/`](../../../examples/skill-fixtures/)
+   that uses the API in question (proves it actually resolves).
+4. Only after all three above fail, ask the user — do not invent.
+
+Class-level `@since` tags landed in 1.6.6 on every entry-point type
+(`DocumentSession`, `DocumentDsl`, `BusinessTheme`, the 19 DSL
+builders, `PageBackgroundFill`, `RichText`, `Transformable`), so the
+hosted Javadoc shows the introduction version at a glance. Types
+marked `@Beta` (e.g. `NodeDefinition` — the custom-node SPI) are
+Extension SPI: callers MAY implement them, but the shape may evolve
+between minors. Treat `@Beta` signatures as load-bearing only after
+cross-checking against the current pinned version.
+
+The additive 1.7.0 primitives carry their own `@since 1.7.0` tags
+(`InlineShapeRun`, `ShapeLayer`, `TextVerticalAlign`,
+`DocumentDashPattern`, the timeline DSL, `FontName.JETBRAINS_MONO`, the
+`headingBar(...)` / per-corner `roundedRect(...)` overloads), so the
+hosted Javadoc shows them as 1.7.0 introductions — see "New in 1.7.0"
+below.
+
+## New in 1.7.0 — additive DSL primitives
+
+GraphCompose 1.7.0 is additive over 1.6.x (zero breaking changes): it
+adds public API but removes none, so every 1.6.x mapping in this pack
+still holds. Each new primitive is worth reaching for because it
+replaces a workaround the older packs had to describe. Load the topic
+skill named in brackets for the usage rules.
+
+- **Inline shape runs** — geometry-drawn dots, diamonds, stars,
+  arrows, chevrons, and checkboxes that ride the text baseline
+  (`InlineShapeRun`, authored via `ParagraphBuilder` / `RichText`
+  `dot(...)`, `diamond(...)`, `star(...)`, `arrow(...)`, `chevron(...)`,
+  `checkbox(...)`, `shape(ShapeOutline, ...)`). Skill-rating dots
+  (`●●●●○`), custom bullets, and inline status markers no longer depend
+  on a font shipping the glyph. [`typography`](typography.md),
+  [`shapes-and-containers`](shapes-and-containers.md)
+- **Polygon shape geometry** — `ShapeOutline` gains a `Polygon` kind
+  and factories (`diamond`, `triangle`, `star`, `arrow`, `chevron`,
+  `checkmark`, `plus`, `regularPolygon(sides)`), usable block-level and
+  inline. [`shapes-and-containers`](shapes-and-containers.md)
+- **Per-corner rounded rectangles** — `roundedRect(w, h,
+  DocumentCornerRadius)` rounds each corner independently (no more
+  CLIP_PATH-parent workaround).
+  [`shapes-and-containers`](shapes-and-containers.md)
+- **Vertical text alignment** — `ParagraphBuilder.verticalAlign(
+  TextVerticalAlign)` seats a single line (TOP / CENTER / BOTTOM) in a
+  taller box. [`spacing-and-alignment`](spacing-and-alignment.md),
+  [`typography`](typography.md)
+- **Semantic timelines** — `addTimeline(...)` lays out a marker-and-
+  content rail (work history, milestones, process steps).
+  [`layout-primitives`](layout-primitives.md)
+- **Dashed / dotted lines** — `LineBuilder.dashed(...)` for dividers,
+  connectors, cut-here rules.
+  [`layout-primitives`](layout-primitives.md)
+- **`headingBar(...)`** — a one-call filled, rounded title band.
+  [`backgrounds-and-panels`](backgrounds-and-panels.md),
+  [`layout-primitives`](layout-primitives.md)
+- **`softPanel(..., stroke)`** — rounded fill + outline on one flow
+  node. [`backgrounds-and-panels`](backgrounds-and-panels.md)
+- **`FontName.JETBRAINS_MONO`** — bundled monospaced family.
+  [`typography`](typography.md)
+- **`DocumentSession.availableHeight()`** — usable page content height
+  (page minus top/bottom margins). [`pagination`](pagination.md)
+- **Fix:** `position(node, dx, dy, align)` offsets are now honored for
+  stacks nested inside a fixed slot.
+  [`layer-stacks-and-overlays`](layer-stacks-and-overlays.md)
+
+These are documented in the GraphCompose 1.7.0 changelog; cross-check
+exact method overloads against the 1.7.0 Javadoc before relying on a
+specific signature, per the lookup priority above.
+
+## Known limitations
+
+This skill describes the 1.7.x semantics conceptually. It does not
+list the exact method signatures of every builder. Specific method
+signatures must be cross-checked against the
+[`verifiedAgainst: 1.7.0`](../../../docs/versioned-skills.md) examples
+once the Phase 4 fixtures land. Until then, when uncertain, the
+agent must:
+
+- prefer documented primitives over guessed methods
+- describe the intended behavior in `architecture-plan.md`
+- mark uncertain mappings as risks in `visual-review.md`
+- fall back to conservative templates rather than invent API
+
+See the no-invented-API rule in
+[`../../../docs/versioned-skills.md`](../../../docs/versioned-skills.md)
+and the skill drift handling in
+[`../../../docs/skill-validation.md`](../../../docs/skill-validation.md).
diff --git a/skills/versions/graphcompose-1.7/layer-stacks-and-overlays.md b/skills/versions/graphcompose-1.7/layer-stacks-and-overlays.md
new file mode 100644
index 0000000..cbc66a7
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/layer-stacks-and-overlays.md
@@ -0,0 +1,242 @@
+---
+skillId: layer-stacks-and-overlays
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Layer Stacks and Overlays Skill
+
+Use this skill when the visual reference has elements that genuinely
+overlap: a badge sitting half-on, half-off a card; a watermark
+behind body text; a decorative shape that crosses a panel boundary; a
+label that breaks out of the row it labels. These are layer-stack
+problems. They are not panel problems and they are not spacing
+problems.
+
+## When to load
+
+Load this skill whenever the
+[`visual-to-graphcompose-mapping`](visual-to-graphcompose-mapping.md)
+analysis lists overlap. Concretely:
+
+- a badge whose edge crosses the edge of a card or row
+- a watermark drawn behind body content
+- a decorative shape that visually sits in front of or behind a
+  panel
+- a label or callout that intentionally breaks out of its parent
+- a stamp ("PAID", "DRAFT") drawn over content
+
+If the surface carries the content rather than floating over it,
+switch to [`backgrounds-and-panels`](backgrounds-and-panels.md). If
+the visual is in the same plane as the content and you just need more
+space, use [`spacing-and-alignment`](spacing-and-alignment.md) instead
+— overlays are not a spacing tool.
+
+## Genuine overlap vs faked spacing
+
+A layer stack is the right tool only when the elements truly need to
+share a region of the page. Two heuristics:
+
+1. **Could the reference be reproduced by giving the underlying
+   element more padding or a different alignment?** If yes, do that.
+   It is not an overlap; the layer stack would be a hack.
+2. **Does removing the overlapping element change the meaning?** A
+   real badge ("NEW", a stamp, an order number) changes the meaning
+   of the card. A fake "overlay" used to nudge a row into place does
+   not.
+
+If both checks point at "no real overlap", do not use a layer stack.
+The layer stack adds rendering complexity, makes diffs noisier, and
+hides intent from the visual-regression workflow.
+
+## Z-index discipline
+
+Layer order matters and must be deliberate:
+
+- the layer at the bottom of the stack is the document content
+- decorative overlays go above content unless they are watermarks
+- watermarks go below content so text remains legible
+- badges go on top of the card or row they belong to
+- nothing in the stack should depend on the renderer drawing layers
+  in a non-deterministic order
+
+Document the intended layer order in `architecture-plan.md` whenever
+more than two layers are present. The Visual Review Agent uses that
+plan as ground truth when classifying overlay mismatches.
+
+## Per-layer offsets with position(...) (1.7.0 fix)
+
+A badge or cap placed with `position(node, dx, dy, align)` is anchored
+by `align` and then nudged by the `(dx, dy)` offset. Before 1.7.0 those
+offsets were silently dropped when the `LayerStack` / `ShapeContainer`
+was nested inside a fixed slot — a row column or another layer — so a
+positioned badge could not be moved off its anchor once nested, even
+though the same call worked at the document root. 1.7.0 fixes this: the
+nested path now feeds the same offsets as the root path, so
+`position(badge, -6, 5, LayerAlign.TOP_RIGHT)` nudges identically
+whether the stack is at the root or nested in a row cell.
+
+Implications for this workflow:
+
+- Target 1.7.0 (this pack's version) before relying on a nudged badge
+  inside a nested stack. On 1.6.x the offset is ignored and the badge
+  sits exactly on its anchor — if a template must run on 1.6.x, anchor
+  the badge with `align` alone and accept the on-anchor position.
+- Layouts that did not use `position(...)` inside a nested stack are
+  unchanged; this is a fix, not a layout shift.
+- Prefer `align` + a small `(dx, dy)` offset over a hand-computed
+  absolute position, per the anchors-over-offsets principle.
+
+## Typical overlay shapes
+
+### Badge on a card
+
+A small pill or square that hangs partly off the corner of a card.
+Compose it as a layer stack rooted on the card. The card is the lower
+layer; the badge is the upper layer. Both are real layout objects;
+neither is a coordinate-drawn ornament.
+
+### Watermark
+
+A faded brand element drawn behind body content. The watermark layer
+sits below the content layer in the stack. The watermark must not
+participate in pagination calculations; it is purely decorative.
+
+### Decoration crossing a panel boundary
+
+A shape that visibly straddles two regions — for example a tab that
+sticks out of a panel top edge. The panel is the lower layer; the
+shape is the upper layer. Do not split the shape into two clipped
+halves; that is a coordinate hack.
+
+### Stamp over content
+
+A semi-transparent stamp ("PAID", "DRAFT", "VOID") drawn over a
+finished page. The stamp is the topmost layer; it sits over every
+other layer on the page.
+
+## Bad vs good
+
+### Good: badge on a card
+
+```text
+LayerStack rooted on the "InvoiceCard" section.
+
+  Layer 1 (bottom): the card content (title, lines, totals).
+  Layer 2 (top):    the "NEW" badge clipped to the card's top-right
+                    corner.
+
+Reason: the badge is a real, semantic element that overlaps the
+card. It changes the meaning of the card and is referenced in the
+visual analysis.
+```
+
+### Bad: fake spacing between two rows
+
+```text
+LayerStack with two rows positioned so that one is drawn slightly
+over the other to "create breathing room".
+
+Reason this is wrong: there is no genuine overlap. The two rows
+are independent content. Using a layer stack here:
+
+  - hides intent from the layout engine,
+  - breaks pagination across the rows,
+  - makes the layout snapshot misleading,
+  - prevents selective rollback of either row.
+
+Correct fix: arrange the rows in their parent container and adjust
+the spacing primitive between them. See
+spacing-and-alignment.md.
+```
+
+### Bad: layered panels to fake a card border
+
+```text
+LayerStack with a coloured panel below and a slightly smaller
+white panel above to simulate a border.
+
+Reason this is wrong: a border is not an overlap, and the
+GraphCompose section primitive supports borders directly. The
+layer stack adds two real layout objects where one suffices.
+
+Correct fix: use the section's border on a single panel. See
+backgrounds-and-panels.md.
+```
+
+## Avoiding fake-spacing hacks
+
+The layer stack is the easiest primitive to abuse. Two specific
+patterns are forbidden in templates produced under this workflow:
+
+1. **Negative-margin emulation.** Stacking two content blocks to
+   make them visually overlap when the layout intent is "they should
+   be closer". Use spacing, not stacking.
+2. **Pseudo-borders.** Stacking two panels of different sizes to
+   imitate a border. Use the section border primitive.
+
+Both patterns hide intent and silently break the rollback model.
+
+## Required visual checks
+
+- the overlap matches the reference: same anchor, same direction,
+  similar protrusion
+- nothing on the upper layer obscures critical text the reference
+  leaves visible
+- the layer order matches what `architecture-plan.md` describes
+- pagination across pages preserves the overlay only where the
+  reference repeats it
+- the visual snapshot still passes after introducing the layer stack
+
+## Custom node types are an @Beta SPI (1.6.6)
+
+When the overlay genuinely cannot be expressed with `LayerStack`,
+`ShapeContainer`, `Section`, or the table/row primitives, the engine
+exposes `com.demcha.compose.document.layout.NodeDefinition` as the
+canonical custom-node-type seam. As of GraphCompose 1.6.6 this seam
+is explicitly marked `@Beta` — it is an **Extension SPI**:
+
+- Callers MAY implement `NodeDefinition` for legitimately novel
+  visuals that no documented primitive covers.
+- The shape of `NodeDefinition` (its method set, the
+  `emitOverlayFragments` contract, helper types it returns) MAY
+  evolve between minor releases (e.g. 1.7.0). Patch releases keep it
+  source-compatible; minors are allowed to break it with one minor
+  of `@Deprecated` warning.
+- Treat any `NodeDefinition`-based overlay as a known maintenance
+  cost. Record it as a `Known Limitation` in `architecture-plan.md`,
+  not as a routine primitive.
+- Before reaching for `NodeDefinition`, exhaust the documented
+  alternatives. The decision order is: documented primitive →
+  `LayerStack` → `ShapeContainer` (with `center`/`position`) →
+  `CanvasLayer` for tiny decorative ornaments → `NodeDefinition`
+  (last resort, `@Beta`).
+
+The `@Beta` marker also implies: do NOT pin downstream tooling
+(visual-diff classifiers, parity-score formulas) to the exact
+`NodeDefinition` shape. Pin to the rendered output instead.
+
+## Known limitations
+
+- Transparency, blending, and shadow rendering may differ between
+  renderers. Tag those differences `ACCEPTED_LIMITATION` per
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md).
+- Very dense stacks (more than three meaningful layers) tend to be
+  hard to diff. If the reference seems to demand one, list it as a
+  visual risk in `architecture-plan.md`.
+
+## Cross-references
+
+- [`shapes-and-containers`](shapes-and-containers.md) — when the
+  overlay is shape-based
+- [`backgrounds-and-panels`](backgrounds-and-panels.md) — when the
+  surface should carry content, not float over it
+- [`layout-primitives`](layout-primitives.md) — the row, section,
+  and table primitives that form the content layer
+- [`spacing-and-alignment`](spacing-and-alignment.md) — the correct
+  tool for "more breathing room"
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  — overlay-specific mismatch classification
diff --git a/skills/versions/graphcompose-1.7/layout-primitives.md b/skills/versions/graphcompose-1.7/layout-primitives.md
new file mode 100644
index 0000000..440241e
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/layout-primitives.md
@@ -0,0 +1,211 @@
+---
+skillId: layout-primitives
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Layout Primitives Skill
+
+Use this skill when deciding which GraphCompose layout primitive to use.
+
+## Row
+
+Use RowBuilder when elements are arranged horizontally.
+
+Examples:
+- logo + company information
+- billing address + invoice metadata
+- two-column summary
+- icon + text
+
+## Section
+
+Use SectionBuilder when content belongs to one semantic block.
+
+Examples:
+- hero block
+- payment instructions
+- notes
+- footer message
+- warning box
+
+## Table
+
+Use TableBuilder when content is structured into rows and columns.
+
+Examples:
+- invoice line items
+- pricing table
+- schedule
+- comparison table
+
+## Layer stack
+
+Use LayerStack when elements overlap visually.
+
+Examples:
+- badge over card
+- watermark behind content
+- decorative shape behind header
+- label crossing a panel border
+
+## Shape container
+
+Use shape containers when the reference uses strong visual shapes.
+
+Examples:
+- rounded card
+- circle avatar placeholder
+- pill badge
+- clipped image area
+- ellipse/circle highlight
+
+## Canvas layer
+
+Use CanvasLayer only when semantic primitives are not enough.
+
+CanvasLayer is allowed for:
+- tiny decorative details
+- exact background geometry
+- non-semantic ornaments
+- visual marks that do not affect document structure
+
+CanvasLayer must not become coordinate soup.
+
+## Semantic timelines (1.7.0)
+
+When the reference shows a vertical sequence where each entry pairs a
+marker with content along a continuous rail — work history, project
+milestones, numbered process steps — use the timeline primitive rather
+than hand-placing bullets with margins. `addTimeline(timeline -> ...)`
+is available on every flow, section, and module, with `TimelineBuilder`,
+`TimelineMarker`, and `TimelineEntryBuilder`
+(`com.demcha.compose.document.dsl`):
+
+```text
+section.addTimeline(tl -> tl
+    .entry(TimelineMarker.numbered(1), e -> e
+        .title("Senior Engineer")
+        .meta("2021 - present")
+        .body("Led the platform rewrite ..."))
+    .entry(TimelineMarker.numbered(2), e -> e
+        .title("Engineer")
+        .meta("2018 - 2021")
+        .body("...")));
+```
+
+Markers are `TimelineMarker.dot`, `circle`, `numbered`, or `square`.
+The rail colour/width, gutter, entry spacing, and default title / meta
+/ body styles are all tunable on the builder. Declaring the
+marker-to-content relationship replaces the hand-placed
+bullet-plus-margin pattern; the timeline paginates between entries and
+a tall entry splits within itself, the rail continuing across the page
+break (see [`pagination`](pagination.md)). Cross-check exact builder
+signatures against the 1.7.0 Javadoc.
+
+## Dividers and dashed lines (1.7.0)
+
+A `line(...)` is solid by default. For section or résumé dividers,
+timeline connectors, or cut-here rules, `LineBuilder.dashed(double...
+pattern)` / `dashed()` / `dashed(DocumentDashPattern)` paint an on/off
+dash. The pattern alternates paint-on and paint-off lengths in points:
+`dashed(8, 5)` is a long dash, `dashed()` is a balanced 3pt-on /
+2pt-off, and `dashed(1, 4)` reads as a dotted rule. The dash is carried
+on the line independently of `DocumentStroke`; the PDF backend honours
+it and other backends fall back to a solid stroke.
+
+## Heading bands — headingBar(...) (1.7.0)
+
+`headingBar(String)` and `headingBar(String, Consumer<HeadingBarStyle>)`
+(on `AbstractFlowBuilder`, so every flow / section / module) add a
+filled, rounded heading band with a single label above the body in one
+call — the discoverable form of the `softPanel(...).addParagraph(...)`
+recipe. `HeadingBarStyle` tunes fill, corner radius, padding, margin,
+label text style, alignment, and an optional outline stroke, each with
+a sensible default (a light-grey band with a centred bold label). See
+[`backgrounds-and-panels`](backgrounds-and-panels.md) for when a band
+is the right surface, and tokenise the fill through the theme.
+
+## Vertical budget — availableHeight() (1.7.0)
+
+`DocumentSession.availableHeight()` returns the usable page content
+height (page height minus top and bottom margins) — the value a
+composition reads to decide how much vertical room a section, sidebar,
+or spacer may fill. It is a one-call alias for `canvas().innerHeight()`.
+Derive vertical sizing from it relationally instead of hardcoding a
+page height (see [`pagination`](pagination.md)).
+
+## When to load
+
+Load this skill whenever the Architecture Mapper Agent or the
+Template Coder Agent has to choose between two or more primitives
+for the same visual region. It pairs with
+[`visual-to-graphcompose-mapping`](visual-to-graphcompose-mapping.md):
+the mapping skill decides which primitive *family* applies to a
+region, and this skill explains the differences between the
+primitives inside that family.
+
+It is also the first skill to load when an existing template is
+being refactored — for example, when a long canvas-heavy block needs
+to be promoted into proper rows, sections, or tables before further
+revisions can land safely.
+
+## Decision flow
+
+Use the following decision chain when classifying a region. Stop at
+the first matching branch.
+
+```text
+Is the content tabular (shared column meaning across rows)?
+  -> the table primitive (see tables.md)
+
+Else, is the region a vertical sequence of marker-and-content entries
+on a shared rail (work history, milestones, numbered steps)?
+  -> a timeline (1.7.0; see "Semantic timelines" below)
+
+Else, is the region a horizontal arrangement of unrelated items?
+  -> the row primitive
+
+Else, is the region a semantically grouped block of related content?
+  -> the section primitive
+
+Else, do elements overlap visually (badge over card, watermark)?
+  -> a layer stack (see layer-stacks-and-overlays.md)
+
+Else, is the region a strong visual shape (rounded card, pill, circle)?
+  -> a shape container (see shapes-and-containers.md)
+
+Else, is the element pure decoration that the DSL cannot express?
+  -> the canvas layer, last resort, kept small and documented
+```
+
+If two branches feel equally valid, prefer the higher-level
+primitive in the chain. A table beats a stack of rows. A section
+beats a single-cell row. A layer stack beats a canvas layer for
+overlaps. Promoting a region one level up the chain almost always
+improves maintainability and selective rollback safety.
+
+## Componentization expectation
+
+Whichever primitive is chosen, the implementation must live in a
+small private render method named after the region:
+`renderHeader`, `renderHero`, `renderLineItems`, `renderFooter`,
+`renderBadge`, and so on. The componentization rule comes from
+[`graphcompose-basics`](graphcompose-basics.md) and is required by
+the selective rollback semantics documented in the parallel-lane
+`revision-discipline.md`.
+
+## Cross-references
+
+- [`tables`](tables.md) for the table primitive decision in depth
+- [`themes-and-colors`](themes-and-colors.md) for the styling tokens
+  that the primitives consume
+- [`typography`](typography.md) for the font hierarchy applied
+  inside each primitive
+- [`spacing-and-alignment`](spacing-and-alignment.md) for the gaps
+  between primitives and the padding inside them
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  for the parity rules that constrain primitive choices
diff --git a/skills/versions/graphcompose-1.7/pagination.md b/skills/versions/graphcompose-1.7/pagination.md
new file mode 100644
index 0000000..f1827f8
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/pagination.md
@@ -0,0 +1,224 @@
+---
+skillId: pagination
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Pagination Skill
+
+Use this skill when the document is expected to span more than one
+page, when a table can overflow into another page, when headers and
+footers must reappear on every page, or when certain blocks must not
+be split mid-content. Pagination is owned by GraphCompose's page-flow
+primitive — templates declare intent, the engine performs the breaks.
+
+## When to load
+
+Load this skill whenever any of the following is true for the
+reference:
+
+- the reference is multi-page or the data set is expected to produce
+  more than one page at render time
+- the reference contains a table whose row count is data-driven and
+  could grow beyond a single page
+- the reference shows the same header or footer on every page
+- the reference shows a block (a totals card, a signed agreement
+  panel) that should never split across pages
+- the analyser flagged "pagination" as a visual risk in
+  `visual-analysis.md`
+
+If the reference is strictly single-page and the data is bounded,
+load only [`layout-primitives`](layout-primitives.md) and skip this
+skill.
+
+## Core rule: let pageFlow handle page breaks
+
+```text
+Do not insert manual page breaks when the page-flow primitive can
+compute them.
+```
+
+GraphCompose's page-flow primitive is the page-break authority.
+Templates compose content into a flow and let the engine decide where
+pages end. Manually computing page positions is a coordinate-soup
+pattern and a defect under this workflow.
+
+Manual page breaks may be acceptable in two narrow situations only:
+
+1. The reference itself shows a forced break (for example "Terms and
+   Conditions start on a new page") that is part of the document
+   semantics, not the rendering. Express the intent explicitly, not as
+   a coordinate hack.
+2. A specific atomic block must start on a new page for legal or
+   structural reasons. Same rule: express the intent.
+
+Otherwise the engine handles breaks.
+
+## Tables across pages
+
+A table that overflows must:
+
+- repeat its header on every page it appears on
+- preserve column proportions across pages
+- not produce a single-row fragment on the last page when the row is
+  visually part of the block above it
+- preserve any zebra-row colouring rhythm if the reference uses it
+
+See [`tables`](tables.md) for the table-builder rules; this skill
+covers only the pagination contract.
+
+### Repeated table headers
+
+Repeated headers are not "the header is duplicated". They are the
+table header reappearing at the top of every page the table reaches.
+The template declares the intent on the table primitive; the engine
+draws the header on every continuation page.
+
+A reference that shows the table header only on page 1 is unusual; in
+that case the template must explicitly suppress repetition rather
+than relying on rendering accident.
+
+### Avoiding orphan rows
+
+A one-row fragment on the last page (one line of the table, marooned
+on its own page) is a `MAJOR` mismatch under
+[`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md).
+Mark the totals row or footer row as atomic with the preceding rows
+when the reference reads them as one block. See atomic blocks below.
+
+## Atomic blocks that must never split
+
+Some blocks lose meaning when split:
+
+- a totals card that summarises the table above it
+- a signed agreement panel (signature line + name + date)
+- a hero card that must appear whole
+- a coloured panel whose surface visually anchors its content
+
+Declare these blocks atomic. The page-flow primitive treats atomic
+blocks as a unit: if the block does not fit on the current page, the
+engine moves the whole block to the next page rather than splitting
+it.
+
+Do not declare entire sections atomic just to avoid thinking about
+page flow — that produces giant ragged page bottoms. Atomicity is for
+blocks whose meaning depends on visual cohesion.
+
+## Timelines across pages (1.7.0)
+
+The 1.7.0 timeline primitive (`addTimeline(...)`, see
+[`layout-primitives`](layout-primitives.md)) is paginated, not atomic.
+The engine breaks between entries, and a single tall entry splits
+within itself with the connector rail continuing across the page break.
+A long work-history or milestone timeline is therefore allowed to flow
+onto the next page — do NOT declare the whole timeline atomic to keep
+it together (that reproduces the giant-ragged-bottom mistake above).
+Declare only an individual entry atomic if its marker and content must
+never separate. Verify, on every continuation page, that the rail
+resumes at the top and the marker-to-content alignment holds.
+
+## Vertical budgeting — availableHeight() (1.7.0)
+
+When a composition needs to know how much vertical room a page offers —
+to size a sidebar to full height, to decide whether a block fits, or to
+split content deliberately — read `DocumentSession.availableHeight()`
+(the usable content height: page height minus top and bottom margins, a
+one-call alias for `canvas().innerHeight()`). Derive vertical sizing
+from it relationally instead of hardcoding a page height; a hardcoded
+height breaks the moment the page size or margins change, exactly like
+the tail-spacer anti-pattern in
+[`backgrounds-and-panels`](backgrounds-and-panels.md).
+
+## Headers and footers across pages
+
+The header and footer of a paginated document are not normal content
+rows. They reappear on every page through the page-flow primitive's
+header and footer slots, not by being duplicated in the body.
+
+Required behaviour:
+
+- the header reappears on every page at the same vertical position
+- the footer reappears on every page at the same vertical position
+- page numbers, if shown, advance correctly
+- the surface (background or panel) of the header and footer
+  reappears as well, not just the text content
+
+If the reference shows a different header on page 1 (a hero header
+that only appears once), express that as a page-1-only header
+override, not as a manual page break.
+
+## Manual page breaks
+
+A manual page break is acceptable when the reference itself shows the
+break as part of the document's structure, not the rendering — for
+example "Terms and Conditions begin on a new page". Express it as an
+explicit break in the page flow, not as a position computed from
+coordinates. The break belongs to the document semantics.
+
+## Required visual checks across pages
+
+Every multi-page revision must verify, on every page:
+
+- the header reappears in the same position and at the same size
+- the footer reappears in the same position and at the same size
+- the table header reappears whenever the table continues on this
+  page
+- there is no orphan one-row fragment from the previous page's
+  content
+- no section title is chopped at the bottom of a page (the title
+  must stay attached to its content)
+- no atomic block is split across pages
+- page numbers, if present, are correct on every page
+- backgrounds and panels declared as page-wide redraw on every page
+  the reference draws them on (see
+  [`backgrounds-and-panels`](backgrounds-and-panels.md))
+
+The Visual Review Agent must walk through these checks page by page,
+not only on page 1.
+
+## Pagination snapshot expectations
+
+When the Test + Render Agent produces `layout-snapshot.json`, the
+snapshot includes per-page boundaries. Pagination changes must be
+visible in the snapshot diff between revisions; a "darker totals row"
+revision should not produce a different page break unless that change
+was intended.
+
+## Common mistakes
+
+1. **Computing the page height manually and inserting a break at a
+   fixed y-coordinate.** Always wrong under this workflow. Use the
+   page-flow primitive.
+2. **Forgetting to declare repeated table headers.** Default
+   behaviour varies; declare the intent explicitly.
+3. **Declaring an entire section atomic.** Atomicity is for blocks
+   whose meaning depends on visual cohesion, not for spilling-prone
+   sections.
+4. **Duplicating header content in the body** so it "reappears" on
+   page 2. The header slot exists; use it.
+5. **Treating an orphan totals row as acceptable** because "it's only
+   one row". One marooned row is a `MAJOR` mismatch.
+
+## Known limitations
+
+- Differences in font metrics between renderers can shift the page
+  break by a row or two. Document those as `MINOR` mismatches.
+- Atomicity is local: a block declared atomic is treated as a unit on
+  its own page, but the engine cannot infer atomicity across more
+  than one block. Declare each atomic block explicitly.
+
+## Cross-references
+
+- [`tables`](tables.md) — table-builder rules; this skill only covers
+  the pagination contract
+- [`visual-regression`](visual-regression.md) — diffing rendered
+  pages across revisions
+- [`layout-primitives`](layout-primitives.md) — the row, section, and
+  table primitives that compose the page flow
+- [`backgrounds-and-panels`](backgrounds-and-panels.md) — page-wide
+  surfaces that must redraw on every page
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  — classification of pagination defects
diff --git a/skills/versions/graphcompose-1.7/revision-discipline.md b/skills/versions/graphcompose-1.7/revision-discipline.md
new file mode 100644
index 0000000..0f8f053
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/revision-discipline.md
@@ -0,0 +1,197 @@
+---
+skillId: revision-discipline
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Revision Discipline Skill
+
+Use this skill whenever a change to a template is proposed: a first
+generation, a "make it darker" tweak, an approval, a rejection, an
+undo, a revert, or a selective rollback. Revision discipline is the
+safety layer that keeps the workflow auditable and every change
+reversible.
+
+## When to load
+
+Load this skill on every change. There is no situation in which
+revision discipline is optional. The Revision Manager Agent owns the
+full machinery; this skill is the contract the rest of the pipeline
+follows when it interacts with revisions.
+
+## Core rule
+
+Quoted verbatim from §5.9 of the project plan:
+
+```text
+Never overwrite the approved revision directly.
+Every change creates a new revision.
+```
+
+This rule is non-negotiable. Even a one-line edit to a render method
+produces a fresh `revision-N` folder; the previous revision keeps its
+artifacts intact. The cost is folder count. The benefit is that
+every step is reversible and the rollback flows in
+[`../../../docs/rollback.md`](../../../docs/rollback.md) become mechanical
+rather than guesswork.
+
+## What "creates a revision" means
+
+Every change produces:
+
+- a new `revisions/revision-N/` folder
+- a fresh `revision.json` with a unique `id`, the correct
+  `parentRevisionId`, an initial `status` of `DRAFT`, the
+  `userRequest`, the `targetGraphComposeVersion`, the `skillPack`,
+  and the list of `changedComponents`
+- a fresh copy of any artifact that is produced for this revision
+  (template, test, patch diff, layout snapshot, PDF, preview image,
+  visual review, test result, status note)
+- a `parentRevisionId` that always points at the revision the new
+  draft was derived from
+
+The artifact inventory and revision-metadata shape live in
+[`../../../docs/revision-model.md`](../../../docs/revision-model.md). The
+skill defers to that page for the exact JSON.
+
+## No destructive overwrite of approved revisions
+
+The `currentApprovedRevisionId` in `template-project.json` is the
+source of truth. Tooling and agents must treat the approved revision
+folder as read-only. The only way to "change" an approved revision is
+to:
+
+1. create a new revision derived from it
+2. modify the new revision
+3. obtain user approval
+4. flip the approved pointer to the new revision
+
+The old approved revision keeps its files. It transitions to
+`SUPERSEDED` in its own `revision.json`, not in the new one.
+
+## Failed revisions are preserved
+
+A revision that fails — compile failure, render failure, visual
+review failure — does not vanish. Its folder stays on disk with
+every artifact that was produced before the failure:
+
+- compilation failure: `build.log` and the partial
+  `generated-template.java` remain
+- render failure: `render.log` and the upstream artifacts remain;
+  `output.pdf` may be missing
+- visual review failure: `output.pdf`, `output.png`, and
+  `visual-review.md` all remain
+
+The revision's `status` is flipped to `FAILED` in its own
+`revision.json`. The next revision is created from the previous good
+draft (or the approved revision), never by editing the failed folder
+in place. See
+[`../../../docs/revision-model.md`](../../../docs/revision-model.md) for
+the failure handling rules.
+
+## Approval rules
+
+Approval flips a `DRAFT` revision to `APPROVED` and updates
+`currentApprovedRevisionId` in `template-project.json`. Approval is
+permitted only when the revision satisfies every condition in
+[`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md):
+
+- no critical mismatches remain
+- no major mismatches remain unless explicitly accepted
+- minor mismatches are documented
+- all generated artifacts exist
+- code compiles
+- PDF renders
+- preview image exists
+- `visual-review.md` is written
+- revision metadata is complete
+
+The Visual Review Agent's approval recommendation is advisory. Only
+the Revision Manager Agent, acting on user instruction, performs the
+status flip.
+
+## Rollback rules
+
+Three rollback types are supported. All three create a new revision
+— nothing is overwritten in place.
+
+### Undo
+
+Discards the current draft. The new revision's `parentRevisionId` is
+the parent of the discarded draft; the discarded draft is relabeled
+`REJECTED` or `SUPERSEDED`. The discarded draft keeps its artifacts.
+
+### Revert to approved
+
+Creates a fresh draft from `currentApprovedRevisionId`. The approved
+pointer is left untouched. The new revision becomes the draft
+pointer. This is the "panic button" path.
+
+### Selective rollback
+
+Creates a new revision derived from the current draft, replacing one
+or more components with the implementation from an older revision.
+The new revision's `parentRevisionId` is the current draft; its
+`changedComponents` lists exactly which components came from which
+older revisions.
+
+Selective rollback works only when the template is componentized.
+Each visible component must be a small private render method
+(`renderHeader(...)`, `renderHero(...)`, `renderLineItems(...)`,
+`renderFooter(...)`, and so on). If the layout lives in a single
+monolithic `compose` method, selective rollback degrades to manual
+patching. Componentization is therefore part of the rollback
+architecture, not a style preference.
+
+See [`../../../docs/rollback.md`](../../../docs/rollback.md) for the user
+phrases that trigger each rollback type and the exact procedure.
+
+## Required artifacts in every revision
+
+A revision is incomplete if any of the following is missing for the
+work it was supposed to do:
+
+- `revision.json` with `id`, `parentRevisionId`, `status`,
+  `userRequest`, `targetGraphComposeVersion`, `skillPack`,
+  `changedComponents`, and the artifact map
+- `user-request.md` capturing what the user asked for
+- `architecture-plan.md` or `patch.diff` describing the intended
+  change
+- `generated-template.java` (or a documented failure record)
+- `output.pdf` and `output.png` (or a documented render failure)
+- `visual-review.md` (or a documented review failure)
+- `status.md` written by the Revision Manager Agent
+
+A revision without these artifacts cannot be approved. It can still
+be saved as `FAILED` — see the failed-revision section above.
+
+## Common mistakes
+
+1. **Editing a previous revision's files in place.** Forbidden. Every
+   change creates a new revision.
+2. **Approving a revision with missing artifacts.** Approval requires
+   the full artifact set. A missing preview image blocks approval.
+3. **Treating selective rollback as a multi-component edit.** It is a
+   structured copy of named components from named revisions, not a
+   free-form patch.
+4. **Discarding a failed revision.** Failed revisions are preserved
+   with their artifacts. The audit trail depends on it.
+5. **Authoring a monolithic template.** A single giant `compose`
+   method breaks selective rollback. Use named private render
+   methods.
+
+## Cross-references
+
+- [`../../../docs/revision-model.md`](../../../docs/revision-model.md) —
+  project and revision metadata, statuses, artifact inventory
+- [`../../../docs/rollback.md`](../../../docs/rollback.md) — the three
+  rollback types and the user phrases that trigger them
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  — approval rule
+- [`visual-regression`](visual-regression.md) — how visual review
+  decisions feed into revision status
+- [`troubleshooting`](troubleshooting.md) — failure-handling for
+  revisions that cannot produce expected artifacts
diff --git a/skills/versions/graphcompose-1.7/shapes-and-containers.md b/skills/versions/graphcompose-1.7/shapes-and-containers.md
new file mode 100644
index 0000000..372ea80
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/shapes-and-containers.md
@@ -0,0 +1,278 @@
+---
+skillId: shapes-and-containers
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Shapes and Containers Skill
+
+Use this skill when the visual reference contains shaped regions that
+carry content: rounded cards, circles around avatars or icons,
+ellipses framing a highlight, pills behind status labels, clipped
+image areas. Shape containers are the GraphCompose primitive for
+"content lives inside a non-rectangular region".
+
+## When to load
+
+Load this skill whenever the
+[`visual-to-graphcompose-mapping`](visual-to-graphcompose-mapping.md)
+analysis lists any of the following on the reference:
+
+- a rectangular block with visibly rounded corners
+- a circle or ellipse used as a container for an avatar, icon, or
+  number
+- a pill-shaped badge that holds text inside its shape
+- a clipped image area (rounded, circular, or otherwise non-rectangular)
+- any region whose outline is not a plain rectangle but which still
+  holds content
+
+If the shape is only decoration sitting on top of unrelated content,
+switch to [`layer-stacks-and-overlays`](layer-stacks-and-overlays.md)
+instead. If the shape is a flat coloured rectangle with no rounding,
+use [`backgrounds-and-panels`](backgrounds-and-panels.md).
+
+## The container shapes
+
+### Rounded card
+
+A rectangular content surface with rounded corners. The shape
+container clips the inner content and provides the rounded outline.
+Use it whenever the reference's corner radius is visibly non-zero.
+
+### Circle
+
+A circular container, typically holding an avatar, an icon, or a
+single character or number. The container clips the inner content to
+a circle.
+
+### Ellipse
+
+An elongated circular container, used for highlights or single-line
+labels that read as oval rather than pill-shaped.
+
+### Pill
+
+A capsule-shaped container, common for status badges. A pill is a
+rounded rectangle whose corner radius equals half its height.
+
+### Clipped image area
+
+A non-rectangular outline that clips a contained image. The image is
+inside the container; the container provides the silhouette.
+
+## Shape container vs canvas layer — decision rule
+
+This is the most important rule in this skill.
+
+```text
+Use a shape container when the shape CARRIES content.
+
+Use a canvas layer (last resort) when the shape is PURE decoration
+and cannot be expressed with any other primitive.
+```
+
+A rounded card with a title and lines inside it is a shape container,
+not a canvas drawing. A circle around a "1" in a numbered list is a
+shape container, not a circle drawn with raw geometry. A subtle dot
+pattern in a corner with no content inside it is decoration; if no
+other primitive fits, that — and only that — may go on a canvas
+layer.
+
+The rule exists because canvas layers are opaque to:
+
+- layout snapshots (the snapshot cannot reason about what is inside
+  the shape)
+- pagination (the canvas layer does not flow)
+- selective rollback (a canvas-painted "card" cannot be swapped
+  component-for-component)
+- visual review (the review tooling treats the canvas region as a
+  single decorative blob)
+
+Every shape that carries content must be expressed as a container so
+that the surrounding workflow can reason about it.
+
+## Shape-as-container thinking
+
+When mapping a reference, write the shape as the parent and the
+content as the child:
+
+```text
+Container: rounded card
+  Content: title row, body section, totals row
+
+Container: circle (avatar)
+  Content: image, or single initial character
+
+Container: pill (status badge)
+  Content: status text
+```
+
+If the analysis ends up with the shape on one side of the page and
+the content on another (or in a different layer), the mapping is
+wrong. Either the shape is decoration (and is therefore an overlay,
+not a container) or the content belongs inside the shape.
+
+## Child placement inside shapes
+
+For content that belongs inside a shape, use the shape container's
+placement API rather than placing a sibling node nearby.
+
+Verified patterns include:
+
+```java
+section.addCircle(118, DEEP_TEAL, circle -> circle
+        .center(label("GC", style)));
+```
+
+```java
+section.addContainer(card -> card
+        .roundedRect(178, 112, 16)
+        .clipPolicy(ClipPolicy.CLIP_PATH)
+        .center(cardCopy())
+        .position(label("NEW", style), -6, 5, LayerAlign.TOP_RIGHT));
+```
+
+Use `.center(...)` when the child is centered in the shape, and
+`.position(..., LayerAlign.X)` or a shape-specific anchor helper when
+the child is anchored to a shape edge or corner.
+
+Do not render a shape and then place its text/icon/image as a sibling
+paragraph with a negative margin. That breaks component ownership,
+rollback semantics, and layout snapshots even when the preview looks
+close.
+
+## Polygon and per-corner geometry (1.7.0)
+
+GraphCompose 1.7.0 widens `ShapeOutline`
+(`com.demcha.compose.document.style`) beyond rectangles, rounded
+rectangles, and ellipses. The additions are additive — the three
+existing container shapes render identically — but they remove two
+workarounds. Cross-check exact factory signatures against the 1.7.0
+Javadoc.
+
+### Polygon outlines
+
+`ShapeOutline` gains a `Polygon` kind plus a family of factories built
+from normalized `ShapePoint` vertices: `diamond`, `triangle`, `star`,
+`polygon`, `arrow` / `arrowRight` / `arrowLeft` (a 4-way `Direction`),
+`chevron`, `checkmark`, `plus`, and `regularPolygon(sides)`.
+`ShapeContainerBuilder` exposes matching block-level outlines, so a
+diamond or chevron can carry content the same way a rounded card does.
+The same outlines drive inline marks on the text baseline — see
+"Inline shapes vs shape containers" below. Arrows and chevrons read as
+directional list bullets or inline separators between text.
+
+Swappable designs: `ShapeOutline` adds `CheckmarkStyle` (`CLASSIC`,
+`HEAVY`) and `ArrowStyle` (`BLOCK`, `TRIANGLE`) with overloads
+`checkmark(w, h, CheckmarkStyle)` and `arrow(w, h, Direction,
+ArrowStyle)`; the no-style factories delegate to `CLASSIC` / `BLOCK`,
+so the default look is unchanged.
+
+### Per-corner rounded rectangles
+
+A card "rounded on the left, square on the right" no longer needs a
+`CLIP_PATH`-parent workaround. `ShapeContainerBuilder.roundedRect(width,
+height, DocumentCornerRadius)` plus the new
+`ShapeOutline.RoundedRectanglePerCorner` round the four corners
+independently, and both the outline fill/stroke and the child clip
+follow the per-corner geometry. `DocumentCornerRadius.left` / `right` /
+`top` / `bottom(...)` give the common asymmetric presets. The
+single-radius `roundedRect(w, h, double)` overload is unchanged, and
+uniform rounded rectangles render byte-for-byte identically.
+
+## Inline shapes vs shape containers (1.7.0)
+
+A shape can now appear in two distinct roles, and the choice mirrors
+the container-vs-canvas rule above:
+
+- **Shape container** — the shape CARRIES content (a diamond around a
+  number, a chevron tab holding a label). Use `ShapeContainerBuilder`
+  with `.center(...)` / `.position(...)` placement, exactly as for
+  rounded cards.
+- **Inline shape run** — the shape RIDES THE TEXT BASELINE as a mark
+  inside a paragraph (a rating dot, a custom bullet, a `→` between
+  steps, a checklist checkbox). Use `ParagraphBuilder` / `RichText`
+  `dot(...)` / `diamond(...)` / `arrow(...)` / `chevron(...)` /
+  `checkbox(...)` / `shape(ShapeOutline, ...)`; it is measured into line
+  width and height like an inline image. Detailed authoring rules live
+  in [`typography`](typography.md).
+
+Neither role is a canvas drawing. A geometry mark that used to require
+a font glyph (U+25CF and friends) or a hand-placed sibling node is now
+a first-class inline run or container outline — prefer it over the
+hack.
+
+## Clipping
+
+Shape containers clip their content to the shape outline. The
+implications matter:
+
+- text that would extend past the shape outline is clipped, not
+  reflowed. Provide enough room inside the container.
+- images placed inside a circle or ellipse container will be clipped
+  to that outline. Use the container shape to express that intent
+  rather than pre-clipping the image externally.
+- nested shape containers compose: a rounded card containing a
+  circular avatar is two containers, not one canvas drawing.
+
+## Required visual checks
+
+- the corner radius visually matches the reference
+- the content sits inside the shape, never bleeding through the
+  outline
+- circular containers stay circular when the inner content changes
+  size (do not let inner content stretch the container into an
+  ellipse unless the reference is itself an ellipse)
+- clipping is symmetric where the reference is symmetric
+- pagination does not split a shape container mid-shape — see
+  [`pagination`](pagination.md) on atomic blocks
+- snapshots and visual regression diffs still pass
+
+## Known limitations
+
+- Rendering of exotic clip paths (complex polygons, custom curves)
+  may differ across renderers. Document those differences in
+  `visual-review.md` and tag them `ACCEPTED_LIMITATION` per
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md).
+- Anti-aliasing on rounded corners is renderer-dependent. Tiny
+  differences (sub-millimetre fringes) usually fall under `MINOR`
+  unless the brand explicitly demands a specific corner treatment.
+- Shadows, glows, and stroke effects on shapes are not described by
+  this skill. If the reference uses them and no other primitive
+  applies, list them as visual risks in `architecture-plan.md` and
+  document them as accepted limitations until a later skill version
+  covers them.
+
+## Common mistakes
+
+1. **Drawing the card outline on a canvas layer and placing the
+   content next to it.** The content is not inside the shape; the
+   shape is decoration. Use a shape container instead.
+2. **Using a layer stack to fake a rounded card.** Layering a smaller
+   panel over a larger rounded rectangle does not produce a
+   container. Use a shape container.
+3. **Clipping the image externally before placing it in a rectangular
+   panel.** This loses the semantic "image inside a circle". Use a
+   circular container.
+4. **Allowing inner content to deform a circle into an ellipse.**
+   Constrain the container; resize the content.
+5. **Rendering shape-owned content as a sibling overlay.** If a
+   circle contains initials, the initials are a child of the circle
+   via `.center(...)`; they are not a later paragraph pulled upward
+   with a negative margin.
+
+## Cross-references
+
+- [`backgrounds-and-panels`](backgrounds-and-panels.md) — when the
+  surface is rectangular
+- [`layer-stacks-and-overlays`](layer-stacks-and-overlays.md) — when
+  the shape is decoration on top of unrelated content
+- [`layout-primitives`](layout-primitives.md) — the row, section, and
+  table primitives that go inside containers
+- [`pagination`](pagination.md) — atomic-block behaviour for shaped
+  containers across page breaks
+- [`visual-regression`](visual-regression.md) — renderer-specific
+  shape differences are documented here
diff --git a/skills/versions/graphcompose-1.7/spacing-and-alignment.md b/skills/versions/graphcompose-1.7/spacing-and-alignment.md
new file mode 100644
index 0000000..034ffd3
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/spacing-and-alignment.md
@@ -0,0 +1,204 @@
+---
+skillId: spacing-and-alignment
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Spacing and Alignment Skill
+
+Use this skill when deciding page margins, the gaps between
+sections, the padding inside primitives, and the alignment grid
+that holds a template together.
+
+## Measuring reference page margins
+
+Margins are the first thing to lock down because they constrain
+every region inside the page. The Visual Analyzer Agent should
+extract:
+
+- top, bottom, left, and right margins from the reference image
+- whether margins are visually symmetric or intentionally asymmetric
+- whether there is a bleed area, an outer frame, or a printer-safe
+  zone
+- whether the reference is calibrated against a known page size
+  (Letter, A4, custom)
+
+Record the measurements in `visual-analysis.md` in millimeters or
+points, not pixels. Pixel measurements depend on the reference's
+DPI and do not survive into the template. Convert at analysis time
+and use the converted values throughout.
+
+## Internal gaps
+
+Inside the page the template has several distinct kinds of gap.
+Treat each one as a separate, named decision.
+
+- Section spacing — the vertical gap between top-level regions
+  (Header, Hero, Parties, LineItems, Footer). This is the rhythm of
+  the document and should be constant unless the reference is
+  visually asymmetric on purpose.
+- Row gutters — the horizontal gap between cells of a row primitive
+  (logo plus address plus QR). Gutters should be consistent inside
+  a row; varied gutters usually indicate a missed sub-row or a
+  shape container that absorbs spacing internally.
+- Table padding — the inner padding inside table cells. Header
+  padding is often larger than body padding. Document both.
+- Component padding — padding inside a section, panel, or shape
+  container. This is separate from the gap between components.
+
+Each kind of gap must be named (see "Consistency rules" below) so
+revisions like "make the rows tighter" can be applied to the right
+token without touching unrelated spacing.
+
+## Alignment grids and how primitives enforce them
+
+Rows arrange their children horizontally (side by side); sections
+stack their children vertically. Neither primitive exposes a
+cross-axis alignment option in 1.7 — there is no row-level "centre
+the children vertically" knob and no section-level "centre the
+children horizontally" knob. (1.7.0 does add per-LINE vertical seating
+of text — `verticalAlign(TextVerticalAlign)`, see "Vertical text
+seating" below — but that is a paragraph control, not a row/section
+child-alignment knob.) Reach for the right structural tool instead of
+faking balance with blank space.
+
+- A row places children along the horizontal axis by weight or
+  width. It does NOT vertically align children of different heights
+  — `RowBuilder` has no top / center / baseline / bottom option. To
+  put an icon and a text label on a shared vertical axis, give them
+  the same height, or wrap the pair in a shape container / layer
+  stack and centre each layer with `.center(...)` / `LayerAlign`
+  (see [`layer-stacks-and-overlays`](layer-stacks-and-overlays.md)
+  and [`shapes-and-containers`](shapes-and-containers.md)).
+- A section stacks children vertically at the content width. It has
+  no left / right / center / stretch child-alignment option; a
+  child's horizontal position comes from its own width and, for
+  text, the paragraph's `TextAlign`. For a centred badge or label
+  inside a box, use a shape container / layer-stack layer with a
+  `LayerAlign` anchor, not a section option.
+- When two adjacent regions must share a visual edge (a header
+  bottom flush with a hero top), align them by matching their
+  measured heights / widths and the parent gap, not by per-region
+  padding fudges.
+
+Note: 1.7 adds a per-line vertical-seating control on text. A single
+line dropped into a taller box still sits on its font baseline by
+default (`TextVerticalAlign.DEFAULT`), but
+`ParagraphBuilder.verticalAlign(TextVerticalAlign)` now seats it by its
+cap band — `TOP`, `CENTER`, or `BOTTOM` — within its line box. For a
+label centred in a taller pill / `ShapeContainer`, combine
+`verticalAlign(TextVerticalAlign.CENTER)` with a vertically-centred
+layer placement (`.center(...)` / `.centerLeft(...)`) instead of
+nudging the text with blank lines or padding lifts. The correction is
+derived from font metrics (ascent, descent, leading, cap height), not a
+magic number, and it is render-only — existing layouts are
+byte-for-byte unchanged. See "Vertical text seating" below.
+
+If the reference clearly uses a column grid (12 columns, 8 columns,
+etc.), the template should express that grid through the row or
+section primitives' widths. Do not pretend to have a grid by
+measuring pixels and writing absolute positions; that re-enters
+coordinate soup and breaks selective rollback.
+
+## Vertical text seating (1.7.0)
+
+This is the anchor-first answer to "my label sits low in its box".
+Before 1.7.0 the only fix was to centre the whole text layer with a
+shape-container / layer-stack `.center(...)`; the text itself always
+sat on its font baseline. 1.7.0 adds
+`ParagraphBuilder.verticalAlign(TextVerticalAlign)` (enum
+`com.demcha.compose.document.node.TextVerticalAlign`):
+
+- `TOP` — cap top to the box top
+- `CENTER` — cap band centred in the line box
+- `BOTTOM` — baseline to the box bottom
+- `DEFAULT` — the pre-1.7.0 baseline seating (unchanged)
+
+Use it as the in-paragraph complement to layer placement: a single
+label in a taller `ShapeContainer` / `LayerStack` "pill" sits where you
+ask when you pair `verticalAlign(CENTER)` with a centred layer anchor,
+instead of a compensating offset hack. It is opt-in and render-only —
+omit it and nothing changes. This belongs to the "anchors over
+hand-computed offsets" principle: prefer the engine's vertical seating
+over blank-line or padding fudges. See [`typography`](typography.md)
+for the typographic side.
+
+## Dashed dividers (1.7.0)
+
+When a gap is marked by a rule rather than whitespace — a dashed
+section divider, a cut-here line, a timeline connector — reach for
+`LineBuilder.dashed(...)` (a dotted rule is `dashed(1, 4)`) rather than
+a row of glyph characters. The primitive and its `DocumentDashPattern`
+value type live in [`layout-primitives`](layout-primitives.md).
+
+## Consistency rules and spacing tokens
+
+Use named tokens for repeated spacing the same way colors are
+tokenized in [`themes-and-colors`](themes-and-colors.md). The token
+name describes role, not value. A revision that says "more breathing
+room between sections" should change one token, not dozens of
+literals.
+
+Suggested tokens:
+
+- `gapSection` — vertical gap between top-level regions
+- `gapRow` — vertical gap between sub-rows inside a section
+- `gutterRow` — horizontal gap inside a row primitive
+- `padTable` — inner padding for table cells
+- `padPanel` — inner padding for sections and panels
+- `padBadge` — inner padding for small overlay elements
+
+Templates should declare these tokens once near the theme and
+import them into every render method. Bare numeric literals in
+compose code are a code smell.
+
+## When to load
+
+Load this skill any time:
+
+- a new template's spacing is being defined
+- a revision uses words like "tighter", "looser", "more breathing
+  room", "more compact", "more spacious"
+- alignment between two regions is being questioned in visual review
+- the reference uses an obvious column grid
+
+This skill chains with [`layout-primitives`](layout-primitives.md)
+(for choosing the right primitive),
+[`tables`](tables.md) (for cell padding), and
+[`themes-and-colors`](themes-and-colors.md) (for the shared naming
+discipline).
+
+## Known limitations
+
+- 1 to 3 pixel drift between renderers is normal. Classify it as
+  `MINOR` per
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  unless it visibly breaks alignment (a column lands a pixel left
+  of its neighbor, a footer overlaps the page bottom rule, etc.).
+  Document the drift in `visual-review.md` so reviewers know it was
+  observed and accepted.
+- Sub-pixel placement of overlapping primitives (a badge over a
+  card edge) may differ between renderers. Adjust the layer stack
+  position by token, not by an arbitrary literal, and re-measure
+  after rendering.
+- When the reference's spacing is itself inconsistent (a hand-built
+  mockup with stray gaps), the template should normalize the gaps
+  through tokens rather than copy the inconsistency. Note the
+  normalization in `visual-review.md`.
+
+## Cross-references
+
+- [`graphcompose-basics`](graphcompose-basics.md) for the place of
+  layout in the semantic model
+- [`layout-primitives`](layout-primitives.md) for choosing the
+  right primitive
+- [`tables`](tables.md) for cell padding and table-internal gaps
+- [`themes-and-colors`](themes-and-colors.md) for the shared
+  naming convention
+- [`typography`](typography.md) for line-spacing decisions that
+  interact with vertical rhythm
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  for spacing mismatch classification
diff --git a/skills/versions/graphcompose-1.7/tables.md b/skills/versions/graphcompose-1.7/tables.md
new file mode 100644
index 0000000..5a7e196
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/tables.md
@@ -0,0 +1,132 @@
+---
+skillId: tables
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Tables Skill
+
+Use TableBuilder for all structured row/column content.
+
+Do not recreate tables using manual text rows unless the reference is not semantically a table.
+
+## Required visual checks
+
+- number of columns matches reference
+- column proportions match reference
+- header styling matches reference
+- row height is visually close
+- borders match or are documented
+- zebra rows match if present
+- totals/footer row matches
+- repeated headers are configured when content paginates
+
+## When to load
+
+Load this skill whenever the reference contains structured row and
+column content. Typical triggers:
+
+- invoice line items
+- pricing tables, fee schedules
+- comparison or feature tables
+- transaction logs and schedules
+- any region where columns have shared meaning across rows
+
+It pairs with
+[`visual-to-graphcompose-mapping`](visual-to-graphcompose-mapping.md)
+(which decides that the region is a table at all),
+[`layout-primitives`](layout-primitives.md) (which separates tables
+from rows or sections), and
+[`themes-and-colors`](themes-and-colors.md) (for header/zebra colors
+that must flow through theme tokens).
+
+## When NOT to use TableBuilder
+
+Not every grid of content is a table. The table primitive must not
+be forced on regions that are not semantically tabular. Use rows,
+sections, or shape containers instead in these cases.
+
+- Decorative grid of icons or logos with no shared column meaning.
+  Each cell is independent and the grid is for visual rhythm; use
+  rows or a section with repeated render methods.
+- Image collage or photo gallery. Use a section that lays out a
+  sequence of figures, or per-cell shape containers when the cells
+  are rounded.
+- Free-form key-value list outside a real table — for example, a
+  small "From / To / Date" block in an invoice header. This is a
+  row of labelled fields, not a table.
+- Single-row arrangements (logo plus address plus QR). Use a row.
+- Side-by-side panels with different internal structure. Use a row
+  of sections; the panels do not share column meaning.
+
+When in doubt, ask: "Do the rows share the meaning of each column?"
+If yes, it is a table. If no, it is not.
+
+## Pagination expectations
+
+Tables are the primary source of multi-page content in templates.
+When a table can paginate, the template must:
+
+- preserve the header row on each new page
+- avoid mid-row page breaks where possible
+- keep totals or footer rows attached to the last data section
+  visually
+- document any pagination-only artefacts in `visual-review.md`
+
+The detailed pagination contract — `pageFlow` integration, atomic
+blocks, repeated headers, and per-page visual checks — lives in the
+parallel-lane `pagination.md`. Cross-link to that file from the
+architecture plan whenever the table is expected to overflow one
+page.
+
+## Theme alignment
+
+Tables consume theme tokens for header background, row backgrounds,
+borders, and totals. Do not hardcode hex values inside the table
+render method. Use the named tokens described in
+[`themes-and-colors`](themes-and-colors.md): for example,
+`tableHeader`, `tableRowAlt`, and `borderMuted`. This keeps the
+table consistent with the rest of the template and lets a theme
+swap propagate everywhere.
+
+## Known limitations
+
+- Exact pixel proportions for column widths may require manual
+  tuning. The library aims for visual fidelity, not pixel-exact
+  reproduction, and 1 to 3 pixel drift between renderers is normal.
+  Document any deliberate proportion adjustments in
+  `visual-review.md` and classify them per the rules in
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md).
+- Complex cell content (icons inline with text, nested badges) may
+  need a per-cell render method rather than a plain string. Treat
+  the cell content as its own miniature semantic block and reach
+  for the same primitive decision flow described in
+  [`layout-primitives`](layout-primitives.md).
+- Cross-page totals, running balances, and merged cells require
+  careful handling. If the verified examples for 1.7.0 do not show
+  the exact pattern needed, mark the requirement as a Visual Risk
+  in `architecture-plan.md` and document substitutions in
+  `visual-review.md` rather than inventing API surface.
+
+When library behavior diverges from anything written here, the
+library is the source of truth. File a skill fix report per
+[`../../../docs/skill-validation.md`](../../../docs/skill-validation.md)
+and do not silently patch around the skill.
+
+## Cross-references
+
+- [`visual-to-graphcompose-mapping`](visual-to-graphcompose-mapping.md)
+  for the upstream decision that a region is a table
+- [`layout-primitives`](layout-primitives.md) for the broader
+  primitive selection rules
+- [`themes-and-colors`](themes-and-colors.md) for header and zebra
+  styling tokens
+- [`typography`](typography.md) for table cell font choices
+- [`spacing-and-alignment`](spacing-and-alignment.md) for padding
+  and gutters inside cells
+- parallel-lane `pagination.md` for multi-page table behavior
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  for the parity contract that table reviews must satisfy
diff --git a/skills/versions/graphcompose-1.7/themes-and-colors.md b/skills/versions/graphcompose-1.7/themes-and-colors.md
new file mode 100644
index 0000000..0fc3785
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/themes-and-colors.md
@@ -0,0 +1,125 @@
+---
+skillId: themes-and-colors
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Themes and Colors Skill
+
+Use theme tokens for repeated colors.
+
+Do not scatter random hex values across the template.
+
+Create named tokens for:
+
+- primary accent
+- secondary accent
+- background
+- panel background
+- muted text
+- border
+- table header
+- warning/success badges
+
+If exact color matching is not possible, document the substitution in visual-review.md.
+
+## When to load
+
+Load this skill any time:
+
+- a new template is being authored and a theme must be defined
+- a revision changes colors (the table is "too dark", the accent
+  should be "warmer", the panels should be "softer")
+- a reference is being mapped and the agent has to decide whether a
+  color is part of the theme or local to one component
+- visual review work flags color mismatches that need to be
+  classified per the visual accuracy contract in
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+
+This skill is also a prerequisite for [`tables`](tables.md) (for
+header and zebra colors) and for the parallel-lane
+`backgrounds-and-panels.md` skill (for page and section
+backgrounds).
+
+## Token naming convention
+
+Token names must describe role, not appearance. The same token
+should survive a complete palette redesign without renaming. Pick
+semantic names that describe what the token does in the template.
+
+- Good: `accentPrimary`, `accentSecondary`, `panelBackground`,
+  `tableHeader`, `tableRowAlt`, `borderMuted`, `textMuted`,
+  `badgeWarning`, `badgeSuccess`.
+- Bad: `darkBlue`, `lightGray`, `red`, `theBlueOne`,
+  `headerColor3`, `lighterGrayThanTheOtherGray`.
+
+The visual name is allowed to *change* without the token name
+changing. If the brand swaps the primary accent from blue to green,
+`accentPrimary` is still the right token; only its hex value moves.
+Hardcoding `darkBlue` everywhere would force a global rename and
+would scatter color decisions across the template.
+
+## Color substitution policy
+
+Sometimes the reference uses a color that the agent cannot match
+exactly — a custom brand color outside the documented palette, a
+print-only spot color, or a gradient the engine cannot reproduce.
+When exact match is not possible, the agent must document the
+substitution rather than silently approximate.
+
+Each substitution must be recorded in `visual-review.md` with:
+
+- the reference hex (or a printed swatch description if hex is
+  unknown)
+- the hex the template uses
+- the reason for the substitution (out of gamut, gradient
+  unavailable, accessibility constraint, brand alternative)
+- the mismatch classification per
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md):
+  typically `MINOR` for a small shift or `ACCEPTED_LIMITATION` when
+  the renderer cannot represent the original
+
+Undocumented color drift is a defect under the visual accuracy
+contract.
+
+## Where colors should live
+
+- Theme tokens belong in a dedicated theme value
+  (`BusinessTheme`-style object) that is constructed once and passed
+  into the template. The exact constructor surface is part of the
+  verified examples — do not invent setters on it. See the
+  no-invented-API rule in
+  [`../../../docs/versioned-skills.md`](../../../docs/versioned-skills.md).
+- Inside render methods, refer to tokens by name. Do not inline hex
+  values. Comments next to the token definition are the right place
+  for "reference brand blue, RGB 23 56 120" notes.
+- One-off colors that legitimately belong to one component (a
+  watermark tint, a single highlight) may live next to that
+  component, but they should still be named constants, not bare
+  hex literals scattered through compose code.
+
+## Accessibility note
+
+When a token serves as text-on-background, the agent should check
+contrast against the relevant background token. Failed contrast is a
+visual defect even when the reference itself fails — the agent must
+flag it in `visual-review.md` and propose an alternative if the user
+has not explicitly accepted the original. Treat this as `MINOR`
+unless the failure makes content unreadable.
+
+## Cross-references
+
+- [`graphcompose-basics`](graphcompose-basics.md) for the place of
+  themes in the mental model
+- [`tables`](tables.md) for table-specific tokens
+- [`typography`](typography.md) for font-color pairing
+- [`spacing-and-alignment`](spacing-and-alignment.md) for the
+  spacing tokens that share the same naming discipline
+- parallel-lane `backgrounds-and-panels.md` and
+  `shapes-and-containers.md` for token usage in panel and shape
+  styling
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  for the classification rules that govern color substitutions
diff --git a/skills/versions/graphcompose-1.7/troubleshooting.md b/skills/versions/graphcompose-1.7/troubleshooting.md
new file mode 100644
index 0000000..e08c9fa
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/troubleshooting.md
@@ -0,0 +1,246 @@
+---
+skillId: troubleshooting
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Troubleshooting Skill
+
+Use this skill whenever something goes wrong in the workflow: the
+library disagrees with the skill pack, a documented primitive turns
+out to be missing, the render step does not produce `output.pdf`, the
+visual mismatch is larger than the analysis predicted, or the
+GraphCompose version cannot be detected. The goal of this skill is to
+contain the failure inside the current revision, preserve evidence,
+and avoid the temptation to "make it work" by inventing API.
+
+## When to load
+
+Load this skill on any failure or surprise during the workflow:
+
+- the build fails
+- the render step does not produce `output.pdf`
+- a primitive documented in the skill pack is not present in the
+  selected GraphCompose version
+- the visual review records a `CRITICAL` or `MAJOR` mismatch the
+  architecture plan did not predict
+- the version of GraphCompose cannot be determined from the project
+  metadata
+- a skill example references behavior the library does not provide
+
+## Failure modes
+
+### Skill drift
+
+The library disagrees with the skill documentation. Quoted verbatim
+from §7.4 of the project plan:
+
+```text
+If GraphCompose behavior differs from the skill documentation, the library is treated as the source of truth.
+
+The skill must be updated.
+
+The agent must not silently work around incorrect skills.
+```
+
+Required response:
+
+1. Do not patch the template to dodge the broken skill.
+2. Mark the affected skill in the manifest with status
+   `failed-validation`.
+3. File a skill fix report following the template in
+   [`../../../docs/skill-validation.md`](../../../docs/skill-validation.md).
+   Required fields: affected skill file, GraphCompose version,
+   problem description, expected behavior according to skill, actual
+   library behavior, failing example, required skill update, status
+   (`FAILED` / `NEEDS UPDATE` / `FIXED`).
+4. Leave the revision in a state that reflects reality: `FAILED` if
+   the drift blocks rendering, `DRAFT` with documented limitations
+   if the drift can be worked around in a conservative way.
+
+### Missing primitive
+
+The skill pack mentions a primitive the selected GraphCompose version
+does not expose, or the primitive exists but its behavior is
+materially different from the skill description. This is a special
+case of skill drift but is common enough to call out separately.
+
+Required response:
+
+1. Do not invent a substitute primitive or imagine a builder method.
+   The no-invented-API rule in
+   [`../../../docs/versioned-skills.md`](../../../docs/versioned-skills.md)
+   applies to skills themselves: if the primitive is not there,
+   treat it as unavailable.
+2. Fall back to a conservative composition using primitives that
+   are present and verified for the version
+   (`DocumentSession`, `pageFlow`, the row primitive, the section
+   primitive, the table primitive, the theme, the layer-stack and
+   shape-container primitives where they exist).
+3. Document the gap in `architecture-plan.md` as a visual risk and
+   in `visual-review.md` as an `ACCEPTED_LIMITATION` per
+   [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md).
+4. File a skill fix report in
+   `validation/skill-fix-report.md` describing the missing primitive
+   and the conservative fallback that was used. The template lives
+   in [`../../../docs/skill-validation.md`](../../../docs/skill-validation.md).
+
+### Render failure
+
+The Test + Render Agent could not produce `output.pdf`. This may be
+caused by:
+
+- compile failure in `generated-template.java`
+- an exception thrown during rendering
+- a missing dependency the fixture or project did not declare
+- a renderer crash on a specific shape, font, or layer combination
+
+Required response:
+
+1. Preserve every artifact that was produced before the failure:
+   `build.log`, `render.log`, the partial
+   `generated-template.java`, any intermediate snapshot.
+2. Mark the revision `FAILED` in its `revision.json` per
+   [`../../../docs/revision-model.md`](../../../docs/revision-model.md).
+3. Do not delete the revision folder. The audit trail depends on
+   the failed artifacts staying on disk.
+4. Create the next revision from the previous good draft or the
+   approved revision, not by editing the failed folder in place. See
+   [`revision-discipline`](revision-discipline.md).
+5. If the cause was a missing primitive or a skill bug, also follow
+   the skill drift or missing primitive flow above.
+
+### Visual mismatch larger than expected
+
+The visual review records a `CRITICAL` or `MAJOR` mismatch that the
+architecture plan did not anticipate. This is not a render failure;
+the document built, but it does not match the reference. The
+temptation is to patch the template until the diff shrinks. That is
+the wrong response under this workflow.
+
+Required response:
+
+1. Do not silently patch the template. The mismatch indicates either
+   a flaw in the visual analysis or a flaw in the architecture
+   mapping; patching downstream code hides the upstream defect.
+2. Rerun the Visual Analyzer Agent on the reference, focusing on
+   the region that mismatched.
+3. Rerun the Architecture Mapper Agent on the updated analysis,
+   producing a new `architecture-plan.md`.
+4. Only after the analysis and the plan have been updated does the
+   Template Coder Agent regenerate or patch the template.
+5. Create a new revision for every iteration. The original revision
+   keeps its `visual-review.md` showing the mismatch; the new
+   revision shows the fix. The audit trail records both.
+
+If the mismatch is caused by a missing primitive or a skill drift,
+follow those flows as well.
+
+### Version uncertainty
+
+The Version + Skill Resolver Agent could not detect the
+GraphCompose version from the project metadata, or the detected
+version is not represented in the skill pack manifest.
+
+Required response:
+
+1. Do not pick a version "close enough". Versioned skills exist
+   precisely because mixing primitives across versions causes
+   defects.
+2. Restrict the template to conservative verified primitives only:
+   `DocumentSession`, `pageFlow`, the row primitive, the section
+   primitive, the table primitive, the theme. Avoid layer stacks,
+   shape containers, and anything else that is version-sensitive
+   until the version is known.
+3. Log the resolution path in `version-resolution.md` for the
+   revision, including the inputs the agent inspected, the
+   ambiguity, and the conservative fallback that was chosen. The
+   resolution log is required even when the version is detected
+   successfully.
+4. Mark the revision with status `DRAFT` and an explicit note in
+   `status.md` that the version was unresolved.
+5. Ask the user to confirm the version before approval.
+
+## Symptoms with a 1.7.0 remedy
+
+Three recurring symptoms have a first-class fix in GraphCompose 1.7.0
+(this pack's target version). Reach for the documented primitive rather
+than a workaround.
+
+- **A bullet / rating dot / arrow renders as tofu or vanishes** because
+  the font lacks U+25CF and friends. Do not switch fonts or fake the
+  mark with an image. Draw it from geometry: an inline shape run
+  (`ParagraphBuilder` / `RichText` `dot(...)` / `shape(ShapeOutline,
+  ...)` / `arrow(...)` / `checkbox(...)`). See
+  [`typography`](typography.md) and
+  [`shapes-and-containers`](shapes-and-containers.md).
+- **A positioned badge inside a nested stack will not move off its
+  anchor.** This was a real bug in the fixed-slot stack path and is
+  fixed in 1.7.0 — `position(node, dx, dy, align)` offsets are now
+  honored for stacks nested in a row column or another layer. Confirm
+  the project resolves 1.7.0; do not compensate with a canvas-drawn
+  badge. See
+  [`layer-stacks-and-overlays`](layer-stacks-and-overlays.md).
+- **An asymmetric / per-corner rounded card needed a CLIP_PATH-parent
+  workaround.** Use `roundedRect(w, h, DocumentCornerRadius)` /
+  `ShapeOutline.RoundedRectanglePerCorner` instead. See
+  [`shapes-and-containers`](shapes-and-containers.md).
+
+These are remedies, not skill drift: the primitives exist in 1.7.0. If
+a project is pinned to 1.6.x, the `graphcompose-1.6` pack documents the
+older workarounds and the missing-primitive flow above applies.
+
+## Containment principles
+
+Every troubleshooting response shares three principles:
+
+1. **Preserve the evidence.** Failed revisions keep their artifacts.
+   Skill drift produces a skill fix report. Version uncertainty
+   produces a resolution log.
+2. **Do not invent.** Inventing API, inventing primitives, or
+   inventing version compatibility are all forbidden.
+3. **Create a new revision rather than edit in place.** This applies
+   to fixes after failures, to retries after visual mismatches, and
+   to reruns after skill or version corrections.
+
+## Common mistakes
+
+1. **Patching the template to dodge a broken skill.** Forbidden.
+   Update the skill.
+2. **Substituting an invented method when a documented primitive is
+   missing.** Forbidden. Fall back to conservative primitives.
+3. **Deleting a failed revision folder.** Forbidden. The audit trail
+   depends on it.
+4. **Picking a "close enough" GraphCompose version.** Forbidden.
+   Restrict to verified primitives and ask the user.
+5. **Patching downstream code instead of rerunning analysis and
+   mapping** when the visual mismatch is larger than predicted.
+   Forbidden.
+
+## Known limitations
+
+- Not every failure mode has a documented response yet. New failure
+  modes must be captured in this skill or in
+  [`../../../docs/skill-validation.md`](../../../docs/skill-validation.md)
+  before they recur.
+- Automated detection of skill drift requires the validation
+  fixtures shipped in Phase 4. Until those land, drift detection is
+  human-led.
+
+## Cross-references
+
+- [`../../../docs/skill-validation.md`](../../../docs/skill-validation.md)
+  — skill drift handling and skill fix report template
+- [`../../../docs/versioned-skills.md`](../../../docs/versioned-skills.md)
+  — no-invented-API rule and skill statuses
+- [`../../../docs/revision-model.md`](../../../docs/revision-model.md) —
+  failure handling and the `FAILED` status
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  — classification of unexpected mismatches
+- [`revision-discipline`](revision-discipline.md) — how failures
+  produce new revisions rather than overwriting old ones
+- [`visual-regression`](visual-regression.md) — the loop that
+  surfaces unexpected mismatches
diff --git a/skills/versions/graphcompose-1.7/typography.md b/skills/versions/graphcompose-1.7/typography.md
new file mode 100644
index 0000000..d553d21
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/typography.md
@@ -0,0 +1,203 @@
+---
+skillId: typography
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Typography Skill
+
+Use this skill when deciding which fonts, weights, and sizes apply
+to each region of a GraphCompose template, and how to handle the
+common case where the reference uses a font the renderer cannot
+reproduce exactly.
+
+## Font matching strategy
+
+The agent should treat font matching as a three-step decision, not
+as a guess.
+
+1. Identify the reference font, or describe it precisely. Look at
+   stroke contrast (modulated vs uniform), serifs (present, slab,
+   absent), letter widths, x-height, and any obvious style markers.
+   Record the identification or the description in
+   `visual-analysis.md`.
+2. Decide whether the reference font is licensable and embeddable
+   in the renderer environment. Use
+   [Google Fonts](https://fonts.google.com/) as the default source
+   for embeddable open fonts when the reference font itself is not
+   available. Many display and custom commercial fonts cannot be
+   embedded; treat licensing as a hard constraint, not a wish.
+3. If the reference font cannot be used, pick the closest fallback
+   in the same family (serif, sans-serif, slab, monospace) and the
+   same weight class. Record the substitution in `visual-review.md`
+   per the color substitution policy in
+   [`themes-and-colors`](themes-and-colors.md).
+
+Do not invent a font name that is not available in the renderer.
+Default to a documented PDF-safe family when uncertain.
+
+## Typographic hierarchy
+
+Every template has a layered hierarchy. The agent must define each
+of the following roles, even if some collapse to the same actual
+font and size:
+
+- `title` — the document's headline. Used once near the top.
+  Purpose: identify the document at a glance.
+- `subtitle` — supporting line under the title. Purpose: clarify
+  document scope, version, or context without competing with the
+  title.
+- `sectionHeading` — heading inside a major region (Hero, Parties,
+  Payment Instructions). Purpose: split the document into scannable
+  blocks.
+- `body` — default text. Purpose: convey the bulk of the content
+  comfortably at reading size.
+- `caption` — small, secondary text such as fine print, labels, or
+  legends. Purpose: present supporting metadata without drawing
+  attention.
+- `tableCell` — the font used inside table cells. Purpose: keep
+  tabular content compact and legible at the chosen column widths.
+
+The hierarchy is named, not hardcoded. The same naming discipline
+described in [`themes-and-colors`](themes-and-colors.md) applies:
+use roles, not visual descriptors. `title` survives a font swap;
+`bigBoldBlue` does not.
+
+## Fallback chain
+
+When the renderer cannot use the chosen font, the agent must use a
+PDF-safe fallback. The standard 14 PDF base fonts (Times, Helvetica,
+Courier, Symbol, ZapfDingbats and their bold/italic variants) are
+always available and require no embedding. For most templates the
+fallback chain follows the family of the original:
+
+- sans-serif reference -> Helvetica family
+- serif reference -> Times family
+- monospace reference -> Courier family
+- decorative or display reference -> closest sans-serif fallback,
+  document the substitution
+
+A custom fallback list is allowed when the project ships embedded
+fonts, but the chain must still end with a PDF-safe family so the
+template cannot fail to render. GraphCompose can add fonts to font
+libraries, so the architecture plan must record the family, weights,
+source, and fallback before code generation. Specific font
+registration APIs must match the verified 1.7.0 examples — do not
+invent them.
+
+## Inline figures, monospace, and vertical seating (1.7.0)
+
+GraphCompose 1.7.0 adds three typography-adjacent capabilities. Each is
+additive and opt-in — existing hierarchies are unchanged — but each
+removes a workaround the 1.6.x pack had to live with. Cross-check the
+exact overloads against the 1.7.0 Javadoc before relying on a
+signature.
+
+### Inline shapes instead of glyph hacks
+
+Rating dots (`●●●●○`), custom bullets, and inline status markers used
+to depend on the chosen font actually shipping the glyph (U+25CF and
+friends). When the fallback font lacked it, the mark rendered as tofu
+or vanished. 1.7.0 draws these from geometry instead: an
+`InlineShapeRun` paints any `ShapeOutline` on the paragraph baseline,
+measured into line width and height like an inline image. Author it
+through `ParagraphBuilder` / `RichText`:
+
+- `dot(...)`, `ellipse(...)`, `diamond(...)`, `triangle(...)`,
+  `star(...)` for filled or outlined marks;
+- `arrow(size, Direction, fill)` and `chevron(...)` for directional
+  separators ("Step 1 → Step 2", "Home › Docs");
+- `shape(ShapeOutline, ...)` for any other figure (the `ShapeOutline`
+  factories live in [`shapes-and-containers`](shapes-and-containers.md)).
+
+A `null` fill paints an outlined figure; a `null` stroke paints a
+filled one; at least one of the two must be present. Prefer an inline
+shape over a Unicode glyph whenever the mark is decorative geometry
+(dots, bullets, arrows) rather than real text — geometry cannot fall
+victim to font coverage.
+
+### Inline checkboxes for checklists
+
+`checkbox(size, checked, color)` / `checkbox(size, checked, boxColor,
+checkColor)` draw a rounded frame plus, in the checked state, a centred
+tick — the todo / checklist marker for "some items done, some not".
+Internally an inline shape run can stack several paint layers
+(`ShapeLayer`), so the frame and tick still measure and place as one
+unit on the baseline. `ShapeOutline.CheckmarkStyle` (`CLASSIC`,
+`HEAVY`) and a raw `ShapeOutline` mark let you swap the tick design.
+
+### JetBrains Mono for code and data
+
+`FontName.JETBRAINS_MONO` joins the bundled `DefaultFonts` catalog
+(Regular / Bold / Italic / Bold-Italic, OFL-1.1), so monospaced code
+blocks, data dumps, and tabular figures render without a system-font
+install. Use it through any `DocumentTextStyle.fontName(...)`, and still
+end the fallback chain with a PDF-safe family (Courier) per the chain
+above.
+
+### Vertical seating of a single line
+
+A label dropped into a taller box (a pill, a `ShapeContainer`, a
+heading band) used to sit on its font baseline, not optically centred.
+`ParagraphBuilder.verticalAlign(TextVerticalAlign)` now seats the line
+by its cap band within its line box — `TOP`, `CENTER`, or `BOTTOM`;
+`TextVerticalAlign.DEFAULT` keeps the pre-1.7.0 baseline. Combine it
+with a vertically-centred layer placement (`.center(...)` /
+`.centerLeft(...)`) so the label sits where you ask instead of needing
+a compensating offset. Full rule in
+[`spacing-and-alignment`](spacing-and-alignment.md).
+
+## When to load
+
+Load this skill any time:
+
+- a new template defines its initial font hierarchy
+- a revision touches font size, weight, or family in any region
+- the reference uses a non-standard font and the agent has to pick a
+  fallback
+- visual review flags a typography mismatch that needs to be
+  classified per
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+
+This skill chains with [`themes-and-colors`](themes-and-colors.md)
+(font color), [`spacing-and-alignment`](spacing-and-alignment.md)
+(line spacing, padding around text), and [`tables`](tables.md)
+(table cell typography).
+
+## Known limitations
+
+- Exact font matching is not guaranteed, especially for custom
+  commercial fonts that cannot be embedded. Document substitutions
+  in `visual-review.md` with the reference font name (or
+  description) and the chosen fallback.
+- Sub-pixel kerning and hinting may differ between renderers. Treat
+  small visual differences in glyph spacing as `MINOR` per the
+  visual accuracy contract.
+- Non-Latin scripts may require explicit font selection that the
+  PDF-safe fallback chain does not cover. When the reference uses
+  such scripts, capture the requirement in `architecture-plan.md`
+  and verify against the 1.7.0 examples before promising parity.
+- Line height and leading conventions may not match the reference's
+  source design tool exactly. If the rendered text breaks
+  differently from the reference, document the break point and
+  classify it; do not invent a "force line break here" API.
+- Decorative glyph marks (`●`, `•`, `▸`, rating dots, custom bullets)
+  no longer need a font that ships the codepoint in 1.7.0: draw them as
+  inline shapes (`dot(...)` / `shape(ShapeOutline, ...)`) per "Inline
+  figures" above. Real text still depends on font coverage — the lifted
+  caveat is only for geometry marks.
+
+## Cross-references
+
+- [`graphcompose-basics`](graphcompose-basics.md) for the role of
+  typography in the semantic model
+- [`themes-and-colors`](themes-and-colors.md) for color pairing and
+  the naming convention this skill inherits
+- [`spacing-and-alignment`](spacing-and-alignment.md) for the gaps
+  around text and the leading between lines
+- [`tables`](tables.md) for table cell typography
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  for mismatch classification
diff --git a/skills/versions/graphcompose-1.7/visual-regression.md b/skills/versions/graphcompose-1.7/visual-regression.md
new file mode 100644
index 0000000..6f37020
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/visual-regression.md
@@ -0,0 +1,205 @@
+---
+skillId: visual-regression
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Visual Regression Skill
+
+Use this skill whenever a revision's rendered output must be compared
+against the visual reference, or against the previous revision's
+output, or both. Visual regression is the discipline that turns
+"the template compiled and rendered" into "the rendered result
+matches the reference".
+
+## When to load
+
+Load this skill on every revision that produces an `output.pdf`. The
+Test + Render Agent and the Visual Review Agent both depend on it.
+Specifically:
+
+- on the first revision of a new project, to compare `output.png`
+  against `reference.png`
+- on every subsequent revision, to compare `output.png` against the
+  reference and against `previous-output.png`
+- when investigating a regression in a previously approved revision
+- when documenting an accepted limitation that requires a screenshot
+
+If the revision did not render (compile failure, render failure), do
+not load this skill yet — handle the failure under
+[`troubleshooting`](troubleshooting.md) first.
+
+## Workflow
+
+This skill mirrors the visual review loop documented in
+[`../../../docs/visual-review-loop.md`](../../../docs/visual-review-loop.md).
+Read that document for the full pipeline; the steps below are the
+skill-level summary.
+
+1. **Render the PDF.** The Test + Render Agent produces `output.pdf`
+   in the revision folder.
+2. **Generate the preview image.** Convert `output.pdf` to
+   `output.png`. The preview is what the Visual Review Agent diffs
+   against the reference; without it, the loop cannot run.
+3. **Locate the comparison inputs.** Required inputs are
+   `reference.png`, `output.png`, `visual-analysis.md`, and
+   `architecture-plan.md`. The optional input
+   `previous-output.png` is included when comparing two consecutive
+   revisions.
+4. **Compare reference vs output.** Walk through the required visual
+   parity checks in
+   [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md).
+5. **Classify every difference** using the labels in the contract.
+6. **Compare output vs previous output** when a previous revision
+   exists. Confirm the intended change was applied and no unintended
+   change was introduced.
+7. **Write `visual-review.md`** following the format in
+   [`../../../docs/visual-review-loop.md`](../../../docs/visual-review-loop.md).
+   Include the parity score, the classified mismatches, the
+   component-by-component review, and one of the three approval
+   recommendations (`APPROVE`, `REVISE`, `REJECT`).
+8. **Persist accepted limitations** as their own entries in the
+   review so future revisions inherit the context.
+
+## Reference vs output comparison
+
+The base comparison is `reference.png` vs `output.png`. The Visual
+Review Agent reviews them side-by-side, following the parity checks:
+
+- page size and orientation
+- main layout regions and visual hierarchy
+- content order and spacing
+- typography and colours
+- table proportions and structure
+- presence of headers, footers, cards, badges, backgrounds, and
+  decorations
+- absence of unexpected elements
+- pagination across all pages, page by page (see
+  [`pagination`](pagination.md))
+
+Every observation goes into `visual-review.md` as a classified
+mismatch, even when the observation is "no mismatch".
+
+## Output vs previous output comparison
+
+When a previous revision exists, the Visual Review Agent also
+compares `output.png` against `previous-output.png`. The goal is to
+catch unintended regressions:
+
+- if the user asked for a darker table and only the table darkened,
+  the comparison is clean
+- if the user asked for a darker table and the header also shifted,
+  the header shift is an unintended regression and must be classified
+- if the user asked to move the footer and the table rebroke across
+  pages, the rebroke pagination is an unintended regression
+
+Unintended regressions are mismatches against the previous revision,
+not the reference. They are classified using the same labels and they
+block approval the same way.
+
+## Difference classification
+
+The canonical classification lives in
+[`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md).
+Quoted here once for convenience — the contract is the source of
+truth:
+
+| Classification | Meaning |
+|---|---|
+| `CRITICAL` | Output does not preserve the reference structure or core meaning |
+| `MAJOR` | Significant visual difference visible immediately |
+| `MINOR` | Small spacing, color, typography, or alignment issue |
+| `ACCEPTED_LIMITATION` | Difference caused by known API/tooling limitation |
+| `INTENTIONAL_DIFFERENCE` | Difference explicitly requested or approved by user |
+
+Approval rule, also from the contract: a revision is approvable only
+when no critical mismatches remain, no unaccepted major mismatches
+remain, and minor mismatches and limitations are documented. The
+visual review's approval recommendation is advisory — only the
+Revision Manager Agent flips the revision status.
+
+## Screenshot-level comparison process
+
+For tight comparison the Visual Review Agent works at screenshot
+level: matching crops of the reference and the output. The
+recommended discipline:
+
+- compare overall structure first (page-level)
+- then compare per region (header, hero, table, footer)
+- then compare per component (a single card, a single badge)
+- record every difference, no matter how small, before classifying
+
+Per-region screenshots may be attached to `visual-review.md` to
+support classification. They are not required, but they make later
+revisions easier to triage.
+
+## Accepted-limitation documentation
+
+When a mismatch is unavoidable for the current GraphCompose version,
+the renderer, or the available fonts, document it as
+`ACCEPTED_LIMITATION` in `visual-review.md`. Required fields:
+
+- the location on the page (which region, which component)
+- a short description of the difference
+- the reason it is accepted (renderer, font fallback, API gap)
+- the classification (`ACCEPTED_LIMITATION`)
+- a link to the related skill or fixture, when applicable
+
+Accepted limitations carry forward to subsequent revisions. The
+Visual Review Agent re-checks them on every revision; if a later
+GraphCompose version closes the gap, the limitation is removed and
+the difference is reclassified.
+
+## Required visual checks before approval
+
+Before recommending `APPROVE` the Visual Review Agent must confirm:
+
+- every required parity check in
+  [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  has been visited
+- no `CRITICAL` mismatch is open
+- no `MAJOR` mismatch is open unless explicitly accepted by the user
+- all `MINOR` mismatches are listed
+- all `ACCEPTED_LIMITATION` entries are listed with their reason
+- pagination has been verified page by page (see
+  [`pagination`](pagination.md))
+- `output.pdf`, `output.png`, `layout-snapshot.json`, and
+  `visual-review.md` all exist
+
+If any of those is missing, the recommendation is `REVISE` or
+`REJECT`, not `APPROVE`.
+
+## Common mistakes
+
+1. **Comparing only the first page.** Multi-page documents must be
+   reviewed page by page; see [`pagination`](pagination.md).
+2. **Silently rounding a `MAJOR` mismatch down to `MINOR`** because
+   the layout is "mostly right". Classification is strict.
+3. **Skipping the output-vs-previous comparison.** Unintended
+   regressions are common after revisions; they must be checked.
+4. **Treating a missing artifact as cosmetic.** A missing `output.png`
+   blocks approval; it is not a documentation issue.
+
+## Known limitations
+
+- Pixel-perfect parity is not guaranteed. Anti-aliasing, font
+  hinting, and PDF-to-PNG conversion all introduce sub-millimetre
+  noise that is `MINOR` at most.
+- This workflow does not currently mandate an automated diff
+  threshold. Comparison is human-led; the per-region screenshots are
+  the most reliable check.
+
+## Cross-references
+
+- [`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+  — canonical classification and approval rule
+- [`../../../docs/visual-review-loop.md`](../../../docs/visual-review-loop.md)
+  — full review pipeline and `visual-review.md` template
+- [`pagination`](pagination.md) — page-by-page review requirements
+- [`revision-discipline`](revision-discipline.md) — how visual review
+  decisions feed into revision status
+- [`troubleshooting`](troubleshooting.md) — what to do when the
+  output cannot be produced at all
diff --git a/skills/versions/graphcompose-1.7/visual-to-graphcompose-mapping.md b/skills/versions/graphcompose-1.7/visual-to-graphcompose-mapping.md
new file mode 100644
index 0000000..6a49aae
--- /dev/null
+++ b/skills/versions/graphcompose-1.7/visual-to-graphcompose-mapping.md
@@ -0,0 +1,120 @@
+---
+skillId: visual-to-graphcompose-mapping
+targetLibrary: GraphCompose
+targetVersion: 1.7.x
+verifiedAgainst: 1.7.0
+status: needs-validation
+lastValidated: 2026-06-07
+---
+
+# Visual to GraphCompose Mapping Skill
+
+Use this skill when converting a screenshot, mockup, PDF preview, or visual reference into a GraphCompose template.
+
+## Core rule
+
+Do not start from coordinates.
+
+Start from semantic document structure.
+
+## Mapping rules
+
+| Visual element | Use GraphCompose primitive |
+|---|---|
+| Top header | RowBuilder |
+| Hero block | SectionBuilder |
+| Invoice/item table | TableBuilder |
+| Repeated card | reusable private render method |
+| Accent strip | section accent / shape container |
+| Background panel | section background / soft panel |
+| Floating badge | LayerStack |
+| Icon with semantic label | Iconify-sourced asset + semantic container |
+| Overlapping decorative element | LayerStack / CanvasLayer |
+| Exact geometric decoration | Shape container |
+| Multi-page content | pageFlow + pagination |
+| Repeated page header | header/footer/chrome |
+| Data-driven content | DocumentTemplate<T> |
+| Visual-only pixel detail | CanvasLayer only as last resort |
+
+## Decision rule
+
+Prefer semantic GraphCompose DSL first.
+
+Use low-level drawing only when:
+
+- the element is purely decorative
+- the DSL cannot represent it cleanly
+- the visual reference requires exact geometry
+- the low-level element is isolated and documented
+
+When the reference contains icons and the exact source is unknown,
+search/select replacements through [Iconify](https://iconify.design/)
+and record the icon set/name in `visual-analysis.md` or
+`architecture-plan.md`. Do not invent an icon asset or silently draw a
+rough substitute with low-level shapes unless the visual review
+documents that limitation.
+
+## When to load
+
+Load this skill whenever a reference image is being analyzed. That
+includes:
+
+- new generation tasks where the user supplies a screenshot, mockup,
+  or PDF preview
+- revisions where the user points to a region of the reference and
+  asks for a change
+- visual review work where the output preview is being compared back
+  against the reference
+
+The Visual Analyzer Agent and the Architecture Mapper Agent both
+depend on this skill. If a task does not involve a visual reference
+(for example, refactoring an existing template's data model), this
+skill can be skipped.
+
+This skill chains naturally into
+[`layout-primitives`](layout-primitives.md) for the per-primitive
+decisions and into [`tables`](tables.md) when the reference contains
+tabular content.
+
+## Common mistakes
+
+The mapping table above is only useful if the agent avoids the
+following recurring failures.
+
+- Starting from coordinates instead of semantics. The agent looks at
+  the reference, picks an x/y position, and reaches for a canvas
+  primitive before asking "what does this region mean?" Always
+  classify the region semantically first, then map it through the
+  table above.
+- Dropping into the canvas layer too early. A canvas layer is the
+  last resort, not the first option. Most reference elements
+  (headers, panels, tables, badges) are expressible with the
+  documented primitives. If an early draft is canvas-heavy, the
+  semantic pass was skipped.
+- Inventing primitives. If the table above does not list a primitive
+  that matches the visual element, the agent must not invent a new
+  builder name. Instead, decompose the element into the closest
+  documented primitives and document the gap in `visual-review.md`.
+  See the no-invented-API rule in
+  [`../../../docs/versioned-skills.md`](../../../docs/versioned-skills.md).
+- Mixing rows and tables. A horizontal arrangement of unrelated
+  items (logo plus address plus QR code) is a row, not a one-row
+  table. A grid of cells with shared column meaning is a table, not
+  a stack of rows. See [`tables`](tables.md) for when the table
+  primitive is the wrong tool.
+- Forgetting the layer stack option for overlaps. When a badge sits
+  on top of a card, or a watermark sits behind content, the answer
+  is a layer stack, not fake spacing or absolute positioning. Layer
+  stack work is detailed in the parallel-lane
+  `layer-stacks-and-overlays.md` skill.
+
+## Output expectation
+
+When this skill is in play, the Architecture Mapper Agent must
+produce an `architecture-plan.md` whose Component Mapping section
+labels every region with the chosen primitive from the table above.
+Regions that cannot be cleanly mapped must be flagged as Visual
+Risks in the same plan, not silently lowered to canvas drawing. The
+visual accuracy contract in
+[`../../../docs/visual-accuracy-contract.md`](../../../docs/visual-accuracy-contract.md)
+requires these decisions to be auditable.
diff --git a/tools/preview-renderer/README.md b/tools/preview-renderer/README.md
index a65124a..8160379 100644
--- a/tools/preview-renderer/README.md
+++ b/tools/preview-renderer/README.md
@@ -64,8 +64,8 @@ java -jar target/preview-renderer.jar render \
   --page 0
 ```
 
-GraphCompose 1.6.7 ships through Maven Central as `io.github.demchaav:graph-compose:1.6.7`.
-The expected jar name is `graph-compose-1.6.7.jar` (resolved by Maven from
+GraphCompose 1.7.0 ships through Maven Central as `io.github.demchaav:graph-compose:1.7.0`.
+The expected jar name is `graph-compose-1.7.0.jar` (resolved by Maven from
 `https://repo1.maven.org/maven2`), and the canary classpath check looks for
 `com.demcha.compose.document.api.DocumentSession` inside it. Pre-1.6.7 pins
 continue to resolve via JitPack as `com.github.DemchaAV:GraphCompose:vX.Y.Z`
diff --git a/tools/preview-renderer/pom.xml b/tools/preview-renderer/pom.xml
index 000ab4c..3fb1281 100644
--- a/tools/preview-renderer/pom.xml
+++ b/tools/preview-renderer/pom.xml
@@ -13,7 +13,7 @@
     <maven.compiler.target>21</maven.compiler.target>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <pdfbox.version>3.0.3</pdfbox.version>
-    <graphcompose.version>1.6.7</graphcompose.version>
+    <graphcompose.version>1.7.0</graphcompose.version>
     <junit.version>5.10.2</junit.version>
   </properties>
 
diff --git a/tools/preview-renderer/src/test/resources/sample-revision.json b/tools/preview-renderer/src/test/resources/sample-revision.json
index 39c597b..335909b 100644
--- a/tools/preview-renderer/src/test/resources/sample-revision.json
+++ b/tools/preview-renderer/src/test/resources/sample-revision.json
@@ -4,7 +4,7 @@
   "status": "DRAFT",
   "userRequest": "Create an A4 invoice template from the reference image.",
   "targetGraphComposeVersion": "1.6.0",
-  "skillPack": "skills/versions/graphcompose-1.6",
+  "skillPack": "skills/versions/graphcompose-1.7",
   "changedComponents": [
     "Header",
     "Hero",
diff --git a/tools/revision-manager/src/commands/init.ts b/tools/revision-manager/src/commands/init.ts
index 0709e20..128fef4 100644
--- a/tools/revision-manager/src/commands/init.ts
+++ b/tools/revision-manager/src/commands/init.ts
@@ -35,8 +35,8 @@ import {
 } from '../paths.js';
 import type { Revision, TemplateProject } from '../types.js';
 
-const DEFAULT_TARGET_VERSION = '1.6.0';
-const DEFAULT_SKILL_PACK = 'skills/versions/graphcompose-1.6';
+const DEFAULT_TARGET_VERSION = '1.7.0';
+const DEFAULT_SKILL_PACK = 'skills/versions/graphcompose-1.7';
 
 /** Template name -> example directory (relative to repo root) that backs it. */
 const TEMPLATE_REGISTRY: Record<string, string> = {
diff --git a/tools/revision-manager/test/commands/init.test.ts b/tools/revision-manager/test/commands/init.test.ts
index e240b9f..84c9b64 100644
--- a/tools/revision-manager/test/commands/init.test.ts
+++ b/tools/revision-manager/test/commands/init.test.ts
@@ -128,8 +128,8 @@ async function buildFakeRepo(root: string): Promise<void> {
       projectName: 'invoice-reference',
       referenceImage: 'reference/reference.png',
       referenceDescription: 'reference/reference.md',
-      targetGraphComposeVersion: '1.6.7',
-      skillPack: 'skills/versions/graphcompose-1.6',
+      targetGraphComposeVersion: '1.7.0',
+      skillPack: 'skills/versions/graphcompose-1.7',
       currentApprovedRevisionId: 'revision-003',
       currentDraftRevisionId: null,
       createdAt: '2026-05-18T12:00:00Z',
@@ -162,8 +162,8 @@ async function buildFakeRepo(root: string): Promise<void> {
       parentRevisionId: null,
       status: 'DRAFT',
       userRequest: 'Create an A4 invoice template from the reference image.',
-      targetGraphComposeVersion: '1.6.7',
-      skillPack: 'skills/versions/graphcompose-1.6',
+      targetGraphComposeVersion: '1.7.0',
+      skillPack: 'skills/versions/graphcompose-1.7',
       changedComponents: ['Header', 'Footer'],
       createdAt: '2026-05-18T12:30:00Z',
       artifacts: { template: 'generated-template.java' },
diff --git a/tools/revision-manager/test/projectStore.test.ts b/tools/revision-manager/test/projectStore.test.ts
index 6b758f9..144cef6 100644
--- a/tools/revision-manager/test/projectStore.test.ts
+++ b/tools/revision-manager/test/projectStore.test.ts
@@ -26,7 +26,7 @@ describe('projectStore', () => {
     const project: TemplateProject = {
       projectName: 'sample',
       targetGraphComposeVersion: '1.6.0',
-      skillPack: 'skills/versions/graphcompose-1.6',
+      skillPack: 'skills/versions/graphcompose-1.7',
       currentApprovedRevisionId: null,
       currentDraftRevisionId: null,
       createdAt: nowIso(),
diff --git a/tools/skill-validation-cache/README.md b/tools/skill-validation-cache/README.md
index c7cb303..fb74e01 100644
--- a/tools/skill-validation-cache/README.md
+++ b/tools/skill-validation-cache/README.md
@@ -52,21 +52,21 @@ Three properties of the key:
 ```bash
 # 1. Compute the key (no I/O)
 skill-validation-cache key \
-  --target io.github.demchaav:graph-compose:1.6.7 \
+  --target io.github.demchaav:graph-compose:1.7.0 \
   --skills layout-primitives,tables,themes-and-colors \
-  --skill-pack skills/versions/graphcompose-1.6
+  --skill-pack skills/versions/graphcompose-1.7
 
 # 2. Look it up (exit 0 = hit + JSON entry on stdout; exit 1 = miss)
 skill-validation-cache lookup \
-  --target io.github.demchaav:graph-compose:1.6.7 \
+  --target io.github.demchaav:graph-compose:1.7.0 \
   --skills layout-primitives,tables,themes-and-colors \
-  --skill-pack skills/versions/graphcompose-1.6
+  --skill-pack skills/versions/graphcompose-1.7
 
 # 3. Store after a real validation run (reportBody from stdin or file)
 cat skill-validation-report.md | skill-validation-cache store \
-  --target io.github.demchaav:graph-compose:1.6.7 \
+  --target io.github.demchaav:graph-compose:1.7.0 \
   --skills layout-primitives,tables,themes-and-colors \
-  --skill-pack skills/versions/graphcompose-1.6 \
+  --skill-pack skills/versions/graphcompose-1.7 \
   --verdict pass
 
 # 4. List cache contents
diff --git a/validation/api-compatibility-checklist.md b/validation/api-compatibility-checklist.md
index 4477e00..590f801 100644
--- a/validation/api-compatibility-checklist.md
+++ b/validation/api-compatibility-checklist.md
@@ -7,39 +7,44 @@ been executed, and which skills are still pending validation.
 
 ## Header
 
-- Target GraphCompose version: `1.6.7` (manifest declares
-  `defaultGraphComposeVersion: 1.6.x`; coordinate is now
-  `io.github.demchaav:graph-compose:1.6.7` from Maven Central).
-- Skill manifest version: `0.2.0` (see
+- Target GraphCompose version: `1.7.0` (manifest declares
+  `defaultGraphComposeVersion: 1.7.x`; coordinate is
+  `io.github.demchaav:graph-compose:1.7.0` from Maven Central).
+- Skill manifest version: `0.3.0` (see
   [../skills/skill-manifest.json](../skills/skill-manifest.json)).
-- Status: fixture smoke re-passed on 2026-06-01 against
-  `io.github.demchaav:graph-compose:1.6.7` from Maven Central
-  (5 fixtures × 1 test each, all green) — see
-  [reports/fixture-smoke-2026-06-01.md](reports/fixture-smoke-2026-06-01.md).
-  The original 2026-05-18 smoke against `v1.6.0` via JitPack remains
-  archived at [reports/fixture-smoke-2026-05-18.md](reports/fixture-smoke-2026-05-18.md).
-  Full render/preview/visual-diff validation is still pending, so
-  manifest statuses remain `needs-validation`.
-- Last reviewed: 2026-06-01.
+- Status: the render-only fixture smoke re-passed on 2026-06-07
+  against `io.github.demchaav:graph-compose:1.7.0` from Maven Central
+  (5 fixtures rendered to non-empty PDF/PNG via
+  `node scripts/validate-skills.mjs --render-only`, all green). 1.7.0
+  is additive over 1.6.x (zero breaking changes), so the earlier 1.6.x
+  compile/smoke lineage carries forward: the 2026-06-01 re-smoke
+  against `1.6.7` is archived at
+  [reports/fixture-smoke-2026-06-01.md](reports/fixture-smoke-2026-06-01.md),
+  and the original 2026-05-18 smoke against `v1.6.0` via JitPack at
+  [reports/fixture-smoke-2026-05-18.md](reports/fixture-smoke-2026-05-18.md).
+  Full render/preview/visual-diff validation (pixel parity vs committed
+  baselines) is still pending, so manifest statuses remain
+  `needs-validation`.
+- Last reviewed: 2026-06-07.
 
 ## Per-skill table
 
 | Skill ID | Target version | Status | Fixture exists | Fixture executed | Drift detected | Last validated |
 |---|---|---|---|---|---|---|
-| graphcompose-basics | 1.6.7 | needs-validation | no | no | unknown | 2026-06-01 |
-| visual-to-graphcompose-mapping | 1.6.7 | needs-validation | no | no | unknown | 2026-06-01 |
-| layout-primitives | 1.6.7 | needs-validation | yes | yes, smoke (re-passed 2026-06-01 vs Central) | no compile drift; visual pending | 2026-06-01 |
-| tables | 1.6.7 | needs-validation | yes | yes, smoke (re-passed 2026-06-01 vs Central) | no compile drift; visual pending | 2026-06-01 |
-| themes-and-colors | 1.6.7 | needs-validation | yes | yes, smoke (re-passed 2026-06-01 vs Central) | no compile drift; visual pending | 2026-06-01 |
-| typography | 1.6.7 | needs-validation | no | no | unknown | 2026-06-01 |
-| spacing-and-alignment | 1.6.7 | needs-validation | no | no | unknown | 2026-06-01 |
-| backgrounds-and-panels | 1.6.7 | needs-validation | yes | yes, smoke (re-passed 2026-06-01 vs Central) | no compile drift; visual pending | 2026-06-01 |
-| layer-stacks-and-overlays | 1.6.7 | needs-validation | yes | yes, smoke (re-passed 2026-06-01 vs Central) | no compile drift; visual pending | 2026-06-01 |
-| shapes-and-containers | 1.6.7 | needs-validation | yes | yes, smoke (re-passed 2026-06-01 vs Central) | no compile drift; visual pending | 2026-06-01 |
-| pagination | 1.6.7 | needs-validation | no | no | unknown | 2026-06-01 |
-| visual-regression | 1.6.7 | needs-validation | no | no | unknown | 2026-06-01 |
-| revision-discipline | 1.6.7 | needs-validation | no | no | unknown | 2026-06-01 |
-| troubleshooting | 1.6.7 | needs-validation | no | no | unknown | 2026-06-01 |
+| graphcompose-basics | 1.7.0 | needs-validation | no | no | unknown | 2026-06-01 |
+| visual-to-graphcompose-mapping | 1.7.0 | needs-validation | no | no | unknown | 2026-06-01 |
+| layout-primitives | 1.7.0 | needs-validation | yes | yes, render-only smoke (re-passed 2026-06-07 vs 1.7.0 Central) | no compile drift; visual pending | 2026-06-07 |
+| tables | 1.7.0 | needs-validation | yes | yes, render-only smoke (re-passed 2026-06-07 vs 1.7.0 Central) | no compile drift; visual pending | 2026-06-07 |
+| themes-and-colors | 1.7.0 | needs-validation | yes | yes, render-only smoke (re-passed 2026-06-07 vs 1.7.0 Central) | no compile drift; visual pending | 2026-06-07 |
+| typography | 1.7.0 | needs-validation | no | no | unknown | 2026-06-01 |
+| spacing-and-alignment | 1.7.0 | needs-validation | no | no | unknown | 2026-06-01 |
+| backgrounds-and-panels | 1.7.0 | needs-validation | yes | yes, render-only smoke (re-passed 2026-06-07 vs 1.7.0 Central) | no compile drift; visual pending | 2026-06-07 |
+| layer-stacks-and-overlays | 1.7.0 | needs-validation | yes | yes, render-only smoke (re-passed 2026-06-07 vs 1.7.0 Central) | no compile drift; visual pending | 2026-06-07 |
+| shapes-and-containers | 1.7.0 | needs-validation | yes | yes, render-only smoke (re-passed 2026-06-07 vs 1.7.0 Central) | no compile drift; visual pending | 2026-06-07 |
+| pagination | 1.7.0 | needs-validation | no | no | unknown | 2026-06-01 |
+| visual-regression | 1.7.0 | needs-validation | no | no | unknown | 2026-06-01 |
+| revision-discipline | 1.7.0 | needs-validation | no | no | unknown | 2026-06-01 |
+| troubleshooting | 1.7.0 | needs-validation | no | no | unknown | 2026-06-01 |
 
 Fixture-to-skill coverage notes for the five fixtures under
 [../examples/skill-fixtures/](../examples/skill-fixtures/):
diff --git a/validation/skill-fix-template.md b/validation/skill-fix-template.md
index 32ef6cf..4e7be28 100644
--- a/validation/skill-fix-template.md
+++ b/validation/skill-fix-template.md
@@ -11,7 +11,7 @@ in inside the copied report file.
 
 ## Affected skill
 
-`skills/versions/graphcompose-1.6/tables.md`
+`skills/versions/graphcompose-1.7/tables.md`
 
 ## GraphCompose version
 
@@ -62,7 +62,7 @@ FAILED / NEEDS UPDATE / FIXED
    validation run report or from
    [api-compatibility-checklist.md](api-compatibility-checklist.md).
 5. Update the affected skill file under
-   `../skills/versions/graphcompose-1.6/` and set the matching entry
+   `../skills/versions/graphcompose-1.7/` and set the matching entry
    in [../skills/skill-manifest.json](../skills/skill-manifest.json)
    to `failed-validation` until the fix lands, then to `active`
    once the fixture re-runs cleanly.