sevgi-appendix 0.98.2

data/README.md

@@ -0,0 +1,115 @@
+# Sevgi Appendix
+
+Sevgi Appendix packages development extras for the Sevgi SVG DSL: an agent skill and RuboCop rules for readable
+`.sevgi` source. Installing the umbrella `sevgi` gem installs the matching Appendix version. A project that only needs
+the development extras can install this package separately:
+
+```sh
+gem install sevgi-appendix
+```
+
+## Require
+
+The package version is available without loading RuboCop:
+
+```ruby
+require "sevgi/appendix"
+```
+
+## Agent skill
+
+For a complete user installation, install Sevgi with Homebrew on macOS or Linux:
+
+```sh
+brew install roktas/tap/sevgi
+```
+
+Locate the skill without guessing a Homebrew prefix or Cellar version:
+
+```sh
+sevgi --skill
+```
+
+The command prints one validated absolute path and nothing else. It fails if the installed `sevgi-appendix` version
+does not match Sevgi or its `SKILL.md` is missing. Homebrew reports a stable path below its `opt` tree, so an agent's
+skill directory may safely link to it. Homebrew keeps that path current across upgrades.
+
+Coding agents look for skills in different directories. Paste this prompt into the agent you want to configure:
+
+> Run `sevgi --skill`. Install the reported directory as a user-level skill named `sevgi` using this agent product's
+> supported skill location. Use a symbolic link because this is a stable Homebrew path. Report the destination and
+> whether a new session is required.
+
+When the umbrella `sevgi` gem was installed through RubyGems or Bundler, the same query works, including inside a
+bundle:
+
+```sh
+bundle exec sevgi --skill
+```
+
+Gem paths contain the package version and can disappear after an upgrade. Copy the complete reported directory into
+the agent's skill location instead of keeping a long-lived symbolic link, then repeat the copy after updating Sevgi.
+The skill uses progressive disclosure to route an agent through the DSL, SVG rendering semantics, Geometry and
+Sundries helpers, Derender, and output workflows.
+
+## RuboCop
+
+Add the gem to development dependencies when the umbrella gem is not already present:
+
+```ruby
+gem "sevgi-appendix", require: false
+```
+
+Then enable the plugin in `.rubocop.yml`:
+
+```yaml
+plugins:
+  - sevgi-appendix
+```
+
+Run RuboCop through the application's bundle:
+
+```sh
+bundle exec rubocop
+```
+
+The plugin adds `*.sevgi` files to RuboCop and checks the DSL's deliberate source shape: optional parentheses are
+omitted from statement-like calls, one-line blocks use braces, multiline blocks use `do`/`end`, and strings use double
+quotes. Parentheses remain valid where Ruby needs them or they clarify a compact chained expression.
+
+### With rubyfmt
+
+`rubyfmt` remains authoritative for ordinary Ruby. Keep `.sevgi` files hand-formatted and let Sevgi Appendix inspect
+their DSL-specific shape:
+
+```yaml
+inherit_gem:
+  rubocop-rubyfmt:
+    - config/full.yml
+
+plugins:
+  - rubocop-rubyfmt
+  - sevgi-appendix
+```
+
+Add the scripts to `.rubyfmtignore` so `rubyfmt` does not erase the shape the plugin protects:
+
+```text
+*.sevgi
+**/*.sevgi
+```
+
+## Ruby compatibility
+
+Requires Ruby 3.4.0 or newer. CI verifies the current Ruby 3.4 release and the development Ruby from `.ruby-version`.
+
+## Native prerequisites
+
+This gem needs only Ruby and its Ruby dependencies.
+
+## Links
+
+- Documentation: <https://sevgi.roktas.dev>
+- API documentation: <https://www.rubydoc.info/gems/sevgi-appendix>
+- Source: <https://github.com/roktas/sevgi/tree/main/appendix>
+- Changelog: <https://github.com/roktas/sevgi/blob/main/CHANGELOG.md>

data/agents/skills/sevgi/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: sevgi
+description: Create, edit, review, and debug SVG drawings written with the Sevgi Ruby DSL. Use for `.sevgi` scripts, Ruby code that builds SVG with Sevgi, reusable drawing modules, editor-authored SVG/XML integration through Derender, PDF or PNG export, visual regressions, or requests to express an SVG design through Sevgi rather than raw XML.
+---
+
+# Sevgi
+
+Sevgi is first a Ruby DSL: write idiomatic Ruby that describes SVG while preserving SVG semantics and the user's
+visible intent.
+
+## Core Contract
+
+1. **Delegate rendering to SVG.** Before calculating any value that affects appearance, decide who owns that result. If
+   SVG can express the intent and the final value depends on renderer knowledge, encode the intent in SVG and let the
+   renderer resolve it. Use Ruby or `Sevgi::Geometry` only for information the program genuinely must derive. Read
+   [drawing.md](references/drawing.md) before adding rendering-related arithmetic.
+2. **Fix the cause, not the symptom.** Treat the visible result as the acceptance criterion. Trace a mismatch through
+   drawing geometry, viewport, transforms, styles, strokes, and renderer behavior; fix the layer that owns the faulty
+   contract. Do not hide it with empty margins, oversized frames, clipping, non-uniform scaling, or a one-case offset.
+3. **Stay native to Sevgi.** Use SVG elements through the Sevgi DSL and prefer Sevgi's existing Graphics, Geometry,
+   Sundries, and Function helpers where they fit. Do not generate raw SVG/XML, another graphics format, or an
+   intermediate string and then convert it into Sevgi. Use Derender only when existing SVG/XML is a genuine input
+   artifact.
+
+## Workflow
+
+1. Determine the host and installed dependency surface: executable `.sevgi` script, full-toolkit Ruby library, or a
+   focused component. Read [dsl.md](references/dsl.md) for its grammar and facade boundaries.
+2. Choose the component that owns each nontrivial operation. Read [toolkit.md](references/toolkit.md) before writing a
+   project-local substitute for a Sevgi helper.
+3. Structure data, control flow, and reuse as ordinary Ruby while preserving the DSL shape. Read
+   [ruby.md](references/ruby.md).
+4. Identify the owner of each visual result before writing arithmetic, offsets, or scaling. Read
+   [drawing.md](references/drawing.md), and use [svg.md](references/svg.md) when SVG may own the behavior.
+5. Read [layout.md](references/layout.md) for repetition, tiling, alignment, rulers, grids, drawing, or hatching.
+6. For editor-authored SVG/XML, `igves` prints Sevgi source and `igsev` round-trips to normalized SVG; both accept files
+   or standard input. Read
+   [derender.md](references/derender.md). For PDF/PNG output, read [output.md](references/output.md).
+7. Before introducing a Sevgi word or signature not established by nearby code or the loaded references, verify it in
+   the DSL catalog or owning YARD. Do not infer an API from an English name or use `Element` to bypass an unknown
+   operation.
+8. Write the smallest clear Sevgi expression. Keep case-sensitive, normally lowercase-leading SVG element calls,
+   capitalized Sevgi operations, ordinary Ruby control flow, and SVG attributes visibly distinct. Do not mechanically
+   parenthesize statement-like DSL calls.
+9. Render and inspect the actual output in each context it claims to support. Compare visible bounds and density—not
+   only canvas or DOM dimensions. For size, alignment, clipping, density, or visual-regression evidence, read
+   [inspection.md](references/inspection.md) and identify the measurement space before choosing a tool.
+10. Re-read the finished source for raw-XML detours, avoidable calculations, magic offsets, duplicated helpers, and
+    stale artifacts.
+
+## References
+
+| Need | Read |
+| --- | --- |
+| Choose script/library syntax, profiles, SVG elements, or Sevgi DSL words | [dsl.md](references/dsl.md) |
+| Choose a component and locate user, YARD, or checkout documentation | [toolkit.md](references/toolkit.md) |
+| Structure `.sevgi` and library code as idiomatic Ruby | [ruby.md](references/ruby.md) |
+| Apply the renderer/program ownership boundary; diagnose visual mismatches | [drawing.md](references/drawing.md) |
+| Measure SVG geometry, browser layout, or painted pixels | [inspection.md](references/inspection.md) |
+| Find an SVG capability and its authoritative specification | [svg.md](references/svg.md) |
+| Choose repetition, tiling, ruler, grid, Draw, pattern, or Hatch | [layout.md](references/layout.md) |
+| Integrate editor-authored SVG/XML through Derender | [derender.md](references/derender.md) |
+| Render, save, or export SVG, PDF, or PNG | [output.md](references/output.md) |

data/agents/skills/sevgi/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Sevgi"
+  short_description: "Create SVG with the Sevgi DSL"
+  default_prompt: "Use $sevgi to create an SVG drawing with the Sevgi DSL."

data/agents/skills/sevgi/references/derender.md

@@ -0,0 +1,81 @@
+# Derender
+
+## Purpose
+
+Some vector geometry is better authored in a visual editor than programmed: a Bezier-heavy logo, traced illustration,
+or hand-adjusted path may be correct as artwork but impractical as handwritten Ruby. Derender brings that SVG/XML into
+the Sevgi element model so editor-authored geometry can participate in Ruby-driven composition, styling, layout, and
+output. This combines both workflows without pretending every path should originate in code.
+
+Do not use Derender as a detour for ordinary shapes or relationships that are clearer in the Sevgi DSL. Use it when
+SVG/XML is a real input artifact.
+
+## Choose the Relationship
+
+| Intent | Inline content | File | Result |
+| --- | --- | --- | --- |
+| Inspect an immutable parsed node | `SVG.Decompile` | `SVG.DecompileFile` | `Sevgi::Derender::Node` |
+| Generate editable Sevgi Ruby source | `SVG.Derender` | `SVG.DerenderFile` | formatted Ruby String |
+| Add the selected node to an existing tree | `SVG.Evaluate` | `SVG.EvaluateFile` | included element or `nil` |
+| Add only the selected node's children | `SVG.EvaluateChildren` | `SVG.EvaluateChildrenFile` | frozen child snapshot |
+| Include a selected file node inside an SVG block | — | `Include` | included element or `nil` |
+| Include only a selected file node's children inside a block | — | `IncludeChildren` | frozen child snapshot |
+
+Use `DerenderFile` when generated Ruby should become the maintained source. Use `Include`, `EvaluateFile`, or their
+children variants when the editor file should remain the source of its geometry. Use `DecompileFile` to inspect names,
+attributes, namespaces, metadata, and children before choosing. Choose one maintained representation; do not keep
+changing both editor SVG and generated Sevgi as parallel sources.
+
+Keep the editor file as the geometry source and compose a selected group in Sevgi:
+
+```ruby
+SVG :minimal do
+  Include "brand.svg", "logo", omit: :id
+end.Save "badge.svg"
+```
+
+Add inline content to an existing document by passing the target explicitly:
+
+```ruby
+drawing = SVG :minimal
+SVG.Evaluate '<circle id="mark" r="4"/>', drawing, omit: :id
+drawing.Render
+```
+
+Generate Ruby for review and integration into the maintained source instead:
+
+```ruby
+source = SVG.DerenderFile "brand.svg", id: "logo", omit: :id
+puts source
+```
+
+At the command line, `igves` prints generated Sevgi source. Use `igsev` from the umbrella gem only when the intended
+result is normalized SVG produced by a complete SVG-to-Sevgi-to-SVG round trip. Both commands accept repeatable
+`--omit ATTRIBUTE` and read standard input when the file is omitted or `-`; `igsev` is a structural formatter, not a
+byte-preserving XML rewrite.
+
+A selected subtree may produce a fragment rather than a standalone `.sevgi` script. Review the conversion, then place
+it inside the document or callable module that owns it; do not merely rename an arbitrary fragment to `.sevgi`.
+
+## Selection and Cleanup
+
+- Give reusable editor groups stable IDs and select one with `id:`. `Include` takes that ID as its second positional
+  argument.
+- Inspect an SVG tree with `SVG.DecompileFile` (or component-level `Sevgi::Derender.decompile_file`) before falling back
+  to text search. Grep can mistake editor helpers, generated IDs, metadata, or unrelated layers for reusable artwork.
+- Use `omit:` with one String/Symbol or an Array of exact, case-sensitive attribute names. Selection happens before
+  omission, so the selecting ID can be removed.
+- Namespace declarations remain intact, and omitting the `style` attribute does not remove `style` elements. Omit
+  style, transform, or geometry attributes only when their behavior is intentionally replaced.
+- Expect paths and other low-level editor geometry to remain low-level. Derender preserves the SVG tree; it cannot
+  reconstruct the loops, modules, or design operations that originally created it.
+- Treat parsing and executing as separate trust boundaries. Derender parses XML as data and direct evaluation builds
+  graphics elements without executing generated Ruby. Execute generated source only when it is trusted code.
+- After renaming or removing a selected id or source path, update its consumers, regenerate derived drawings, and check
+  for stale references.
+
+Script mode uses bare names such as `DerenderFile`; library mode uses the `SVG.` facade. Component-only consumers use
+the lowercase `Sevgi::Derender` methods and `_file` variants.
+
+Read the [Derender guide](https://sevgi.roktas.dev/derender/) for the complete workflow and
+[`sevgi-derender` YARD](https://www.rubydoc.info/gems/sevgi-derender) for exact signatures and failure contracts.

data/agents/skills/sevgi/references/drawing.md

@@ -0,0 +1,79 @@
+# Drawing Discipline
+
+## Renderer First
+
+Treat SVG as the rendering model, not merely as an output format. The governing question is not whether Ruby *can*
+calculate a value, but which layer has the knowledge and responsibility to determine it.
+
+Use this ownership boundary:
+
+| Owner | Test | Action |
+| --- | --- | --- |
+| SVG renderer | SVG can state the intent and the final result depends on rendering context | Encode the intent with SVG elements, attributes, CSS, or transforms |
+| Sevgi | Sevgi already names the SVG operation or supplies the required layout abstraction | Use the DSL or helper instead of rebuilding it |
+| Program | The value must exist before rendering and SVG neither derives nor exposes it | Compute it with ordinary Ruby or `Sevgi::Geometry` |
+
+Before computing, first ask whether SVG can state the desired relationship rather than its current numeric result. If
+it can, keep that relationship declarative. Then check whether Sevgi already wraps it. Compute only when the program
+needs geometry or data that the renderer cannot provide as part of the supported workflow.
+
+Geometry is appropriate for constructed points and lines, intersections, bounds consumed by later algorithms, sweeps,
+and hatching. It is not a parallel rendering engine.
+
+## Example: Preserve the Ownership Boundary
+
+The Showcase Ruler illustrates the general rule; it does not introduce a text-specific recipe. The desired relationship
+is “center each label on this tick,” while the rendered width of a label depends on font metrics known by the SVG
+renderer.
+
+Computing a guessed width in Ruby takes ownership away from the renderer:
+
+```ruby
+(10..(WIDTH - 10)).step(10).each_with_index do |x, i|
+  label = (i + 1).to_s
+  estimated_width = label.length * 4 * 0.6
+  text label, x: x - (estimated_width / 2), y: length + 5.5, class: "labels"
+end
+```
+
+Instead, keep the tick coordinate and express the relationship in SVG:
+
+```ruby
+(10..(WIDTH - 10)).step(10).each_with_index do |x, i|
+  label = (i + 1).to_s
+  text label, x:, y: length + 5.5, "text-anchor": "middle", class: "labels"
+end
+```
+
+The broader lesson is to encode the stable relationship and leave context-dependent rendering values to the renderer.
+Apply that reasoning before introducing measured compensations or Geometry objects solely to imitate rendering.
+
+## Root-Cause Review
+
+When a drawing looks wrong, inspect these contracts separately:
+
+1. **Source geometry:** coordinates, intervals, repetition counts, and intended visible bounds.
+2. **Layout framing:** content bounds, margins, alignment, and repetition policy.
+3. **Viewport:** `width`, `height`, `viewBox`, and `preserveAspectRatio`.
+4. **Painting:** stroke width, line caps/joins, fill, opacity, filters, and CSS cascade.
+5. **Transforms:** order, origin, inherited transforms, and duplicated translations.
+6. **Environment:** font availability, renderer support, output size, and theme-specific styles.
+
+Fix the first contract that is false. Do not make a frame larger to hide unequal content, add whitespace to simulate
+alignment, clip an overflow caused by wrong geometry, or use a special-case offset that only matches one label or
+viewport.
+
+Verify every rendering context the artifact claims to support. For browser assets this may include representative
+desktop/mobile widths and light/dark themes; for print output it may include page sizes and an independent PDF renderer.
+Equal SVG dimensions or DOM boxes do not prove equal visible size.
+
+## Layout Changes
+
+Treat the viewport, visible drawing bounds, and visual density as separate contracts. When changing a canvas, grid, or
+repeated layout, reconsider interval counts, hatch spacing, margins, and stroke weights together instead of scaling one
+number mechanically.
+
+For a drawing parameterized across sizes or profiles, check representative extremes and nearby values that share the
+same layout rule. Judge actual whitespace, visual balance, row and column counts, clipping, and perceived density.
+Rounding or repetition changes can fix one variant while regressing another. Do not use an offset to hide a wrong
+geometry, interval, or viewport model.

data/agents/skills/sevgi/references/dsl.md

@@ -0,0 +1,99 @@
+# DSL Map
+
+## Host Grammar
+
+| Form | Meaning |
+| --- | --- |
+| `rect`, `circle`, `linearGradient`, `clipPath`, ... | Standard SVG elements created directly by exact, case-sensitive names; they normally start lowercase |
+| `Translate`, `Tile`, `Call`, `Render`, ... | Sevgi operations, normally capitalized to stand apart from SVG elements |
+| `css`, `layer`, `layer!`, `base` | Deliberate lowercase Sevgi words; `base` belongs to callable-module definitions |
+| `SVG(...)` | Build a document in both script and library code |
+| `SVG.Canvas(...)` | Call a full-toolkit facade operation in library code |
+| `SVG::Canvas` | Refer to a type or namespace |
+| `Canvas(...)` | Call the promoted operation in an executable `.sevgi` script |
+
+Use Ruby hashes for SVG attributes. Quote hyphenated SVG names:
+
+```ruby
+text "Ready", x: 12, y: 16, "text-anchor": "middle", "font-weight": "bold"
+```
+
+## Dependency Surface
+
+| Host | Load | Vocabulary |
+| --- | --- | --- |
+| Executable script | `ruby -S sevgi` through the `.sevgi` shebang | bare promoted operations such as `Canvas`, `Paper`, and `Grid` |
+| Full-toolkit library | `require "sevgi"` | `SVG(...)` plus facade operations such as `SVG.Canvas` and `SVG.Grid` |
+| Focused graphics library | `require "sevgi/graphics"` | `Sevgi::Graphics.SVG` and lowercase component constructors; no full `SVG` facade |
+
+Follow the consumer's declared gems and existing dialect. Do not require the full toolkit merely to obtain facade
+spelling, and do not use facade operations when only a focused component is installed.
+
+## Minimal Forms
+
+Executable script:
+
+```ruby
+#!/usr/bin/env -S ruby -S sevgi
+
+canvas = Canvas width: 24, height: 24, unit: :px
+
+SVG :minimal, canvas do
+  circle cx: 12, cy: 12, r: 10, fill: "tomato"
+end.Save "badge.svg"
+```
+
+Ruby library:
+
+```ruby
+require "sevgi"
+
+canvas = SVG.Canvas width: 24, height: 24, unit: :px
+drawing = SVG(:minimal, canvas) { circle cx: 12, cy: 12, r: 10, fill: "tomato" }
+
+File.write "badge.svg", drawing.Render
+```
+
+## Paper, Canvas, and Document
+
+Keep physical size and serialization dialect independent:
+
+| Need | Use | Owns |
+| --- | --- | --- |
+| Register or look up a named physical size | `SVG.Paper` / script `Paper` | width, height, and unit |
+| Build one drawing surface | `SVG.Canvas` / script `Canvas` | size, margins, unit, name, and resulting `viewBox` |
+| Define or select an SVG document profile | `SVG.Document` / script `Document` | root attributes and preambles |
+
+The first argument to `SVG` selects a document profile; the optional second argument supplies a canvas. Use an
+anonymous `Document` for one-off metadata and a named profile only for shared process-wide vocabulary.
+Prefer non-bang registration; use `Paper!` or `Document!` only for an intentional overwrite.
+
+## Task-to-Word Map
+
+| Task | Start with |
+| --- | --- |
+| Create SVG structure | SVG element names; nest containers with blocks |
+| Choose page dimensions and document metadata | `Paper`, `Canvas`, `Document`; keep their responsibilities separate |
+| Set reusable styles | `css`, classes, presentation attributes |
+| Transform an element or group | `Translate`, `Rotate`, `Scale`, `Skew`, `Flip` |
+| Center known inner and outer boxes | element `Align`; use `Sevgi::Geometry::Operation` for edge alignment or a Ruby result |
+| Draw simple line/path wrappers | `LineTo`, `LineBy`, `HLineTo`, `HLineBy`, `VLineTo`, `VLineBy` |
+| Reuse or repeat drawing | `defs`/`use`, `Tile`, `TileX`, `TileY`, `Duplicate` |
+| Compose reusable drawing code | `SVG::Module`, `base`, `Call`; profile-specific `Group`, `Layer`, `Layer!`, `Symbols` |
+| Move existing element trees | `Append`, `Prepend`, `Adopt`, `AdoptFirst`, `Orphan` |
+| Draw or hatch Geometry values | `Draw`, `Hatch` on `:inkscape` or an explicitly extended custom profile |
+| Inspect or validate output | `Identifiers`, `Validate`, `Lint` |
+| Produce output | `Render`, `Out`, `Save`; optional `PDF` and `PNG` export |
+| Import existing SVG/XML | `Include`, `Evaluate`, `Derender`, `Decompile` and their file variants |
+
+## Profiles
+
+| Profile | Use |
+| --- | --- |
+| `:minimal` | SVG without default preamble or namespace metadata |
+| `:default` | Standalone SVG with XML declaration and SVG namespace |
+| `:html` | SVG intended for HTML embedding |
+| `:inkscape` | Editor metadata plus convenient `Draw` and `Hatch` helpers |
+
+Do not invent a Sevgi word from a likely name. Check the [online DSL catalog](https://sevgi.roktas.dev/dsl/) for
+executable examples and the appropriate YARD component reference for exact arguments and return values.

data/agents/skills/sevgi/references/inspection.md

@@ -0,0 +1,82 @@
+# Inspection
+
+Measure rendered output only when the acceptance criterion requires evidence about size, alignment, clipping, density,
+or a visual regression. Measurement is diagnostic evidence, not permission to copy observed coordinates back into the
+DSL as compensating offsets. Use the evidence to locate the faulty source, viewport, layout, paint, transform, or
+environment contract, then fix that owner.
+
+## Choose the Evidence
+
+State the question before selecting a tool:
+
+| Question | Evidence | Space |
+| --- | --- | --- |
+| Is the declared coordinate model correct? | `viewBox`, viewport dimensions, `preserveAspectRatio` | SVG user units and viewport policy |
+| What geometry does this SVG element contain? | Browser `getBBox()` | SVG user units |
+| Where does it appear after layout and transforms? | Browser `getBoundingClientRect()` or an equivalent automation API | Viewport-relative CSS pixels |
+| What is a path's renderer-computed length or point? | `getTotalLength()` or `getPointAtLength()` | SVG user units |
+| Which pixels were actually painted? | A deterministic PNG or browser screenshot inspected as raster data | Raster pixels |
+| Does the result have the intended balance or density? | Visual inspection at representative outputs | Perceptual; no single bounding box proves it |
+
+Do not compare values from different spaces as if they shared units. Label every recorded measurement with:
+
+```text
+kind: geometry | layout | paint
+space: svg-user-unit | css-px | raster-px
+bounds: x, y, width, height
+context: renderer, viewport, DPR, theme, font state
+```
+
+## Browser Recipe
+
+Use an installed browser automation facility, preferably Playwright when available, for responsive layout, CSS, text,
+and integration-context checks.
+
+1. Open the artifact in the context that owns the reported behavior. A standalone SVG does not reproduce a host page's
+   container, inherited CSS, theme, or responsive rules.
+2. Fix the viewport, device-pixel ratio, theme, and output scale. Disable animation and wait for the page and fonts to
+   settle before measuring.
+3. Select the smallest element or group that represents the questioned content. Record its identity with the result.
+4. Read `getBBox()` for local SVG geometry and `getBoundingClientRect()` for viewport-relative layout. Use
+   `getCTM()` or `getScreenCTM()` to map points into a common space when transforms matter.
+5. Capture the same target and surrounding context. A tightly clipped element screenshot can hide incorrect margins,
+   overflow, or neighboring alignment.
+6. Repeat only the contexts covered by the drawing's contract, such as representative desktop/mobile widths and
+   light/dark themes. Use the actual target engine when diagnosing renderer-specific behavior.
+
+`getBBox()` applies geometry attributes but does not apply transforms on the element or its parents.
+`getBoundingClientRect()` is an axis-aligned CSS-pixel rectangle after layout and transforms. Do not treat either value
+as the exact painted-pixel boundary: strokes, markers, clipping, filters, font rasterization, and antialiasing may require
+raster evidence. With rotated or skewed content, transform all relevant corners instead of scaling a width and height.
+
+## Raster Recipe
+
+Use raster evidence when the question concerns visible paint, whitespace, clipping, renderer output, or a pixel-level
+regression.
+
+1. Produce a PNG at a fixed viewport or export size, device-pixel ratio, theme, font environment, and background.
+   Prefer transparency when the painted foreground must be isolated.
+2. Inspect the image visually before reducing it to numbers. Confirm that the selected image contains the intended
+   context and that no crop already concealed the defect.
+3. When ImageMagick or an equivalent tool is available, derive the occupied-pixel box from the alpha channel or a known
+   background. Record the transparency threshold or color tolerance; antialiased edge pixels make that policy part of
+   the measurement.
+4. Compare occupied bounds, edge margins, and clipping against the stated acceptance criterion. Pixel counts and boxes
+   do not measure perceived weight or balance by themselves.
+5. Use pixel diffs only with a pinned rendering environment. Font changes, renderer versions, DPR, color management,
+   and antialiasing can create noise without a source regression.
+
+For PDF evidence, first validate document structure, then rasterize representative pages through an independent
+renderer and apply the same fixed-context checks. Do not convert a raster observation into maintained drawing source.
+
+## Interpret the Result
+
+- Wrong SVG-user-unit geometry points to coordinates, repetition, transforms, or a Sevgi layout helper.
+- Correct geometry but wrong CSS-pixel placement points to the viewport, host layout, responsive CSS, or transforms.
+- Stable browser boxes but different raster bounds point to paint, clipping, filters, fonts, or renderer behavior.
+- Equal boxes with visibly unequal results point to spacing, stroke weight, contrast, or density; keep visual inspection
+  as the acceptance criterion.
+
+Do not measure routine API or source-only changes merely because a browser or image tool is available. Stop when the
+chosen evidence answers the original question; extra metrics add confidence only when they test another relevant
+contract.

data/agents/skills/sevgi/references/layout.md

@@ -0,0 +1,55 @@
+# Layout Routing
+
+Choose by the value the caller needs after the operation, not merely by the visible pattern.
+
+## Repetition
+
+| Need | Use | Result |
+| --- | --- | --- |
+| Repeat one SVG subtree in the rendered document | `defs`/`use`, or DSL `Tile`, `TileX`, `TileY` | SVG references with generated positions |
+| Copy and independently edit an existing subtree | `Duplicate`, `DuplicateX`, `DuplicateY` | Independent SVG element trees |
+| Inspect repeated cells or row/column bounds in Ruby | `Sevgi::Sundries::Tile` | Geometry values and boxes, no SVG elements |
+
+## Intervals and Grids
+
+| Need | Use |
+| --- | --- |
+| Fit whole major/minor intervals into a span and inspect their distances | `Sevgi::Sundries::Ruler` |
+| Require an even major-interval count | `Sevgi::Sundries::RulerEven` |
+| Combine two fitted rulers and obtain lines, points, cells, or a fitted canvas | `SVG.Grid` or `Sevgi::Sundries::Grid` |
+
+`Ruler` is a Ruby value, not a drawing word. `Grid` is also a Ruby layout model; `Draw` materializes its geometry as SVG
+when lines are required. In a Grid, `grid.x` returns horizontal lines and `grid.y` vertical lines—the names describe
+line direction.
+
+## Alignment
+
+| Need | Use |
+| --- | --- |
+| Center known inner and outer boxes with an SVG translation | element `Align` with `:center` |
+| Align Geometry at center or an edge and return the value or offset | `Sevgi::Geometry::Operation.align` or `Sevgi::Geometry::Operation.alignment` |
+| Align rendered text or other renderer-owned content | SVG anchoring, baseline, layout, or transform semantics |
+
+Geometry alignment accepts `:center`, `:left`, `:right`, `:top`, and `:bottom`; the element DSL's narrower `Align`
+contract accepts only `:center`. Do not calculate font or painted-content bounds merely to feed either API; use them
+when the program already owns meaningful box geometry.
+
+## Drawing and Hatching
+
+| Need | Use |
+| --- | --- |
+| A visual repeated fill whose individual strokes are irrelevant | SVG `pattern`; let the renderer repeat and clip it |
+| Explicit finite hatch segments that must remain separate geometry/SVG paths | Geometry sweep or `Hatch` |
+| Existing Geometry values rendered as SVG elements | `Draw` |
+
+`Hatch` computes finite segments and emits each as a separate SVG path. Use it for editable, inspectable, plotter-like,
+or otherwise explicit line geometry—not merely because a region should look striped. `Draw` and `Hatch` are included by
+`:inkscape`; add the Hatch mixture to another profile only when that profile deliberately owns the capability. For a
+scoped extension, subclass `SVG::Document::Base`, then call `SVG.Mixin :Hatch, profile`; targeting `Base` itself changes
+every descendant profile process-wide.
+
+Read the [Sundries guide](https://sevgi.roktas.dev/sundries/) for Ruler, Grid, and both Tile models; read
+[Geometry sweeps and hatching](https://sevgi.roktas.dev/geometry/#sweeps) for explicit hatch lines; use the
+[DSL Catalog](https://sevgi.roktas.dev/dsl/) for exact drawing words. Exact Ruby contracts live in
+[`sevgi-sundries`](https://www.rubydoc.info/gems/sevgi-sundries) and
+[`sevgi-graphics`](https://www.rubydoc.info/gems/sevgi-graphics).

data/agents/skills/sevgi/references/output.md

@@ -0,0 +1,61 @@
+# Output Routing
+
+Keep document construction and output policy separate. Choose the final operation from the artifact the caller needs:
+
+| Artifact | Use |
+| --- | --- |
+| SVG String owned by surrounding Ruby code | `Render` |
+| SVG on standard output | `Out` |
+| SVG file | `Save` |
+| PDF file | `PDF` |
+| PNG file | `PNG` |
+| Export an existing SVG String outside the document | `Sevgi::Sundries::Export.call` |
+
+The `sevgi` command reads standard input when no file is given. Use `sevgi --as badge` when an implicit `Save`, `PDF`,
+or `PNG` should derive `badge.svg`, `badge.pdf`, or `badge.png` instead of the default `output` basename. `NAME` is a
+basename, not a path; explicit destinations in the source remain authoritative.
+
+## PDF
+
+For a document, use the convenience operation:
+
+```ruby
+canvas = SVG.Canvas width: 40, height: 40, unit: :px
+drawing = SVG :minimal, canvas do
+  circle cx: 20, cy: 20, r: 16, fill: "tomato"
+end
+
+drawing.PDF "badge.pdf"
+```
+
+For an application that owns the rendered SVG and output policy separately:
+
+```ruby
+canvas = SVG.Canvas width: 40, height: 40, unit: :px
+svg = SVG(:minimal, canvas) { circle cx: 20, cy: 20, r: 16, fill: "tomato" }.Render
+Sevgi::Sundries::Export.call(svg, "badge.pdf")
+```
+
+The output suffix selects PDF when `format:` is omitted. `width:` and `height:` are export dimensions; they do not
+repair or replace the drawing's canvas, `viewBox`, or visible geometry. Fix those in the SVG document. Use `css:` only
+for deliberate export-only styling, and use `dpi:` when the CSS-pixel-to-output conversion policy must differ.
+
+SVG output has no native graphics dependency. PDF and PNG export lazily require Cairo, RSVG, and HexaPDF; report a
+missing optional component rather than replacing the path with an unrequested external command or raster workaround.
+
+## Verification
+
+Inspect the produced artifact; a successful write does not prove correct rendering. For a parameterized or multi-page
+family, start with a representative output and then check other variants affected by the same rule.
+
+For PDF output, validate document structure with `qpdf` when available, render representative pages through Poppler or
+an equivalent independent renderer, and inspect embedded fonts when fallback would change the result. Compare raster
+output only as evidence; fix discrepancies in the SVG source, export policy, or environment that owns them.
+
+Treat rendered SVGs, PDFs, PNGs, and visual snapshots as derived evidence, not implementation sources. Fix the
+maintained Sevgi or editor-owned SVG/XML source and regenerate. Update expected artifacts only for an intentional output
+change, then review the visible diff before accepting it.
+
+Read [Sundries export](https://sevgi.roktas.dev/sundries/#export) for installation and examples, and
+[`Sevgi::Sundries::Export`](https://www.rubydoc.info/gems/sevgi-sundries/Sevgi/Sundries/Export) for exact dimensions,
+options, return paths, and errors.