@stacksjs/defaults 0.75.361 → 0.75.366

package/ai/skills/stacks-technical-diagrams/references/authoring-defaults.md

@@ -0,0 +1,57 @@
+# Authoring defaults
+
+Read once before writing a fresh candidate. An existing frozen candidate going straight to `finalize` needs this only if repair changes its authorship.
+
+## Composition and meaning
+
+For Architecture, default to a system overview led by the main user journey unless the user asks for a narrower mechanism, module map, or deployment topology. Group cooperating roles in accurately named subsystems when that still explains the requested interaction. Separate roles when grouping would hide control ownership, a trust or persistence boundary, lifecycle behavior, or another distinction the reader asked about. Keep secondary and opt-in capabilities in concise sourced notes unless their path matters to the requested question. Name a deliberately narrower scope in the title.
+
+Preserve every requested responsibility, relationship direction, protocol, and behavior-changing condition. Show approval, authorization, and state-transition gates on the affected node or relationship; a card alone cannot qualify an otherwise unconditional arrow. Keep source evidence with each asserted claim. Boundaries express real isolation, ownership, runtime, or persistence facts. Cards answer additional reader questions; they do not replace required topology. There is no node, edge, source, card, or boundary quota. If an authored overview needs regrouping after failure, use [Composition repair](authoring-contract.md#composition-repair); user-supplied or agreed topology remains fixed.
+
+Relationship labels carry meaning. Give them clear space and preserve action, protocol, direction, async behavior, or cross-boundary meaning. Where the mode schema permits an absent label, omit it only when both endpoints already fully imply it; a collision calls for spacing or routing repair. See [Label repair](authoring-contract.md#label-repair) when measured evidence reports a collision.
+
+## Layout and routing
+
+Place Architecture nodes by their actual connections before assigning coordinates; the router cannot rearrange boxes, so placement decides whether lines stay straight. Classify each relationship first, then place:
+
+- **Main path**: the reader's main journey, neighbors adjacent in reading order. Let a medium path step through meaningful rows instead of making a shallow horizontal strip.
+- **Branch or store**: directly above or below the node that owns, reads, or writes it, centered on that node so the edge is one straight segment. Keep all stores and branches of one row on the same side of it.
+- **Return** (back to an earlier main-path node): put its source on the side of the main path with no branches or stores, so it runs through an empty corridor instead of crossing them.
+- **Second entrance** into a node that already has an incoming edge: place the new source so it reaches that node from another side, usually directly below or above it.
+- **Fan-out**: a side with k relationships needs at least `32 + 14 × (k − 1)`px (four need 74px). Spread a hub's counterparts over two or three sides, or enlarge the hub. Center a parent on its children and align a child with its only parent.
+
+Before writing positions, trace each non-main relationship: its straight or one-bend corridor must not pass another node or cross another relationship. If it does, move the endpoint that is off the main path. Start the main actor and its first connected step together near the canvas origin (about `[40, 40]`, not `[200, 200]`); use content rows for vertical rhythm. Empty top/left margin from a high origin wastes canvas and drops fill without improving readability. Omit `meta.viewBox` for a fresh Architecture so the Reader measures intrinsic height. Keep supplied fixed geometry authoritative.
+
+Start with automatic routes and endpoint sides. Pin a side only for a necessary branch, return, or supplied geometry. For a fresh Architecture, leave adjacent request/reply directions automatic when no required side constraint prevents parallel straight lines; preserve supplied side pins. Reserve `via`, `channelX`, `channelY`, and label coordinates for measured defects. Before writing positions, budget every labeled edge between side-by-side boxes, on the main path or not, at `6.5px × ASCII units + 21px` of clear gap, counting CJK as two units; use its own label length, not a row-wide fixed gap. A boundary frame is the padded box around all of its members: place members as one compact axis-aligned cluster (no empty bay that lets a non-member sit inside the padded frame) and keep every non-member, especially an external actor, outside that box. Keep an Architecture canvas within 1240px wide, or 1790px when it is at least 1.55 times as wide as tall; past that its 8px relationship labels drop below the desktop floor. Size Architecture sublabels for their preferred 9px text at `5.4px × text units + 8px`, with CJK counting twice; keep supporting copy concise without dropping required facts. Do not trade readability or meaning for fewer crossings. The [Geometry reference](authoring-contract.md#executable-geometry-rules) has measured spacing, port, canvas, and route rules for a diagnosed layout problem.
+
+## Evidence and schema
+
+For a real repository, follow [Repository authoring](repository-authoring.md) while inspecting source. Freeze its credential-free origin and 40-character commit in `meta.repository`, attach inspected repository-relative `sources` to each key semantic node, and pass `--repo-root` to the first `finalize`. Each reference proves only the fact visible at that location. Follow material relationships and conditions to their actual source; do not reuse a startup citation as protocol or persistence evidence.
+
+Examples show field shape, not legal values or source facts. They are finished showcases, so their optional presentation fields (`meta.subtitle`, `meta.viewBox`, `meta.column_fit`, `via`, `labelAt`) are not defaults; these defaults win. Read the mode schema and shared definition before adding a field, enum, or constrained text. In particular, inspect Architecture boundary kinds. Keep longer evidence in a card while retaining the fact. See [Schema lookup](authoring-contract.md#schema-lookup) for details.
+
+## Presentation and modes
+
+Motion is enabled automatically. Omit `meta.animation`; use the Viewer’s Live/Still button to pause or resume playback.
+
+Use one primary authored language from the user's choice or the request/conversation. Set `meta.locale`; `en`, `zh-CN`, `zh-TW`, `es`, `ko`, and `ar` select a bundled Viewer catalog with nothing further. For other languages, supply `meta.translations` with reusable UI translations, or disclose the fixed Viewer UI and `<html lang>` English fallback. Keep exact product, code, protocol, command, API, and environment names while localizing surrounding explanation. See [Language consistency](authoring-contract.md#language-consistency) for bilingual cases.
+
+Omit `meta.visual_preset` for classic, `meta.subtitle` for a title-only header, `meta.legend` for truthful auto, and `meta.engineering_profile` for an ordinary system overview. Explicit styles and a subtitle require a user request. Use legend or deployment ownership under the [legend](authoring-contract.md#legend-contract) or [engineering profile](authoring-contract.md#engineering-profile-default) contracts. Branding is optional and explicit when a node names a real product; [Brand marks](brand-marks.md) gives lookup and capture rules for that branch. Never let a badge replace semantic type, label, or relationship facts. Set required `meta.output` to a portable POSIX-relative `.html` path within the working directory; see [Output path contracts](delivery-contract.md#output-path-contracts) for native path exceptions.
+
+For a fresh Workflow use schema v2 and omit `meta.viewBox` so the compiler measures the real footprint; do not add empty canvas just to satisfy a viewport ratio. Preserve supplied fixed geometry and v1 sources. In an unpinned draft, omit node `width`: a node starts at 92px and grows to fit its label, sublabel and tag up to 200px. Explicit canvases and absolute route or label pins retain the previous geometry contract. Use its [layout contracts](../renderers/workflow/README.md#layout-contracts) when lane or group geometry needs detail.
+
+For a fresh Sequence omit `meta.viewBox` and `meta.column_fit`: automatic height fits the timeline (no 760px floor), 2–3 short-label participants pack below 920px when labels fit, and the canvas still widens for crowded labels up to its readable width; preserve an authored `meta.viewBox`. Set `meta.column_fit: "fixed"` explicitly when historical fixed coordinates are required; use `spread` when a wide viewBox leaves unused horizontal space or meaningful labels need width. Describe a participant's internal action in a note on its surrounding real cross-participant message, preserving its meaning and order; Sequence self-message loops are not supported. For fresh placement, budget vertical space for that note before placing the next message: 28px is the basic spacing for messages without notes, not a note budget. A note extends below its message; allow at least 44px for one rendered line, 55px for two, or 66px for three before the next message sharing that space (for example, a three-line note at y=200 needs the next message at y=266 or later). Wrapping depends on the final lane width, so leave more room for longer notes and preserve every note's meaning rather than deleting it. These gaps do not guarantee clearance from segment titles, other notes or activations. Supplied fixed y values remain authoritative; in an agent-authored fresh draft, adjust later messages, segment bounds and activation bounds together as needed, preserving order and meaning, and use `sequence/note-overlap` evidence for repairs within those constraints.
+
+For a fresh Dataflow start with the stage/row grid of 2 to 5 stages and rows 0 to 4, and follow the canonical [Dataflow canvas and showcase defaults](authoring-contract.md#dataflow). Adjacent stage centres sit 215px apart and default nodes are 112px wide, leaving about 100px between them, so keep a flow label within about 17 text units, counting CJK as two, and move further detail into a card; add dimensions or route controls for supplied geometry or a measured constraint.
+
+For Dataflow lineage, work backward from every requested output to the values its producer actually consumes. A transformation that combines a raw payload with derived configuration receives a separate labelled input for each; each upstream node may forward only values it actually outputs. Use `database` for an evidenced storage endpoint, naming the file or store. Represent a computed in-memory result through its producing `backend` operation and name the resulting fields in its label or sublabel.
+
+Dataflow requires a non-empty `label` on every flow. Choose `variant` by the meaning its default legend tells the reader: omitted/`default` is ordinary data flow, `emphasis` is primary data, `security` is policy/PII, and `dashed` is async batch. Use `default` for an ordinary dependency, return or fallback; use `security` or `dashed` only when the source supports that meaning. If the user requests a different visual convention, give the affected `meta.legend.entries.<variant>.label` wording that truthfully describes every flow using that variant, following the [legend contract](authoring-contract.md#legend-contract).
+
+For Lifecycle use schema v3: list the happy path in `mainPath` and author every transition, including the main path; the renderer places all other states and routes. Preserve each exit's label, note and variant; [eligible equivalent exits](../renderers/lifecycle/README.md#layout) share routing automatically. Keep transition labels short; a recoverable failure needs a real transition back.
+
+For Class omit `meta.viewBox` and keep the grid to three columns, or four only while types stay near the 180px default width: long members grow a type toward `layout.typeMaxW` (300px), and every extra column widens the canvas and shrinks all text toward the readability floor, so add rows instead. `layout.gapX` and `layout.typeMaxW` are the width controls.
+
+For a repository or directory Tree set `layout.direction: "right"`; keep the default `"down"` for a shallow, balanced breakdown. Read [Mode placement](authoring-contract.md#mode-placement) when a mode-specific placement or viewport problem needs more detail.
+
+`finalize` performs the browser gate. Keep the complete drawing comfortably readable on desktop, with zero horizontal overflow. Use meaningful vertical rows and intrinsic-height page scroll when necessary. The 6px projected-text check is a failure floor; at 1440px, aim for ordinary context text around 7.5px or larger. See [Automated browser evidence](delivery-contract.md#automated-browser-evidence) when viewport evidence fails.

package/ai/skills/stacks-technical-diagrams/references/brand-marks.md

@@ -9,7 +9,7 @@ does; `brand` explains whose product it is.
 1. Search the built-in catalogue when the request names a recognizable brand:
 
    ```bash
-   .claude/skills/stacks-technical-diagrams/bin/diagrams brands "Claude" --json
+   node bin/archify.mjs brands "Claude" --json
    ```
 
 2. Put the returned canonical ID in the node, participant, or state:
@@ -27,7 +27,7 @@ does; `brand` explains whose product it is.
    capture its icon explicitly:
 
    ```bash
-   .claude/skills/stacks-technical-diagrams/bin/diagrams brands capture "https://partner.example.com" --json
+   node bin/archify.mjs brands capture "https://partner.example.com" --json
    ```
 
    Put the command's digest-pinned `brand` value in the authored node:
@@ -48,6 +48,25 @@ does; `brand` explains whose product it is.
    URL or silently assign a visually similar company.
 
 Known-brand URLs resolve to the bundled vector instead of using the network.
+For discovered icon `href` attributes, capture decodes the basic named references
+`amp`, `quot`, `apos`, `lt`, `gt` (and their defined uppercase aliases), plus
+decimal and hexadecimal numeric references, once before URL resolution. Thus
+`/icon.png?v=1&size=32` requests `/icon.png?v=1&size=32`. URL percent escapes
+remain intact; nested escapes are not decoded recursively. This bounded decoder
+does not add a general HTML parser or support every named HTML entity.
+HTML reads stop at an explicit head ending outside comments, raw-text elements
+and quoted attributes, including when those tokens span network chunks. The
+256 KiB head limit and capture deadline still apply; a larger body after the
+head is not read for icon discovery.
+Icon candidates come from complete `link` tags outside comments, raw text and
+template contents. Attribute values and lookalike names such as `data-href`
+cannot supply icon declarations; quoted `>` characters stay within their tags.
+For `text/html`, discovery treats `noscript` contents as raw text, matching
+scripting-enabled HTML parsing; capture does not execute scripts. This exclusion
+does not apply to `application/xhtml+xml`, where `noscript` links remain
+discoverable. XHTML empty elements such as `<script />` and `<template />` do not
+hide following links; the same trailing slash does not close those elements in
+`text/html`.
 Unknown URL capture accepts only bounded raster image formats, blocks
 credentials, nonstandard public ports, and private or link-local destinations,
 uses bounded concurrency and one total deadline, and returns the captured
@@ -55,11 +74,46 @@ content digest. Later render and validate operations require that exact digest;
 blocked, unavailable, changed, oversized, or unsafe content fails closed instead
 of silently changing the artifact.
 
+Remote-brand provenance in capture receipts, node metadata and SVG/HTML keeps
+the source URL's HTTP(S) scheme, host, port and path, but omits userinfo, query
+strings and fragments. The authored `brand.url` and all download/redirect URLs
+remain unchanged so existing pins still reproduce the same bytes and digest.
+Credential-bearing download URLs remain rejected. Built-in marks retain their
+recorded catalogue provenance.
+
+The public source link identifies the original site/path, not necessarily a
+downloadable asset: removing a signed query or a query-based page selector can
+make that link unusable or less specific. Prefer capturing a stable public
+landing page that exposes the intended icon when one is available; do not edit
+an existing pin's URL without capturing and verifying that source again. Paths
+are retained, so this normalization is not a general URL-secret scrubber.
+
+After upgrading from a version that captured inactive HTML markup (including
+`noscript`), an existing URL pin may fail with `brand/digest-mismatch` because
+discovery now selects a different icon. Inspect the intended icon, rerun the
+capture command above for the same URL, and explicitly replace the authored
+`brand` value with the returned pin. Existing pins are not rewritten
+automatically, and digest verification remains enforced.
+
+For ICO captures, every directory entry must reference a non-empty image range
+after the complete directory and within the downloaded file. This bounds check
+also applies when reproducing a pinned capture. PNG/DIB payloads, multiple
+images, shared or out-of-order ranges, and trailing bytes remain supported;
+the check does not decode pixels or guarantee that an otherwise bounded payload
+is decodable. A rejected ICO candidate does not prevent trying later icons.
+
+Page, icon and redirect requests send `Accept-Encoding: identity`. Capture does
+not decompress response bodies: a successful response declaring another content
+coding is closed and rejected explicitly. This keeps the existing byte limits
+and pinned digest tied to the unencoded representation. A later usable icon may
+still succeed; otherwise an encoding error is retained instead of being hidden
+by an unrelated favicon 404.
+
 The final artifact never fetches a brand asset when opened. Preset vectors and
 digest-verified captured site icons remain embedded in SVG, PNG, WebP, JPEG,
 Share Card, and WebM exports.
 
-Use `.claude/skills/stacks-technical-diagrams/bin/diagrams brands --json` to inspect all canonical IDs, aliases,
+Use `node bin/archify.mjs brands --json` to inspect all canonical IDs, aliases,
 categories, domains, and provenance. Current categories cover AI, cloud,
 engineering, data, collaboration, business systems, channels, languages, and
 frameworks.