@hraness/slopcamera 3.2.4

package/skills/slopcamera/references/reference-led-3d.md

@@ -0,0 +1,140 @@
+# Reference-led Three.js and metallic treatments
+
+Use this guide only when Slopcamera's complete local Code Mode host is available.
+It ships in this repository alongside the thin desktop capture shell. The
+portable `@hraness/slopcamera/code` and `@hraness/slopcamera/workflow`
+entrypoints intentionally expose no HTML renderer, Three.js operation, or
+arbitrary source execution. Those capabilities belong to the local host.
+
+## Separate reference generation from source execution
+
+An image model may supply a visual reference. It must not supply executable
+authority.
+
+1. Generate or select one reference image and preserve its exact artifact
+   record.
+2. Inspect the subject, silhouette, palette, proportions, negative space, and
+   intended polygon character.
+3. Run `slopcamera html scaffold three --output <scene.html>`. The command does
+   not overwrite an existing source.
+4. Edit only the scaffold's `createSubject()` region unless the requested
+   camera, lights, or timing require a reviewed change elsewhere.
+5. Run Code Mode checks and render a full-length 1x preview.
+6. Inspect the first, middle, and last frame plus at least two useful angles.
+7. Change the checked scene source, not a rendered frame. Render a final target
+   only after selection.
+
+Do not collapse those stages into an operation that accepts JavaScript text.
+Local Code Mode is trusted local code with the current user's authority. It
+is not a sandbox. The reviewed physical source and its imports enter the graph
+identity before an effect can execute.
+
+## Bind the reference to the reviewed scene
+
+In a local Code Mode module, use the typed helper with the image artifact
+and its projected media type:
+
+```ts
+const generated = workflow.gateway.image("reference", imageOptions);
+const reference = generated.select("outputs").at(0);
+const binding = createThreeReferenceScaffoldInput(
+  reference,
+  reference.select("mediaType"),
+);
+const scene = workflow.media.htmlOverlay("scene", {
+  ...binding,
+  document: { path: "overlays/reviewed-scene.html" },
+  canvas: { deviceScaleFactor: 1, height: 1080, width: 1920 },
+  parameters: { explode: 0.35, orbitTurns: 1, zoom: 1 },
+  project,
+  range: { startUs: 0, endUs: 3_000_000 },
+  timing: { durationUs: 3_000_000, fps: 30 },
+});
+```
+
+The resource binding verifies path, bytes, SHA-256, and media type. A mismatch
+fails before the browser render. The reference remains execution provenance
+even when the final scene does not display it.
+
+If the scene uses the reference as a color texture, load only its declared
+private URL and settle decoding before frame zero:
+
+```js
+const texture = new THREE.TextureLoader()
+  .loadAsync(SlopcameraOverlay.asset("reference-image"))
+  .then((loaded) => {
+    loaded.colorSpace = THREE.SRGBColorSpace;
+    return loaded;
+  });
+SlopcameraOverlay.ready(texture);
+```
+
+Never load a remote URL, data URL, object URL, undeclared font, environment map,
+or model file from scene code.
+
+## Preserve deterministic motion
+
+- Derive every visible state from `progress`, `timeMs`, parameters, or
+  `SlopcameraOverlay.randomFor(key)`.
+- Do not use `requestAnimationFrame`, `setAnimationLoop`, wall-clock time,
+  mutable random sequences, pointer input, or cumulative per-frame state.
+- Create geometry, materials, textures, vectors, matrices, and arrays before
+  `onFrame`. Avoid allocation and asset loading inside the frame callback.
+- Keep the first and last frame loop-compatible when the result is a loop.
+- Use one `renderer.render(scene, camera)` call per frame unless a reviewed
+  multipass effect justifies the extra cost.
+
+## Keep generated Three.js inexpensive
+
+The starter defaults to 64 draw calls and 200,000 triangles per frame. Keep
+those ceilings unless the user chooses a measured exception.
+
+- Reuse geometry and materials. Use `THREE.InstancedMesh` for repeated forms.
+- Prefer flat-shaded primitives, indexed `BufferGeometry`, and a few deliberate
+  lights for low-poly subjects.
+- Leave shadows, postprocessing, physics, environment maps, logarithmic depth,
+  and high-detail subdivisions off by default.
+- Fit the camera from `Box3` or a bounding sphere rather than hand-tuning it for
+  one output ratio.
+- Keep opaque objects opaque. Preserve alpha in the renderer and background,
+  rather than making every material transparent.
+- Track every geometry, material, texture, and render target. Dispose them and
+  the renderer when the page closes.
+- Set color textures to `THREE.SRGBColorSpace`. Leave normal, roughness, metal,
+  and other data textures in their default no-color space.
+- Use a 1x canvas for the full-duration preview. A selected final may raise
+  device scale or destination dimensions. Do not shorten the preview to hide a
+  late-frame failure.
+
+Compare output at each destination aspect ratio. Camera fit, negative space,
+caption-safe areas, and transparent edges can fail even when the source scene
+is valid.
+
+## Create a metallic logo candidate
+
+Use the supplied logo image as the sole shape authority. The treatment has
+three literal creative variables: brand name, background color, and object
+color. Model selection is separate because image-reference support changes by
+provider.
+
+```ts
+const candidate = workflow.gateway.image("metallic-logo",
+  createMetallicLogoImageRequest({
+    backgroundColor: "warm gray",
+    brandName: "Hraness",
+    model: input.imageModel,
+    objectColor: "brushed cobalt",
+    reference: input.logo,
+  }));
+```
+
+For direct local CLI use, choose a live image model that accepts reference
+images, then pass the exact logo with `--image` and the required
+`--allow-cloud-upload`. Inspect model capabilities before dispatch. Do not
+silently upload a local brand asset.
+
+Treat every output as a candidate. Reject it when the silhouette, negative
+space, proportions, orientation, or existing lettering changes. Reject added
+text, duplicated marks, invented symbols, cropped edges, implausible bevels,
+dirty reflections, or a background that contaminates the mark. Preserve the
+reference and prompt receipt beside an accepted derivative.

package/skills/slopcamera/references/rubber-stamp-field-notes.md

@@ -0,0 +1,144 @@
+# Rubber-stamp travel field notes
+
+Use this when the user wants travel photos turned into «橡皮章旅行田野笔记»
+posters: photograph on the left, a small multi-color rubber-stamp vignette and
+typewriter field notes on warm paper on the right.
+
+Reference look: https://x.com/Hamburgerai/status/2090683415104557406
+
+Do **not** ask a generative model to redraw the whole poster. Keep the source
+photograph as real pixels. Generate only the stamp (and optionally a stamp-on-paper
+crop), then assemble with the local compositor.
+
+## Inputs
+
+Per poster, collect:
+
+- one absolute path to the source photograph;
+- place name in English (`VENICE`, `ROME`, …);
+- serial number (`01`, `02`, …);
+- three short English keywords joined with ` / `;
+- year (`2026` unless the user names another).
+
+If the user does not supply place / keywords / year, derive them from the photo
+and say what you assumed. Never invent a brand slogan.
+
+## Layout contract
+
+- One independent poster per photo. No multi-photo collage.
+- Aspect ratio **4:3** landscape (default `1600×1200`).
+- Left ≈ **58%**: the source photo, cover-cropped. Preserve subject identity,
+  terrain, architecture, plants, people, spatial relationships, natural light,
+  real texture, and the photo's color character. Only restrained publication-grade
+  grading and a touch of fine film grain are allowed. Natural crop for the frame
+  is fine; never stretch, warp, move, replace, or redraw the subject.
+- Right ≈ **42%**: warm off-white aged paper with fiber, matte feel, and generous
+  unprinted blank space. No hard vertical divider.
+- Stamp sits mid-lower on the paper, about **30–38%** of the right panel's height,
+  with ample margin. It is a small rubber stamp, not a full illustration, logo, or
+  landscape painting.
+
+## Stamp generation (Gateway only)
+
+Generate **only** the stamp vignette (square-ish, on transparent or warm paper),
+using a current image model that accepts a reference photo. Prefer
+`bfl/flux-kontext-pro` when available; otherwise discover with
+`slopcamera ai models list --type image --json` and pick a reference-capable model.
+
+Write the brief to a prompt file. Example shape:
+
+```text
+Using the attached travel photograph as the only reference, create ONE small
+multi-color rubber-stamp vignette of this place for a field notebook.
+
+Compress the scene into the least information needed to recognize the location:
+keep the dominant silhouette, a few stepped color blocks, and key terrain / shore /
+road relationships. Delete crowds, cars, dense windows, repeated buildings,
+busy foliage, and decorative clutter.
+
+2–4 spot-ink colors sampled from the photo after desaturation (charcoal, deep
+green, brick, ochre, gray-blue, gray-brown). One small accent color only.
+
+Each color layer must look hand-carved and hand-stamped: uneven hatch, broken
+edges, dry ink, paper show-through, pressure variation, slight 1–2mm misregistration.
+Not a smooth vector logo, not a filtered photo, not a full landscape painting.
+
+Center the stamp on a warm off-white paper square with generous blank margin.
+No typewriter text in this image. No Chinese seals, round postmarks, stamp
+perforations, wax seals, stickers, or collage.
+```
+
+Pass the source photo first, then one packaged style reference from
+`references/rubber-stamp-examples/stamp-style-1.png` (or
+`references/rubber-stamp-examples/stamp-style-2.png`)
+so the model copies the hand-stamped ink language without copying that place.
+
+Resolve the version-matched packaged skill inside each executable shell step.
+Do not assume the current directory is a Slopcamera source checkout or use the
+agent runner's copied skill path. The [source installation](install.md) supplies `SLOPCAMERA_SOURCE_ROOT`; restore that exact checkout in a new shell. Vercel launches the built Bun entrypoint because it cannot execute the source-install shell function. Run through the linked Vercel project:
+
+```sh
+skill_root="$(slopcamera skill path)"
+vercel env run -- bun "$SLOPCAMERA_SOURCE_ROOT/apps/desktop/dist/cli/main.js" ai image generate \
+  --model bfl/flux-kontext-pro \
+  --prompt-file stamp-brief.txt \
+  --image /absolute/source-photo.png \
+  --image "$skill_root/references/rubber-stamp-examples/stamp-style-1.png" \
+  --aspect-ratio 1:1 \
+  --allow-cloud-upload \
+  --json --timeout 180s
+```
+
+Remux awkward JPEGs to PNG first if Slopcamera's FFprobe rejects them. If Gateway
+decode validation fails but bytes exist under `artifacts/slopcamera/generated/…`,
+inspect the file; a valid image may still be usable after a local remux.
+
+## Compose with code
+
+Assemble the final poster with the packaged compositor so the photograph stays
+literal:
+
+```sh
+skill_root="$(slopcamera skill path)"
+bun "$skill_root/scripts/compose-rubber-stamp-field-note.ts" \
+  --photo /absolute/source-photo.jpg \
+  --stamp /absolute/generated-stamp.png \
+  --output /absolute/field-note.jpg \
+  --place "VENICE" \
+  --number "01" \
+  --keywords "brick / bell / lagoon" \
+  --year "2026"
+```
+
+The compositor cover-crops the photo into the left panel, draws warm paper on
+the right, places the stamp mid-lower, and sets typewriter text beneath it:
+
+```text
+PLACE
+No. NN
+keyword / keyword / keyword
+YEAR
+```
+
+Use a small monospace face. Keep the copy like a traveler's field record, not
+an advertisement.
+
+## Avoid
+
+Hard center dividers, round Chinese seals, postage perforations, wax seals,
+sticker collage, souvenir templates, smooth vector city icons, full rebuilds of
+every building, dense carving, cartoon or child-craft looks, 3D plastic renders,
+smooth digital gradients, oversaturation, excess copy, decorative pile-up, and
+any redraw of the left-side photograph.
+
+## Save and show
+
+- Prefer `/home/box/media/images/slopcamera/YYYY-MM-DD-<place-slug>-field-note.jpg`
+  for Slopcamera library copies.
+- Show the finished poster to the user.
+- Keep the stamp artifact and receipt for iteration.
+
+## Batch
+
+Process one photo at a time. Reuse the same serial numbering scheme across a
+trip. Do not stitch multiple photos into one poster unless the user asks.

package/skills/slopcamera/references/vectorization.md

@@ -0,0 +1,29 @@
+# Vectorize raster artwork
+
+When the user asks to convert caller-owned raster artwork to SVG, keep the
+raster as the source and treat the SVG as a replaceable derivative:
+
+```sh
+slopcamera image vectorize path/to/input.png --output path/to/input.svg --json
+```
+
+- Do not provide a credential for vectorization. The conversion keeps image bytes local; the initial tool provisioning can download a verified VTracer release.
+- Do not redraw, relabel, crop, recolor, or simplify the subject beyond the
+  trace mechanics the command measures.
+- Use `--duotone '#primary,#secondary'` only when the user explicitly asks for
+  that two-color adaptation.
+- Preserve the emitted receipt in task output or an adjacent provenance record
+  when auditability matters.
+- Do not bypass input, decoded-pixel, duration, path, byte, or fidelity gates.
+- Inspect the SVG at its intended size. A successful trace is not evidence
+  that an unfamiliar symbol communicates the intended concept.
+
+VTracer downloads from its checksum-pinned official release on first use. Use
+`SLOPCAMERA_VTRACER_PATH` only for a compatible local 0.6.4 binary; Slopcamera still
+records its hash. Never add an upscaling model, embedded raster fallback, or
+commercial font to make a trace pass.
+
+Bounded vectorization is currently supported on macOS and Linux. On Windows,
+report the deliberate `tool_platform` failure; do not bypass it with an
+unbounded temporary output file.
+

package/skills/slopcamera/references/video-projects.md

@@ -0,0 +1,187 @@
+# Edit a video project
+
+Use this workflow for screen recordings, talking-head videos, product demos,
+imported camera or audio takes, captions, motion layers, creative alternatives,
+and multi-format delivery. Slopcamera records editing decisions in a local project
+and leaves original media unchanged.
+
+## Define the finished result
+
+Before editing, identify:
+
+- the source recording or existing project;
+- the intended audience and approximate duration;
+- what should be removed, emphasized, or left untouched;
+- whether the project needs generated images, video, speech, or transcripts;
+- the required captions, logo, overlays, music, and audio treatment; and
+- the final aspect ratios and clean or captioned versions.
+
+Ask only when a missing choice would materially change the edit. Do not invent
+brand assets, remove content merely to make the video shorter, or select a creative alternative outside the user’s supplied criteria.
+
+## Inspect the host and project
+
+Run these before building exact commands:
+
+```sh
+slopcamera doctor --json
+slopcamera recordings list --json
+slopcamera projects list --json
+slopcamera workflows list --json
+```
+
+Use `slopcamera inspect <recording> --json` for a recording bundle and
+`slopcamera project inspect <project> --json` for a project. Read IDs, streams,
+placements, synchronization, analyses, and current edit state from those
+results. Never guess them.
+
+Check the bootstrap before promising a file-only edit. There is no public empty-project or arbitrary-media project creator: `projects create` requires a real stopped Slopcamera recording, and `project add` / SDK `media.ingest` require an existing project. Current-source `studio assemble` creates one from a real successful native sequence; `direct assemble` uses accepted generated takes. Neither is a generic file import. Do not fabricate recording manifests or receipts, run paid generation to obtain an empty project, or hand-edit private state. If the request permits, use a standalone spatial scene for visuals and disclose any separate local audio/editor step; otherwise report the missing project bootstrap precisely.
+
+If the work begins with a new Slopcamera recording, create the project from that
+recording, then add any independent footage or audio:
+
+```sh
+slopcamera projects create --from-recording <recording-id> --name '<name>' --json
+slopcamera project add <project-id> camera.mov --role camera --json
+slopcamera project add <project-id> narration.wav --role dialogue --json
+```
+
+Imported media begins with unverified synchronization. When timing with another
+track matters, inspect and apply audio alignment before cuts, filler removal,
+camera moves, or rendering depend on it.
+
+## Analyze before changing the edit
+
+Use only the evidence the requested edit needs:
+
+- `slopcamera analyze inactivity` for long still or silent ranges;
+- `slopcamera analyze speech` and `slopcamera fillers list` for words and safe filler
+  candidates;
+- `slopcamera analyze faces` and `slopcamera faces list` for local face geometry used
+  by framing;
+- `slopcamera analyze music` before applying filler removal that must protect music;
+- `slopcamera analyze scenes` for scene boundaries or bounded scene descriptions;
+  and
+- recording events for cursor, click, keystroke, focused-input, and typed-text
+  timing.
+
+Face analysis is local geometry tracking, not recognition. Scene descriptions
+upload only selected derived frames and require `--allow-cloud-upload`.
+Speech analysis may use the configured local Whisper runtime; Gateway
+transcription is the separate workflow in
+[gateway-media.md](gateway-media.md).
+
+## Make non-destructive editorial changes
+
+Run `slopcamera help project` for the current grammar. The project editor supports:
+
+- cuts, trims, and speed changes in project time;
+- camera push, reframe, arbitrary camera paths, and local face-follow framing;
+- screen zooms tied to a rectangle, point, cursor, window, or focused input;
+- cursor, click, keystroke, and typed-text presentation;
+- direct image, SVG, GIF, video and emoji overlays;
+- captions and interaction metadata; and
+- captions, clean outputs, and captioned outputs.
+
+Preserve the original recording and imported media. Apply changes to the
+project or its editable scene source, then inspect the resulting project hash.
+When an edit depends on evidence, use the evidence identifier returned by its
+analysis rather than recomputing or approximating it.
+
+Direct `project edit` does not accept HTML or arbitrary audio/color filters. Render HTML/Canvas/Three/WGSL through the local workflow `media.htmlOverlay` operation, then use its returned video as a project layer. `media audio` and `media color` produce separate controlled derivatives.
+
+Overlay `--position x,y` is an offset from its selected anchor. Use `--anchor center --position 0,0` to center a layer, or `--anchor top-left --position 42,70` for an actual top-left pixel position. A full-frame overlay uses top-left at `0,0`. Do not add half the canvas dimensions to center offsets.
+
+For independently authored media, explicit `project add --at` timing may be appropriate. Rendering with `--allow-unverified-sync` acknowledges provisional synchronization; it does not turn authored times into measured alignment. Finish ordinary edits before V2 spatial migration, because ordinary editing rejects the migrated head.
+
+## Choose one HTML authoring surface
+
+Run `slopcamera html catalog` before creating a transparent HTML overlay. Choose the
+profile by its primary job:
+
+- `plain` for document layout, CSS, SVG, and native browser drawing;
+- `motion` for seekable DOM or SVG choreography;
+- `p5` for an immediate-mode Canvas 2D sketch;
+- `two` for a retained vector 2D scene;
+- `paper-shaders` for a parameterized texture or gradient;
+- `three` for a retained 3D scene; and
+- `vgpu` for explicit WGSL, compute, or pass-level GPU control.
+
+Slopcamera owns the clock and declared assets in every profile. Keep p5 in P2D instance
+mode with an empty startup draw, `noLoop()`, and one awaited `redraw()`. Keep
+Two.js on its explicit WebGL renderer with `autostart: false` and one manual
+`render()`. Derive all visible state from the absolute Slopcamera frame and
+`SlopcameraOverlay.randomFor`; never add a CDN, live input, ambient asset loader, or
+second frame loop.
+
+## Use vgpu for explicit WebGPU effects
+
+Choose `slopcamera html scaffold vgpu --output <file.html>` for a reviewed fullscreen
+WGSL effect or a composition that needs explicit WebGPU passes. The
+starter is one transparent pass; extend its checked source for bounded
+multipass work instead of introducing a second animation clock.
+
+- Derive motion from the absolute `timeMs` supplied by `SlopcameraOverlay.onFrame`.
+- Submit explicit `frame()` passes and wait for both frame completion and GPU
+  settlement before the callback resolves.
+- Keep the transparent clear and premultiplied-alpha contract intact.
+- Expect the render to fail closed when WebGPU or its adapter is unavailable;
+  do not add a silent Canvas, WebGL, or static-image fallback.
+
+Prefer Motion for DOM animation, Paper Shaders for its existing texture and
+gradient treatments, and Three.js for full 3D scenes. vgpu is not a reason to
+rewrite an overlay that already fits one of those paths.
+
+## Prefer a built-in workflow for a complete known job
+
+Inspect the exact input schema with
+`slopcamera workflows show <id> --json` before preparing its JSON input.
+
+- `talking-head-cleanup` removes long pauses, keeps local face evidence, and
+  renders a final landscape talking-head video.
+- `polished-screen-demo` analyzes inactivity, screen actions, faces, and
+  music before applying cleanup, interaction effects, and face-aware framing.
+- `chaptered-demo` adds a reviewed overlay composition and renders an exact
+  final video.
+- `social-variants` renders 16:9, 9:16, 1:1, and 4:5 branches, with clean and
+  optional captioned outputs.
+- `creative-iteration` makes two to sixteen independent preview candidates
+  from one frozen project.
+- `creative-selection` records an explicit human or task selection, promotes
+  it when requested, and materializes named deliveries.
+
+Read [workflows and SDK](workflows-sdk.md) for custom Bun authoring, exact plan approval and durable recovery. The seventh built-in, `directed-scene`, consumes prepared V2 scene render inputs.
+
+Plan a workflow before running it. Do not choose or promote a creative
+candidate unless the user has selected it or the request supplies a
+deterministic selection rule.
+
+## Preview before final delivery
+
+For substantial edits:
+
+1. inspect the current project;
+2. plan or apply the requested edits;
+3. render the complete timeline at preview quality;
+4. inspect picture, sound, captions, transitions, framing, and the first and
+   last frames;
+5. revise the project, not the preview file; and
+6. render final outputs from the selected project state.
+
+Ordinary project render `--output` paths are relative to that project’s directory. Under the default workspace, `--output renders/final.mp4` means `artifacts/slopcamera/projects/<project-id>/renders/final.mp4`. Resolve returned relative receipt paths against that project, not the shell directory.
+
+Preview and final use the same timeline and composition. A preview is evidence
+about the final edit, but still check the final file's duration, dimensions,
+streams, and output path.
+
+## Report the creative result
+
+Tell the user:
+
+- which recording or project was edited;
+- what was generated, analyzed, removed, added, or reframed;
+- which decisions remain alternatives rather than the current project state;
+- the preview path they can review;
+- every final output path and aspect ratio; and
+- any upload, model, synchronization, or local-tool limitation that affected
+  the result.

package/skills/slopcamera/references/visual-communication.md

@@ -0,0 +1,120 @@
+# Slopcamera visual communication rules
+
+Use these rules to turn supplied content into a diagram without adding content.
+
+## Start with the claim
+
+A diagram should make one relationship, comparison, sequence, or hierarchy easy
+to perceive. Write down that supplied claim privately before placing shapes.
+Every primary mark must help the viewer perceive it. Remove marks that merely
+repeat styling.
+
+Keep the semantic inventory small:
+
+- Three to seven primary objects is a useful default for a high-level overview.
+- A viewer should be able to name the reading order after a quick glance.
+- Labels should normally be one to three words. Use a second diagram when the
+  only way to fit the content is paragraph-sized labels.
+
+These are compression rules, not permission to omit facts the user explicitly
+asked to show.
+
+## Make visual grammar consistent
+
+Similarity implies shared meaning. Proximity implies grouping. Alignment implies
+relationship. Encode those implications deliberately:
+
+- Equal roles use equal geometry and treatment.
+- A size change must encode a supplied magnitude or hierarchy.
+- A color change must encode a supplied category or state.
+- A different shape must encode a different kind of object.
+- Group with whitespace and position before adding a new enclosing border.
+- Do not mix rounded and hard corners for peers.
+
+When appearance varies without a reason, a viewer spends attention searching
+for a distinction that does not exist.
+
+## Route relationships clearly
+
+Connectors need room to be seen as connectors.
+
+- Keep at least 96px of visible connector between shape boundaries; prefer
+  120–200px.
+- Bind each semantic arrow to its source and target.
+- Point arrowheads into open space at the target edge.
+- Avoid crossings. If a crossing is unavoidable, change the layout before
+  adding bridge decorations.
+- Keep connector labels short and off the path.
+- Separate repeated fan-in and fan-out arrowheads with distinct endpoint
+  positions. A shared side-center port makes several relationships look like
+  one heavy or broken connector.
+- Looking from a source toward a target, positive bend is on the viewer's
+  right side of the chord and negative bend is on the left. For a
+  left-to-right chord, that means positive bends down and negative bends up.
+  Reverse paired signs when branches should bow toward their open interior.
+- Do not use an arrow where proximity or containment already states the
+  relationship.
+
+Longer arrows are the default because a short arrow can collapse into the
+neighboring strokes and make two objects look like one component.
+
+## Use icons as recognition cues
+
+- Use one icon family and one stroke language in a diagram.
+- Keep peer icons the same optical size.
+- Render an icon bare inside its existing card or shape.
+- Do not add a second bordered icon container inside a bordered card.
+- Pair an icon with a short label when the glyph is not universally understood.
+- Never let an icon introduce a fact absent from the prompt.
+
+## Build hierarchy without prose
+
+Use position, whitespace, and restrained contrast before size or saturation.
+Make the important path visually continuous. Keep supporting objects quieter.
+Avoid shadows, gradients, textures, and ornamental strokes unless they encode
+requested meaning.
+
+When one supplied object contains two distinct text roles, use measured label
+rows rather than punctuation or manual vertical offsets. A compact mono row can
+name a type, identifier, or relation while a larger default-family row carries
+the human-readable value. Keep peer rows consistent and center the complete
+icon, gaps, and wrapped line boxes as one group.
+
+Use one color distinction by default. When the supplied system contains stable
+roles across several diagrams, a restrained family palette can reduce relearning:
+
+- blue for sources, evidence, and observed records;
+- purple for proposed structure, transforms, or system-generated candidates;
+- yellow for named-human review or authority;
+- green for accepted, versioned, or published outputs;
+- red or orange for correction, retraction, or failure; and
+- neutral for ordinary supporting objects.
+
+Use only the roles the content actually supplies. Preserve the same mapping
+throughout the diagram family, and keep text or icons sufficient when color is
+unavailable.
+
+For light and dark variants:
+
+- Preserve the same geometry and semantic contrast.
+- Test text and thin strokes against their immediate background.
+- Do not encode meaning only by hue.
+- Keep axis and connector strokes single and opaque enough to avoid a faint
+  inner-line effect.
+
+## Sources behind the rules
+
+These defaults synthesize established work rather than copying a house style:
+
+- Gestalt principles of proximity, similarity, continuity, and enclosure.
+- Colin Ware, *Information Visualization: Perception for Design*, on
+  preattentive features and visual queries.
+- Stephen Kosslyn, *Graph Design for the Eye and Mind*, on perceptual grouping
+  and correspondence between visual marks and meaning.
+- Richard Mayer's coherence principle: exclude extraneous material that
+  competes with the intended explanation.
+- Barbara Tversky's work on spatial representations and diagrams as external
+  structures for inference.
+
+The practical test is semantic: if a visual difference makes a reasonable
+viewer infer a difference that the prompt did not supply, remove it.