@hybridlabor-api/aos 4.6.6 → 4.7.0

package/skills/global_config/archify/references/authoring-contract.md

@@ -0,0 +1,247 @@
+# Authoring contract
+
+Read this reference only after the Fast authoring path calls for more detail. The schemas and examples remain authoritative.
+
+## Schema lookup
+
+Read both the mode schema and `schemas/common.schema.json`. The mode schemas use `$ref`, so the common file is where shared enums live.
+
+- `componentType`: `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`
+- `variant`: `default`, `emphasis`, `security`, `dashed`
+- Relationship IDs use the shared identifier pattern and must be unique in their collection.
+
+Do not invent fields. Use the nearest matching example for structure, then author fresh IDs, wording, facts, and layout.
+
+## Workflow layout contracts
+
+Use schema v2 for new workflows and keep schema v1 when an existing source must
+retain fixed geometry. In both versions, `col` stays in `0..5` and semantic
+edge labels are never deleted as a spacing repair. Do not change only
+`schema_version` when absolute coordinates exist: follow the canonical
+[migration and layout-receipt contract](../renderers/workflow/README.md#migration-and-layout-receipt).
+The complete normative invariants live in the workflow renderer's
+[layout contracts](../renderers/workflow/README.md#layout-contracts).
+
+## Legend contract
+
+Omit `meta.legend` for the truthful default: `auto` lists only semantic kinds
+present in typed IR. Use `mode: "all"` for a renderer reference or
+`mode: "hidden"` to remove the full legend. Under `entries`, only keys listed
+by the selected mode schema are valid; each key accepts `label`, `visible`, or
+both. `visible: true` may show an unused supported convention, while
+`visible: false` hides it. `hidden` cannot be overridden.
+
+A label override changes reader wording only. Never infer a kind from prose or
+use the legend to compensate for missing nodes, states, messages, or flows.
+Long labels are measured and wrap into deterministic rows. Architecture's
+implicit automatic viewBox grows from that same measured footprint. For
+backwards compatibility, a legacy document with no `meta.legend` may omit an
+implicit auto legend that cannot fit its explicit viewBox; this never changes
+its typed topology. Adding `meta.legend` makes the presentation intentional and
+strict: if its resolved labels cannot fit the authored viewBox, shorten or hide
+them, or widen the viewBox using the emitted diagnostic.
+
+## Language consistency
+
+Choose one primary authored language. An explicit user choice wins; otherwise
+use the language of the request, or the conversation's dominant language when
+the request itself is language-neutral. Separately choose the Viewer locale.
+For supported languages, always write the matching `meta.locale`: `"en"` for
+English or `"zh-CN"` for Simplified Chinese. The renderer consumes the authored
+locale without inferring language from diagram strings. Documents that omit it
+remain valid and default to English.
+
+`meta.locale` controls only renderer-owned reader surfaces: `<html lang>`, the
+document-title suffix, default SVG description and focus labels, default legend
+labels, and fixed Viewer controls, statuses, accessibility names, and errors.
+It never translates authored content. Apply the primary language separately to
+titles, subtitles, node and relationship copy, boundaries, lanes, groups,
+guided views, legend label overrides, and cards. A bilingual diagram still
+chooses one primary locale for the Viewer; follow an explicit primary-language
+request, then prompt order or conversation dominance.
+
+For a requested language outside `en` and `zh-CN`, do not write an unsupported
+locale. Keep every reader-facing authored string in the requested language,
+omit `meta.locale` so the renderer safely uses English, and explicitly tell the
+user that fixed Viewer UI and `<html lang>` remain English and the artifact is
+not fully localized. The fallback applies only to renderer-owned surfaces; it
+never permits authored copy to fall back to English. Do not silently substitute
+`zh-CN` for another language or Chinese locale.
+
+Keep exact product names, code identifiers, commands, protocols, API paths, and
+environment names intact. Those terms may remain English inside localized copy,
+but surrounding explanatory prose must still use the selected language.
+Renderer-owned default legend labels follow `meta.locale`; author a
+`meta.legend.entries.*.label` override only when the diagram needs different
+domain wording, and keep that authored override in the primary language.
+
+## Visual preset default
+
+Omit `meta.visual_preset` by default. The renderer then opens the diagram in
+`classic` for both light and dark color modes. Color mode and visual preset are
+independent viewer state: switching Light / Dark must preserve the current
+preset. Author `signal-flow`, `blueprint`, or `editorial` only when the user
+explicitly requests that visual style.
+
+## Engineering profile default
+
+Omit `meta.engineering_profile` for an ordinary system architecture. Region,
+cluster, and security boundary wording do not by themselves enable an
+engineering profile. Enable `deployment-ownership` only when the user
+explicitly asks for a production deployment topology, ownership handoff, or
+fail-closed deployment review and the source facts are known. Once enabled,
+do not remove the engineering profile merely to pass validation; repair the
+authored facts or report the diagnostics truthfully.
+
+## Title hierarchy
+
+Use one concise title and let the diagram carry the explanation. Omit
+`meta.subtitle` by default, and never use it to restate the title, nodes, edges,
+or cards. Include one short supporting line only when the user explicitly asks
+for a subtitle; an omitted or blank subtitle must not leave an empty visual row
+in the generated viewer.
+
+## Executable geometry rules
+
+- Node anchors start at side midpoints. `left`/`right` change the horizontal endpoint; `top`/`bottom` change the vertical endpoint. For an automatic Architecture relationship, unobstructed facing ports whose axis offset is under 16px may share one horizontal or vertical axis when both endpoints retain the 16px corner gutter. If exactly one endpoint belongs to a spread group, only its unshared counterpart moves; relationships spread at both endpoints keep their distinct ports and outside bridge.
+- A side is a direction contract. The first and final route segment must be perpendicular and outward/inward in the named direction.
+- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle diagrams. Shared automatic endpoints spread deterministically and symmetrically with a 16px corner gutter. It does not apply to sequence messages, single relationships, or explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes.
+- Showcase route rhythm: every nonzero segment must be at least 8px; every interior segment must be at least 16px. When spread ports are nearly parallel, the router uses a 24px endpoint stub and a 16px outside bridge instead of manufacturing a tiny dogleg.
+- Shared endpoint corridors are allowed only when they remain semantically unambiguous. Unrelated collinear overlap of 8px or more fails showcase.
+- Container borders are intentional pass-through geometry, but a long edge running along a structural border is not.
+- An edge crossing an unrelated opaque node is always a hard failure, independent of quality profile.
+
+### Spacing and labels
+
+Spacing recommendations mean clear gap between boxes, not center distance. A 200px center distance between 165px-wide nodes leaves only 35px of clear gap.
+
+For a relationship label, require:
+
+```text
+clear gap > label mask width + 8px breathing room
+label mask width ≈ 6.5px × ASCII units + 13px
+CJK characters count as two units
+```
+
+Relationship labels are semantic data. If the gap is too small, move the label,
+adjust the route or spacing, then shorten the wording while preserving meaning.
+Omit only wording already fully implied by both endpoints and carrying no
+protocol, action, direction, synchronous/asynchronous behavior, or
+cross-boundary mechanism. Preserve every meaningful label.
+Deleting it is not a spacing repair. If a relationship starts unlabeled because
+its endpoints fully imply it, explain why the wording is redundant; this is a
+semantic authoring choice, not a spacing repair. In workflow v2, let the compiler
+allocate its measured mask before applying a diagnosed `labelAt`,
+`labelDx`/`labelDy`, or `labelSegment`. Apply one diagnosed geometry control at
+a time.
+
+### Repair order
+
+1. Fix missing/invalid `meta.quality_profile` and schema errors.
+2. Fix node overlap or out-of-range placement.
+3. Fix edge-through-node and endpoint-direction errors.
+4. Fix crossings, ambiguous corridors, border runs, and route rhythm.
+5. Fix label-to-node, label-to-label, then label-to-route clearance.
+
+Run `validate` after every edit. Consume `diagnostics[]` by stable `code`, exact `subject`, measured `evidence`, and `supportedFixes`. If the diagnostic gives `labelAt`, use that point instead of estimating another offset.
+
+## Mode placement
+
+### Architecture
+
+Use one left-to-right spine with short vertical branches. Prefer 6–12 primary components and group only real ownership, trust, process, or deployment boundaries. Boundaries do not replace relationships.
+
+Grid placement is preferred when the schema supports it. Free positions are appropriate for a bounded exception, not for prose-level coordinate planning. Keep external actors outside the system boundary when that is factually true.
+
+### Workflow
+
+Lanes express responsibility or phase. Columns `0..5` express logical
+progression. Start new workflows on `readable-v2`; retain `fixed-v1` only for
+legacy geometry compatibility. Keep the happy path monotonic, preserve semantic
+edge labels, and route retries and exception returns outside the main lane
+corridor.
+
+### Sequence
+
+Participants are ordered by conversation role. Messages own their vertical order. Use return/async/security variants for meaning, not decoration; sequence does not use Automatic Port Spread.
+
+### Dataflow
+
+Stages express transformation or custody. Rows separate parallel streams. Label only data contracts, classifications, or cross-boundary movement that is not obvious.
+
+### Lifecycle
+
+Main phases use columns `0..4`; event and terminal bands use columns `0..2`.
+Event/terminal column `N` aligns to the same x coordinate as main column
+`N + 2`. A recoverable failure needs a real transition back to an active state.
+A card or guided view saying “retry” is not topology.
+
+## Repository evidence
+
+When an architecture diagram must reflect real code, inspect repository
+entrypoints, runtime boundaries, storage, transports, and deployment
+configuration before authoring. Record only evidence you actually verified.
+`--repo-root <path>` is architecture-only and is accepted by architecture
+`render`, `validate`, `deliver`, `preview`, and `compare`; workflow, sequence,
+dataflow, and lifecycle reject it. Never infer runtime causality from file
+proximity or naming alone.
+
+Declare `meta.repository.url` and one full 40-character `revision`, then attach
+`components[].sources` with repository-relative `path`, optional `line`,
+`end_line`, and `label`. Verification reads blobs at that commit, independently
+of working-tree edits. Verification ignores local Git replacement refs, including
+those selected by `GIT_REPLACE_REF_BASE`, and always reads the original objects
+at the pinned SHA. It does not change repository configuration or delete
+replacement refs.
+A matching local origin, available commit, bounded path,
+blob, and valid line range are required in every link mode. Verification is
+local and makes no remote requests; it establishes neither public availability
+nor the current reader's access rights.
+
+`link_mode` defaults to `web`. GitHub and Gitee HTTPS repository URLs generate
+revision-pinned links; their public hosts select the provider automatically.
+Optional `provider: "github"` or `"gitee"` must agree with the host. Existing
+GitHub declarations and default delivery receipt fields remain compatible.
+
+```json
+{
+  "url": "https://gitee.com/team/service",
+  "revision": "0123456789abcdef0123456789abcdef01234567",
+  "provider": "gitee"
+}
+```
+
+For an internal or unsupported forge, select `link_mode: "local-only"`. The
+Viewer retains SRC markers, searchable file paths, line ranges, and revision
+labels without repository or source hyperlinks. The evidence receipt adds
+`linkMode: "local-only"`. `url` remains required as the expected origin identity;
+local-only disables links, not identity verification. A repository without an
+origin is not supported.
+
+```json
+{
+  "url": "http://git.internal:3000/Platform/Services/service",
+  "revision": "0123456789abcdef0123456789abcdef01234567",
+  "link_mode": "local-only"
+}
+```
+
+Local-only accepts HTTP(S), `git@host:path`, and `ssh://git@host[:port]/path`
+addresses, including nested namespaces. Declare a credential-free address;
+HTTP(S) credentials on the checkout's origin are ignored for identity and
+redacted from diagnostics. Hostnames compare case-insensitively; repository
+paths retain case except for the existing GitHub behavior. A trailing slash
+normalizes away. Only GitHub and Gitee normalize a terminal `.git` and match
+standard HTTPS/443 with Git SSH/22. For other hosts, use the actual clone address:
+transport, port, `.git` suffix, and remote-relative versus absolute paths must
+match. For example, `git@host:Team/repo` differs from
+`ssh://git@host/Team/repo`; `git@host:/Team/repo` matches the latter. SCP-style
+paths preserve literal percent escapes, while URI paths decode them. SSH host
+aliases and forge-specific browse/clone prefixes are not guessed.
+GitLab/Gitea/Forgejo/Bitbucket web links are not implemented in this version;
+use local-only until a tested link provider is available. Unknown web providers
+fail with a diagnostic rather than emitting a guessed link.
+
+## Hand-placed fallback
+
+Use only when no renderer can run. Start from `assets/template.html`, keep semantic CSS classes, preserve the inline SVG/accessibility structure, and run the delivery visual checklist. Never introduce inline literal colors that break dark/light parity.

package/skills/global_config/archify/references/brand-marks.md

@@ -0,0 +1,65 @@
+# Brand marks
+
+Use a brand mark only when a real product, provider, model family, channel, or
+service identity helps the reader. Semantic `type` still explains what the node
+does; `brand` explains whose product it is.
+
+## Agent decision path
+
+1. Search the built-in catalogue when the request names a recognizable brand:
+
+   ```bash
+   node bin/archify.mjs brands "Claude" --json
+   ```
+
+2. Put the returned canonical ID in the node, participant, or state:
+
+   ```json
+   {
+     "id": "planner",
+     "type": "backend",
+     "label": "Claude",
+     "brand": "claude"
+   }
+   ```
+
+3. If there is no catalogue match and the user supplied the official website,
+   capture its icon explicitly:
+
+   ```bash
+   node bin/archify.mjs brands capture "https://partner.example.com" --json
+   ```
+
+   Put the command's digest-pinned `brand` value in the authored node:
+
+   ```json
+   {
+     "id": "partner",
+     "type": "external",
+     "label": "Partner portal",
+     "brand": {
+       "url": "https://partner.example.com",
+       "sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+     }
+   }
+   ```
+
+4. If there is no match and no user-provided URL, omit `brand`. Do not invent a
+   URL or silently assign a visually similar company.
+
+Known-brand URLs resolve to the bundled vector instead of using the network.
+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
+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.
+
+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 `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.

package/skills/global_config/archify/references/delivery-contract.md

@@ -0,0 +1,138 @@
+# Delivery contract
+
+## Validate and deliver
+
+Use `validate` after every candidate edit. CLI HTML output paths must end in `.html`, including after symbolic-link resolution.
+Compare receipt paths must end in `.json`. Explicit CLI paths may be absolute or
+outside the current working directory; authored `meta.output` remains confined
+to that directory. A type mismatch fails before writing with
+`output/cli-extension` or `output/cli-resolved-extension`. These checks prevent
+accidental file-type overwrites; they do not sandbox explicit CLI directories
+or prevent replacement of an existing artifact of the expected type.
+
+Use final atomic delivery only after the candidate is frozen:
+
+```bash
+node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
+```
+
+Deliver reads the specification once, writes those exact bytes to a private same-directory candidate snapshot, renders that snapshot, runs the complete artifact checker, and only replaces the target after all artifact checks pass. The JSON receipt includes SHA-256 and byte counts for both `specification` and `artifact`. Renderer, checker, receipt, or commit failure exits non-zero, removes private state, preserves the previous trusted artifact, and never invokes an opener.
+
+Run `visual-check` only after `deliver` exits zero for the current candidate. If
+delivery fails and the output path already exists, that path still names the
+previous trusted artifact; running `visual-check` then would measure and capture
+stale output, not the rejected candidate. Report the delivery diagnostics and
+repair the source before collecting new visual evidence.
+
+The delivery interface exposes three separate claims:
+
+1. `deliver` proves deterministic artifact checks and byte identity.
+2. `visual-check` collects automated browser evidence from the exact artifact.
+3. Perceptual visual review records a human or image-capable reviewer's judgment.
+
+Passing one claim never implies either of the others. Never claim that the deterministic receipt includes visual review. It does not include browser evidence either.
+
+## Recovering a failed comparison
+
+`compare` commits an HTML artifact and its JSON receipt as a pair. If that commit
+fails, it attempts to restore the previous files. A complete rollback removes
+the temporary directory as usual.
+
+If a previous file cannot be restored, compare exits non-zero with
+`delta/commit-rollback-failed` and retains the recovery directory. In the JSON
+failure receipt, `diagnostics[].evidence.recoveryDirectory` identifies that
+directory and `recoveryFiles` lists `{ backup, target }` paths for the files whose
+restoration failed. Human-readable diagnostics also print the recovery paths.
+
+Resolve the filesystem error, inspect the current targets, and restore each
+listed backup to its corresponding target before retrying. Keep the recovery
+directory until both previous files have been recovered and verified; it can
+also contain rejected candidate files, which must not be mistaken for backups.
+Successful comparisons and failures before commit retain their normal cleanup.
+
+## Automated browser evidence
+
+After delivery, inspect the exact trusted HTML without rerendering or modifying
+it:
+
+```bash
+node bin/archify.mjs visual-check <output.html> --json
+```
+
+The zero-dependency command uses Chrome/Chromium through the DevTools pipe. It
+measures light-theme containment at 1440×900, 1600×1000, 1920×1080, and
+2048×1320, then captures light/dark screenshots at 1440×900 and 2048×1320. It
+writes four PNG sidecars, one relative-path HTML contact sheet, and one JSON
+receipt beside the artifact. The receipt binds the source artifact SHA-256 and
+byte count, identifies `evidenceKind: "automated-browser"`, records READ plus
+Still runtime state, and always reports `visualReview: "pending"`; automated
+browser evidence cannot claim perceptual review.
+
+`browser_evidence` in the handoff records only the outcome of this automated command:
+
+- `passed` maps from exit 0 and receipt `status: "pass"` only after every required measurement and capture completes and passes.
+- `failed` maps from exit 1 and receipt `status: "fail"` when the inspection finds a defect, the command fails, or a runtime/capture error leaves the evidence incomplete.
+- `skipped` maps only from exit 2 and receipt `status: "skipped"` when Chrome/Chromium is unavailable and the inspection does not run.
+
+Runtime or capture failures leave incomplete evidence and must not be normalized to `skipped`. Failed or skipped capture runs remove stale
+image/contact-sheet sidecars rather than presenting prior evidence as current.
+They do not invalidate an already successful deterministic delivery, and they
+do not turn a perceptual visual review into passed or failed. Retry an
+environmental failure through the supported command in a browser-capable
+execution context when practical. Keep the packaged transport unchanged unless
+the failure reproduces through that seam in a capable environment.
+
+## Optional opening
+
+Add `--open` only when the user wants an immediate local preview. It runs after that atomic commit, uses one argument-array OS opener with a five-second bound, and records `open.status`. Keep it off for CI, unattended agents, and non-interactive environments. Failure or unsupported opening does not invalidate delivery; its status proves only whether the local opener invocation succeeded.
+
+## Last-Good Live Preview
+
+For an active desktop authoring loop only:
+
+```bash
+node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase
+```
+
+Preview watches one explicit input on loopback, binds each stable digest to a private snapshot, and advances only after the existing verified delivery pipeline passes. Invalid, half-written, deleted, or superseded input leaves the previous verified revision on screen and on disk. Identical bytes do not rebuild or reload.
+
+The preview runtime ships inside the zero-dependency Skill ZIP and must work without `node_modules`.
+
+Never start it by default. Do not use it for CI, unattended agents, remote sharing, or mobile use. `--no-open` is only for a user who will open the printed local URL or for loop testing. Stop it with Ctrl-C before handoff. Server state, port, source path, diagnostics, error text, and reload tokens must never enter the generated artifact or any export.
+
+## Perceptual delivery gate
+
+Automated validation and browser evidence cannot prove visual polish. After deterministic delivery, inspect the actual HTML in a capable browser or render the evidence screenshots with an image reader. Check both themes when changed, the default READ view, line crossings/corridors, label masks, node/card fit, focus/search/passport closure, and export cleanliness.
+
+For the default standalone desktop viewer, measure 1440×900, 1600×1000, and 1920×1080. When the artifact is intended for a large desktop display, also measure 2048×1320. A first-screen pass requires `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size. At the largest checked viewport, inspect the rendered composition for a conspicuous empty lower band: the main panel and necessary conclusion cards should use the available height as a balanced whole, not collapse into a shallow strip. If a desktop viewport overflows, repair the authored composition by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. Do not hide overflow, clip content, introduce an internal diagram scroller, or reduce node/label typography to make the measurement pass. Narrow/mobile containment may retain vertical page scrolling.
+
+A manual browser record is supplementary to the automated status. Reproducing the same coverage requires all four exact viewport measurements, both endpoint themes, and an artifact-bound record of the inspected SHA-256 and byte count. It never changes `browser_evidence`: when Chrome/Chromium is unavailable, that status remains `skipped` even when the manual browser record is complete and `visual_review: passed`; an automated `failed` result likewise remains `failed`. An unconstrained browser glance can support perceptual review only.
+
+Report exactly one truthful status:
+
+- `visual_review: passed` — only after inspecting the rendered artifact.
+- `visual_review: skipped (image reader unavailable)` — when no capable visual surface exists.
+- `visual_review: failed` — with the concrete visible defect.
+
+Use `correction_rounds: 0`, `correction_rounds: 1`, or `correction_rounds: 2`; never exceed a maximum of two focused correction rounds. Never report `visual_review: passed` without inspecting the artifact.
+
+If visual review changes the candidate, validation and delivery must run again because the prior frozen specification receipt is no longer current.
+
+## Handoff receipt
+
+Return:
+
+```text
+diagram_type: architecture|workflow|sequence|dataflow|lifecycle
+output: /absolute/path/to/file.html
+specification_sha256: <receipt value>
+artifact_sha256: <receipt value>
+validation: 9/9 showcase, 0 errors, 0 warnings
+browser_evidence: passed|failed|skipped
+visual_review: passed|skipped (image reader unavailable)|failed
+correction_rounds: 0|1|2
+```
+
+Derive `browser_evidence` only from the latest artifact-bound `visual-check` receipt. Record any manual browser work separately with its artifact binding, viewport/theme scope, and observations; never use it or `visual_review` to overwrite the automated status.
+
+Opening, preview status, Share Cards, and other viewer exports are not validation claims.

package/skills/global_config/archify/references/viewer-runtime.md

@@ -0,0 +1,45 @@
+# Viewer Runtime reference
+
+Read this only when the user asks for a reader-facing capability. Ordinary generation does not require implementing or re-documenting these features; they are already in the generated HTML.
+
+## Exploration
+
+- Diagram Guide lists current actions and shortcuts.
+- Reading Depth starts at READ at the default 100% scale, reveals FULL detail at 175%, and falls back to MAP only below 100%. Focus, story, route, and semantic interactions reveal their exact facts at any scale.
+- Semantic Lens summarizes selected node/relationship kinds without changing authored geometry.
+- Intent Trace previews a fine-pointer or keyboard target before committed focus.
+- Node Finder searches labels and stable IDs.
+- Semantic Passport opens on focus, shows authored upstream/downstream facts, supports a copyable deep link, has an explicit close action, closes on true outside activation and Escape, and never enters canonical export.
+- Semantic Radar mirrors the visible viewport and authored graph without becoming a second source of truth.
+- Direct Relationship Pin makes a unique compiled relationship operable while preserving the authored line and stable relationship identity. It must fail closed on conflicting source/target/label/ID metadata.
+- Route Probe resolves exactly two endpoints over authored directed relationships. It never infers a route from geometry.
+
+## Guided views and story
+
+`meta.views` may define at most five curated chapters using stable node IDs. The Named Chapter Rail, Chapter Delta Preview, Story Beat Navigator, Story Follow Camera, Story Director Strip, Story Horizon, and Shareable Story Moment links all derive from that one authored array; none owns parallel topology or layout.
+
+Story transitions classify only the exact relationship between adjacent authored stops: forward, reverse, multiple, or grouped/no direct link. Never infer a transitive edge, verb, causality, or runtime behavior from proximity, kinds, or story order. Playback is reader-started, bounded, stale-safe, and motion-governed.
+
+## Motion and presentation
+
+`meta.animation: "trace"` enables a finite reader-controlled Live/Still trace. Static is the default. Still, reduced motion, page hiding, print, and canonical export preserve complete static meaning. Presentation Stage changes viewer chrome and framing, never authored geometry. This is not a mobile product feature; narrow layouts get containment only.
+
+## Canonical exports
+
+The export menu can copy/download full-diagram PNG, download JPEG/WebP, download a dual-theme SVG, and record a trace-enabled WebM. Viewer state—Guide, Lens, finder, focus, route, story, camera, radar, presentation, motion ownership, and temporary overlays—must be removed from canonical export.
+
+### Share Card
+
+The optional 1200×630 Share Card PNG is for README, release, social, or launch previews. It uses the current theme and visual preset, contains the complete canonical diagram without cropping, and never claims validation. Copy Share Card reuses the same canonical PNG when clipboard image writes are supported.
+
+### Route Share Card
+
+After a real directed Route Probe resolves, the reader may use **Export → Route Share Card**. It reuses the exact ordered route snapshot and the shared Share Card seam: `format=share-card`, `variant=route`. The isolated clone may use only static `data-share-route-*` decoration. It is download-only, fails closed for stale/unreachable/conflicting routes, and never becomes the canonical artifact.
+
+### Reach Share Card
+
+After a non-empty authored reachability query, the reader may use **Export → Reach Share Card**. It consumes the already resolved upstream/downstream node and edge set without rerunning traversal: `format=share-card`, `variant=reach`. The isolated clone may use only static `data-share-reach-*` decoration. It is download-only. Call it authored reachability—not impact, blast radius, breakage, or runtime causality.
+
+## Truth boundary
+
+Viewer exports are communication assets. They do not replace the checked HTML, the deterministic delivery receipt, or a real visual review. Do not add a hosted service, storage surface, dependency, schema branch, or mobile product surface for these viewer-only capabilities.

package/skills/global_config/archify/renderers/architecture/grid.mjs

@@ -0,0 +1,62 @@
+/** Grid placement for architecture IR (#8). Not auto-layout — fixed cell math only. */
+
+export const DEFAULT_GRID = {
+  mode: 'grid',
+  origin: [40, 80],
+  cols: 4,
+  gapX: 30,
+  gapY: 40,
+  cellW: 130,
+  cellH: 64,
+};
+
+export function gridLayout(arch) {
+  const raw = arch.layout;
+  if (!raw || raw.mode !== 'grid') return null;
+  return { ...DEFAULT_GRID, ...raw };
+}
+
+export function resolveComponentPos(component, grid) {
+  if (Array.isArray(component.pos) && component.pos.length === 2) {
+    return component.pos;
+  }
+  if (!grid) return [NaN, NaN];
+  if (!Number.isInteger(component.row) || !Number.isInteger(component.col)) {
+    return [NaN, NaN];
+  }
+  const [ox, oy] = grid.origin;
+  const stepX = grid.cellW + grid.gapX;
+  const stepY = grid.cellH + grid.gapY;
+  return [ox + component.col * stepX, oy + component.row * stepY];
+}
+
+export function validateGridPlacement(arch, grid, problems) {
+  if (!grid) return;
+  if (arch.layout !== undefined && arch.layout.mode !== 'grid') {
+    problems.push('layout.mode must be "grid" when layout is set (free placement omits layout entirely).');
+    return;
+  }
+  const seen = new Map();
+  for (const c of arch.components ?? []) {
+    const hasPos = Array.isArray(c.pos) && c.pos.length === 2;
+    const hasCell = Number.isInteger(c.row) && Number.isInteger(c.col);
+    if (hasPos) continue; // pos wins; row/col are optional hints only
+    if (!hasPos && !hasCell) {
+      problems.push(`Component "${c.id}" needs pos [x,y] or grid row/col when layout.mode is "grid".`);
+      continue;
+    }
+    if (c.row < 0 || c.col < 0) {
+      problems.push(`Component "${c.id}" row/col must be non-negative integers.`);
+      continue;
+    }
+    if (c.col >= grid.cols) {
+      problems.push(`Component "${c.id}" col ${c.col} exceeds layout.cols ${grid.cols} (valid: 0..${grid.cols - 1}).`);
+    }
+    const key = `${c.row},${c.col}`;
+    if (seen.has(key)) {
+      problems.push(`Components "${seen.get(key)}" and "${c.id}" share grid cell row ${c.row} col ${c.col}.`);
+    } else {
+      seen.set(key, c.id);
+    }
+  }
+}