create-yss-spec 3.0.0 → 3.0.1

package/template/.hermes/skills/alibaba-java-code-style/references/java-programming.md

@@ -1,178 +0,0 @@
-# Java Programming Rules
-
-Use this reference for Java implementation and review: naming, constants, formatting, OOP, collections, concurrency, control flow, comments, and general coding traps.
-
-## Naming
-
-Mandatory:
-
-- Do not start or end identifiers with `_` or `$`.
-- Do not mix pinyin and English; do not use Chinese identifiers. Widely recognized names such as `alibaba`, `taobao`, `youku`, and `hangzhou` are acceptable.
-- Use `UpperCamelCase` for classes, except suffix acronyms such as `DO`, `BO`, `DTO`, `VO`, `AO`, `PO`, and `UID`.
-- Use `lowerCamelCase` for methods, parameters, member variables, and local variables.
-- Use uppercase words separated by underscores for constants, with complete semantics such as `MAX_STOCK_COUNT`.
-- Name abstract classes with `Abstract` or `Base` prefixes, exception classes with `Exception` suffixes, and test classes as the tested class name plus `Test`.
-- Put brackets next to the type for arrays: `String[] args`, not `String args[]`.
-- Do not prefix POJO boolean properties with `is`; frameworks may mis-detect the property name. Map database `is_xxx` fields explicitly.
-- Package names must be lowercase, singular, dot-separated, and each segment should be one natural English word.
-- Avoid nonstandard abbreviations that hide meaning.
-
-Recommended/reference:
-
-- Prefer complete words for self-explanatory names.
-- If a module, interface, class, or method uses a design pattern, reflect the pattern in the name, such as `OrderFactory`, `LoginProxy`, or `ResourceObserver`.
-- Interface methods and fields should omit redundant `public` modifiers and include useful Javadoc.
-- For `Service` and `DAO`, expose interfaces and name implementations with `Impl`.
-- Capability interfaces may use adjective names such as `Translatable`.
-- Enum class names may end with `Enum`; enum members use uppercase underscores.
-- Layer method prefixes: `get` for one object, `list` for multiple objects, `count`, `save`/`insert`, `remove`/`delete`, and `update`.
-- Model suffixes: `xxxDO`, `xxxDTO`, `xxxVO`; do not name a class `xxxPOJO`.
-
-## Constants
-
-Mandatory:
-
-- Do not use magic values directly in code. Define named constants.
-- Use uppercase `L` for `long`/`Long` literals, never lowercase `l`.
-
-Recommended:
-
-- Do not keep every constant in one universal constant class. Group by function and scope.
-- Choose the smallest sensible reuse scope: cross-application library, application, submodule, package, or class-local `private static final`.
-- Use `enum` when values vary only within a fixed set, especially when values have attributes.
-
-## Formatting
-
-Mandatory:
-
-- For non-empty blocks, put `{` on the same line, newline after `{`, newline before `}`, and keep `} else {` on one line. Empty blocks may be `{}`.
-- Do not put spaces immediately inside parentheses. Put one space before `{`.
-- Put one space between reserved words and `(` for `if`, `for`, `while`, `switch`, and `do`.
-- Put one space around binary and ternary operators.
-- Use 4 spaces for indentation; do not use tab characters.
-- `//` comments must have exactly one space after the slashes.
-- Keep lines at or below 120 characters. When wrapping, indent the second line 4 spaces, keep operators and dots with the following line, wrap method arguments after commas, and do not break before `(`.
-- Add a space after commas in method definitions and calls.
-- Use UTF-8 and Unix line endings.
-
-Recommended:
-
-- Keep a single method under 80 lines, including signature, braces, code, comments, blank lines, and invisible characters.
-- Do not align variables by adding decorative spaces.
-- Insert one blank line between different logical or business sections; avoid multiple blank lines.
-
-## OOP And POJO
-
-Mandatory:
-
-- Access static members through the class name, not an object reference.
-- Add `@Override` to all overridden methods.
-- Use varargs only for same-type, same-meaning arguments; avoid `Object...`.
-- Do not change method signatures of externally used APIs or library APIs. Deprecate old interfaces with `@Deprecated` and document replacements.
-- Do not use deprecated classes or methods.
-- Call `equals` on constants or known non-null objects, or use `Objects.equals`.
-- Compare wrapper objects of the same type with `equals`, not `==`.
-- Use wrapper types for all POJO fields and RPC parameters/returns; prefer primitive types for local variables.
-- Do not set default values on DO/DTO/VO fields.
-- When adding fields to serializable classes, do not change `serialVersionUID` unless the change is intentionally incompatible.
-- Do not put business logic in constructors; use an init method or lifecycle hook.
-- POJO classes must implement `toString`; include `super.toString()` when extending another POJO.
-- Do not define both `isXxx()` and `getXxx()` for the same POJO property.
-
-Recommended:
-
-- Before indexing into `String.split` results, account for trailing separators.
-- Keep overloaded methods and multiple constructors adjacent.
-- Order methods as public/protected methods, private methods, then getters/setters, except overloaded groups.
-- Setter parameter names should match field names and use `this.field = field`.
-- Do not add business logic to getters or setters.
-- Use `StringBuilder.append` for string concatenation inside loops.
-- Use `final` for non-inheritable classes, non-overridable methods, immutable references, non-reassigned locals, or to avoid variable reuse confusion.
-- Be careful with `Object.clone`; default clone is shallow.
-- Minimize access scope: private constructors for non-instantiable classes, no public/default constructors in utility classes, private fields and methods unless broader access is truly required, and consider `final` for static fields.
-
-## Collections
-
-Mandatory:
-
-- If overriding `equals`, also override `hashCode`.
-- Objects stored in `Set` or used as `Map` keys must implement both `equals` and `hashCode`.
-- Do not cast `ArrayList.subList` results to `ArrayList`; it is a view.
-- Do not structurally modify the original list while iterating or changing a `subList`.
-- Convert collections to arrays with `toArray(new T[list.size()])`, not raw `toArray()`.
-- Do not call mutating methods on `Arrays.asList` results.
-- Respect PECS: `? extends T` is for producers/readers and cannot safely accept `add`; `? super T` is for consumers/writers and cannot safely provide typed `get`.
-- Do not remove/add elements inside foreach loops; use an `Iterator` and `iterator.remove()`. Lock the iterator if operations are concurrent.
-- Comparators must be symmetric, transitive, and handle equality consistently.
-
-Recommended:
-
-- Use diamond syntax or type inference where supported.
-- Specify initial collection capacity where size is known; for `HashMap`, use roughly `expectedSize / 0.75 + 1`, or default 16 when unknown.
-- Iterate maps with `entrySet` or `Map.forEach` when both key and value are needed.
-- Know map null support: `ConcurrentHashMap` and `Hashtable` reject null keys/values; `TreeMap` rejects null keys; `HashMap` allows null keys/values.
-- Use set uniqueness to de-duplicate rather than repeated `List.contains`.
-
-## Concurrency
-
-Mandatory:
-
-- Singleton acquisition and singleton methods must be thread-safe.
-- Name threads and thread pools meaningfully.
-- Provide thread resources through thread pools; do not create raw application threads casually.
-- Do not create production thread pools through `Executors`; use `ThreadPoolExecutor` so queue size, thread count, rejection policy, and resource limits are explicit.
-- Do not use static `SimpleDateFormat` without synchronization. Prefer `DateTimeFormatter`/`java.time`, `ThreadLocal`, or a safe date utility.
-- In high concurrency, minimize lock cost: prefer lock-free structures, small locked blocks, and object locks over class locks where suitable.
-- Keep a consistent lock acquisition order across resources to avoid deadlock.
-- For concurrent updates to one record, use application/cache locks or database optimistic locks with a `version` field; retry optimistic locks at least 3 times.
-- Prefer `ScheduledExecutorService` over `Timer` for multiple scheduled tasks, because one uncaught `TimerTask` exception stops other tasks.
-
-Recommended/reference:
-
-- With `CountDownLatch`, call `countDown` in `finally` or otherwise guarantee it runs even on exceptions.
-- Prefer `ThreadLocalRandom` over shared `Random`/`Math.random` in concurrent code.
-- If using double-checked locking on JDK 5+, declare the target field `volatile`.
-- `volatile` solves visibility for one writer/many readers but not compound writes; use `AtomicInteger`, `AtomicLong`, or `LongAdder` for counters.
-- Avoid unsynchronized high-concurrency `HashMap` resizing; use concurrent collections or locking.
-- Declare `ThreadLocal` fields as `static` when the per-thread value should be shared by all instances of the class.
-
-## Control Flow And Parameters
-
-Mandatory:
-
-- Every `switch` case must end with `break`, `return`, or a comment explaining fallthrough. Every `switch` must have a final `default`.
-- Always use braces for `if`, `else`, `for`, `while`, and `do`, even for one line.
-- In high-concurrency exit logic, avoid equality-only checks; prefer range checks that cannot be skipped by concurrent changes.
-- Do not exceed 3 levels of `if/else`; use guard clauses, strategy, or state pattern.
-
-Recommended:
-
-- Prefer guard clauses for exceptional branches.
-- Do not put complex expressions inside conditions. Assign them to well-named boolean variables first.
-- Move object creation, connection acquisition, unnecessary try/catch, and other expensive operations outside loops where possible.
-- Avoid negated logic when an equivalent positive condition is available.
-- Protect interface parameters, especially batch operations.
-- Validate parameters for low-frequency, expensive, high-stability, external, or sensitive-permission methods.
-- You may omit repeated validation for hot private or low-level methods only when callers have already validated and method docs state the expectation.
-
-## Comments And General Rules
-
-Mandatory:
-
-- Use Javadoc (`/** ... */`) for classes, fields, and methods. Do not use `//` as class or method API documentation.
-- Abstract methods and interface methods need Javadoc explaining purpose, parameters, returns, exceptions, and implementation notes.
-- Classes must include creator and creation date if the repository convention requires Alibaba manual compliance; otherwise follow local project header policy.
-- Place single-line comments above the code they explain. Align multi-line block comments with code.
-- Every enum value must have a comment explaining its purpose.
-- Precompile regular expressions; do not call `Pattern.compile` repeatedly inside method bodies.
-- Use `System.currentTimeMillis()` for current milliseconds, not `new Date().getTime()`. Use `System.nanoTime()` for elapsed time measurement; Java 8 may use `Instant`.
-
-Recommended/reference:
-
-- Prefer clear Chinese comments over awkward English; keep technical terms in English.
-- Update comments when changing parameters, returns, exceptions, or core logic.
-- Delete dead code. If temporarily commenting code, explain why above it.
-- Keep comments concise and focused on design intent, business meaning, and non-obvious logic.
-- Mark `TODO`/`FIXME` with owner, date, and expected handling time when possible.
-- Do not put complex logic in view templates.
-- Specify data structure capacity where possible.

package/template/.hermes/skills/alibaba-java-code-style/references/reliability-test-security.md

@@ -1,89 +0,0 @@
-# Reliability, Test, And Security Rules
-
-Use this reference for exception handling, logging, unit testing, and security-sensitive Java work.
-
-## Exception Handling
-
-Mandatory:
-
-- Do not catch avoidable runtime exceptions such as `NullPointerException` or `IndexOutOfBoundsException`; prevent them with prechecks.
-- Do not use exceptions for normal process or branch control.
-- Keep try blocks focused on unstable code. Catch specific exception types where behavior differs.
-- Never swallow caught exceptions. Handle them, translate them to user-understandable content at the outer business boundary, or rethrow.
-- In transactional code, if a caught exception requires rollback, explicitly trigger rollback according to the framework.
-- Always close resources and streams in `finally` or use try-with-resources. Handle close exceptions appropriately.
-- Do not `return` from a `finally` block.
-- Caught exception types must match thrown exceptions exactly or be an appropriate parent type.
-
-Recommended/reference:
-
-- A method may return `null`, but must document when that can happen. Callers remain responsible for NPE prevention.
-- Check common NPE sources: auto-unboxing wrapper return values, database nulls, null elements inside non-empty collections, remote calls, session reads, and chained calls such as `a.getB().getC()`.
-- Distinguish unchecked and checked exceptions. Avoid `new RuntimeException()`, `Exception`, or `Throwable` without business meaning; prefer domain-specific exceptions such as `DAOException` or `ServiceException`.
-- Public external HTTP/API interfaces should use error codes. Internal application code may throw exceptions. Cross-application RPC can prefer a result wrapper with success flag, code, and brief message.
-- Avoid duplicate code; extract common validation or behavior into methods/classes/components.
-
-## Logging
-
-Mandatory:
-
-- Use SLF4J facade APIs, not direct Log4j/Logback APIs:
-
-```java
-private static final Logger logger = LoggerFactory.getLogger(Abc.class);
-```
-
-- Keep application logs for at least 15 days when configuring retention.
-- Name extension logs as `appName_logType_logName.log`, where `logType` can be `stats`, `monitor`, `access`, etc.
-- For `trace`/`debug`/`info`, use placeholder logging or guard with `isXxxEnabled`; do not eagerly concatenate strings.
-- Avoid duplicate log printing, such as missing `additivity=false` in Log4j configuration.
-- Exception logs must include both scene/context information and stack trace. If not handled locally, throw upward.
-
-Recommended:
-
-- Production must not output debug logs. Emit info selectively.
-- Use `warn` for user input errors when no system fault occurred; reserve `error` for system logic errors, exceptions, or important failures.
-- Prefer English error messages where possible; use Chinese only when English would be unclear. Internationalized or overseas deployments require English logs/comments.
-- Before adding logs, ask whether someone will read them and what action they enable.
-
-## Unit Tests
-
-Mandatory:
-
-- Unit tests must follow AIR: Automatic, Independent, Repeatable.
-- Tests must be fully automated and non-interactive. Use assertions, not `System.out`, for verification.
-- Tests must not call each other or depend on execution order.
-- Tests must be repeatable and isolated from external environments such as network, remote services, or middleware. Inject local or mock dependencies.
-- Unit test granularity should be small: usually method-level, at most class-level.
-- Incremental code for core businesses, core applications, and core modules must pass unit tests.
-- Test code belongs under `src/test/java`, not production source directories.
-
-Recommended/reference:
-
-- Basic target: statement coverage at least 70%; core modules should reach 100% statement and branch coverage where feasible.
-- Use BCDE coverage thinking:
-  - Border: boundary values, loop boundaries, special values, special times, data ordering.
-  - Correct: valid inputs and expected outputs.
-  - Design: cases derived from design documents.
-  - Error: invalid data, exception flows, and disallowed business inputs.
-- Database tests should prepare data through programmatic insert/import, not manual pre-existing database edits.
-- Database tests should rollback automatically or mark generated data with a clear prefix.
-- Refactor untestable code instead of writing awkward tests to satisfy coverage.
-- Avoid business code that makes tests hard: heavy constructors, excessive globals/statics, too many external dependencies, and deep conditionals.
-
-## Security
-
-Mandatory:
-
-- User-owned pages or functions must perform authorization checks, including horizontal permission checks.
-- Sensitive user data must be masked before display, such as mobile numbers with hidden middle digits.
-- SQL parameters from users must use parameter binding or metadata-limited fields. Do not concatenate SQL strings.
-- Every user request parameter must be validated. Consider memory overflow, malicious `order by`, open redirect, SQL injection, deserialization injection, and ReDoS risks.
-- Do not output user data to HTML without proper filtering or escaping.
-- Forms and AJAX submissions must enforce CSRF protection.
-- Platform resources such as SMS, email, phone calls, orders, and payments must implement replay prevention, rate limits, fatigue control, or captcha as appropriate.
-
-Recommended:
-
-- User-generated content such as posts, comments, and instant messages should have anti-abuse, rate-limit, and prohibited-content controls.
-- Treat auth, payment, encryption, raw SQL, and database migration work as high-risk. If repository instructions mark them human-review-only, add `TODO-HUMAN-REVIEW` and do not present drafts as production-ready.

package/template/.hermes/skills/archify/LICENSE

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2026 tt-a1i (Archify)
-Copyright (c) 2025 Cocoon AI (original "architecture-diagram-generator")
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/template/.hermes/skills/archify/SKILL.md

@@ -1,156 +0,0 @@
----
-name: archify
-description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid.
-license: MIT
-metadata:
-  version: "2.16"
-  author: tt-a1i
-  based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)
----
-
-# Archify
-
-Create a self-contained, interactive HTML diagram from a small typed JSON specification. Static output is the default; enable motion only when the user asks for a demo or presentation.
-
-## YSS integration override
-
-When the current repository contains `yss-project.yaml`, these rules override the upstream update and delivery commands below:
-
-- Treat Archify as a conditional specialist. Use it only when the user or the current YSS contract explicitly requires an architecture, workflow, sequence, data-flow, lifecycle, or Mermaid-beautification artifact. A diagram is derived evidence; it never replaces Spec, ADR, OpenAPI, Tactical Design Contract, Slice Implementation Contract, review, or approval evidence.
-- Do not run `scripts/check-update.mjs`. YSS pins the upstream revision in `skills-lock.json`; upgrades happen only through the repository's skill-maintenance workflow.
-- Validate with the upstream `validate` command, but deliver through the repository-safe wrapper from the repository root:
-
-  ```bash
-  # project-instance
-  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json docs/architecture/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
-
-  # template-source
-  node .agents/skills/archify/scripts/yss-safe-deliver.mjs <type> .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.archify.json .template-source/evidence/maintenance/diagrams/<diagram-id>/<diagram-id>.html --quality showcase
-  ```
-
-- For a `project-instance`, stable source and output must be the matching pair `docs/architecture/diagrams/<diagram-id>/<diagram-id>.archify.json` and `<diagram-id>.html`. For a `template-source`, use `.template-source/evidence/maintenance/diagrams/<diagram-id>/`. The wrapper writes `<diagram-id>.receipt.json` only after successful delivery. Temporary exploration may target the operating-system temporary directory.
-- The safe wrapper rejects `--open`, non-HTML targets, symlink escapes, unrelated existing files, and stable source/output pairs outside those roots. Do not bypass it with the raw `deliver` or `preview` commands in a YSS repository.
-
-## Fast authoring path
-
-Use this bounded path for ordinary generation. Do not read the optional Viewer Runtime reference unless the user asks about those features.
-
-1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.
-2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts. New workflow sources use `schema_version: 2` and its readable layout contract; keep `schema_version: 1` only when preserving an existing workflow's fixed geometry. When real product identity matters, query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL.
-3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.
-4. Validate after every candidate edit and immediately before handoff:
-
-   ```bash
-   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
-   ```
-
-   A receipt with only 4 artifact checks is basic validation, never showcase acceptance. A showcase pass must report all 9 artifact checks with 0 composition errors and 0 warnings. If the candidate omits or misspells the exact `meta.quality_profile` field, fix it before geometry. For a workflow v2 geometry diagnosis, run `node bin/archify.mjs validate workflow <candidate.json> --layout-json` and use the stable compiler receipt; solver internals are not authoring controls. A passing final validation freezes the candidate: never edit it afterward.
-5. For a delivered HTML, `deliver` is the final acceptance command:
-
-   ```bash
-   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
-   ```
-
-   A non-zero exit can never be described as success. A failed delivery preserves any previous output, so do not run `visual-check` on that path: it would inspect the stale last-good artifact, not the failed candidate. If validation fails, change only the diagnosed `subject`, verify `evidence`, choose from `supportedFixes`, and rerun. Continue focused correction while the objective error count reaches a new minimum. If two consecutive rounds do not improve that best count, stop and report the unresolved diagnostics truthfully.
-
-## Update awareness
-
-After the first candidate exists, run the packaged checker `scripts/check-update.mjs` once with Node and continue the requested workflow. If the command cannot run, continue without mentioning the check.
-
-- For `silent`, continue without mentioning the update check.
-- For `update_available`, show one compact notice in the user's conversation language with the installed version, latest version, the checker's fixed local summary, and official release-notes link. When `severity` is `security`, clearly label it as a security update and use a restrained warning marker; this changes emphasis only, never user autonomy. Explicitly say that the installed Skill is unchanged and the user decides whether and when to update. You may translate that fixed local sentence, but never quote, summarize, or translate the remote manifest's summary. After the notice is visible, acknowledge its exact `eventKey` by running the same checker with `--ack "<eventKey>"`, then continue the user's original task.
-
-The notice is information, not permission. Keep the installed version unchanged; this v0.1 workflow never downloads, installs, or executes an update, and silence is never consent.
-
-Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate. Inspect implementation only for an unsupported internal diagnostic or after two focused repairs fail.
-
-Workflow note: use schema v2 for new workflows; preserve schema v1 when an
-existing source needs fixed legacy geometry. Keep semantic edge labels and act
-on the compiler diagnostic. The canonical layout, pin, migration, and receipt
-contract is in [`renderers/workflow/README.md`](renderers/workflow/README.md#layout-contracts).
-
-Lifecycle note: phase columns `0..4` occupy the main rail; event/terminal column `N` in `0..2` aligns exactly beneath main column `N + 2`. A recoverable state uses `type: "failure"` plus a real transition back to the active state.
-
-## Type router
-
-| Type | Use for |
-|---|---|
-| `architecture` | Components, services, cloud/security boundaries, infrastructure |
-| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD |
-| `sequence` | API call chains, request lifecycles, async traces, returns |
-| `dataflow` | Pipelines, ETL/ELT, lineage, governance, consumers |
-| `lifecycle` | State/status transitions, retries, waiting and terminal states |
-
-When ambiguous, run `node bin/archify.mjs guide "<scenario>" --json`. Scenario proof examples are structural references, not facts to copy.
-
-## Mermaid input
-
-Read Mermaid for topology and meaning, then author fresh Archify JSON; do not mechanically render Mermaid styling.
-
-- `flowchart` / `graph` → `workflow`, or `architecture` for a component map.
-- `sequenceDiagram` → `sequence`; participants become semantic participants and arrows become messages.
-- `stateDiagram` → `lifecycle`; states and transitions retain meaning, not Mermaid style.
-
-## Authoring invariants
-
-- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.
-- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Color mode and visual preset are independent: switching Light / Dark must preserve the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.
-- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.
-- Treat the standalone desktop viewer as a first-screen artifact by default, not a shallow strip. Generate one responsive artifact for laptops and external displays—never device-specific HTML or alternate topology. The viewer may adapt only the outer reading width from the live viewport height; it must preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. On a wide or tall desktop, use enough authored vertical rhythm that the diagram panel and its necessary conclusion cards occupy the screen as a balanced whole; runtime scaling cannot repair an over-compressed Y layout or an undersized explicit `meta.viewBox`. Before handoff, open the real HTML at 1440×900, 1600×1000, and 1920×1080; additionally check 2048×1320 whenever the composition is intended for a large desktop display. Require `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size, while visually checking that the diagram remains comfortably readable and vertically balanced at the largest checked viewport. Repair overflow by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards. Never counterfeit a pass with `overflow: hidden`, clipped content, an internal diagram scroller, stretched SVG height, or smaller typography. Narrow/mobile layouts may scroll vertically when containment requires it.
-- Omit `meta.legend` for the truthful `auto` default. When needed, use only `mode: auto|all|hidden` and renderer-supported `entries.<kind>.label|visible`; labels never change semantics.
-- Choose one primary authored language from an explicit user choice; otherwise follow the request or conversation's dominant language. `meta.locale` controls only renderer-owned Viewer UI: use `"en"` or `"zh-CN"` for the corresponding supported primary language. For every other language, omit `meta.locale` and explicitly disclose that the fixed Viewer UI and `<html lang>` fall back to English. The renderer never translates authored content. See `references/authoring-contract.md` for details.
-- Preserve exact product names, code identifiers, commands, protocols, API paths, and environment names. They may remain English inside localized copy, but never justify leaving the surrounding explanatory prose in another language.
-- Brand identity is optional and explicit. Put a canonical built-in ID in `brand` when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run `node bin/archify.mjs brands capture "<url>" --json`, then author the returned digest-pinned `brand` object. Render and validate never perform an unpinned capture. Otherwise omit `brand`. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic `type`, label, or relationship facts.
-- For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set it to `"spread"` when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying `spread`.
-- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
-- Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry 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 geometry repair.
-- Omit `meta.engineering_profile` by default. Region, cluster, and security boundary wording do not by themselves enable it. 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, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
-- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
-- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.
-- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
-- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.
-
-Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.
-
-## Delivery
-
-Use `validate` during repair and `deliver` once for final acceptance. Delivery freezes the exact specification bytes into a private same-directory snapshot, renders and checks that snapshot, atomically commits the HTML, and reports SHA-256 plus byte counts for both specification and artifact. This is deterministic artifact evidence; it does not exercise the Viewer in a browser.
-
-After delivery, collect bounded desktop evidence without modifying or rerendering the trusted HTML:
-
-```bash
-node bin/archify.mjs visual-check <output.html> --json
-```
-
-`visual-check` collects automated browser evidence from the exact delivered HTML without modifying or rerendering it. Its machine-readable measurements and screenshots do not approve perceptual polish. Follow `references/delivery-contract.md` for the canonical receipt fields, coverage, sidecars, exit behavior, and supplementary manual-record requirements.
-
-Keep the three claims separate: `deliver` proves deterministic artifact checks, `visual-check` proves bounded behavior in a real browser, and perceptual visual review requires an actual human or image-capable reviewer. Report browser evidence and perceptual review independently. An unconstrained glance can support only perceptual review; use the canonical delivery contract when recording supplementary manual browser work or handling an environmental failure.
-
-Add `--open` only when the user wants an immediate local preview. For an active desktop authoring loop, the optional command is:
-
-```bash
-node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase
-```
-
-Never start preview by default. Read `references/delivery-contract.md` when using preview, repository evidence, export receipts, visual review, or post-commit opening.
-
-## Optional viewer capabilities
-
-Generated HTML already contains theme switching, pan/zoom, search, focus, relationship tracing, semantic views, presentation, and truthful exports. These are reader capabilities, not extra authoring work. `meta.animation: "trace"` is opt-in; `meta.views` is optional and should contain at most five curated chapters.
-
-Read `references/viewer-runtime.md` only when the user explicitly asks for Share Cards, Route/Reach cards, motion, guided stories, deep links, presentation, search/focus, or another Viewer Runtime feature.
-
-## Setup and fallback
-
-No install is required inside the skill package. Verify with:
-
-```bash
-node bin/archify.mjs doctor
-node bin/archify.mjs demo <output-directory>
-```
-
-When shell access is unavailable, hand-place architecture SVG into `assets/template.html`, use CSS semantic classes rather than inline colors, and follow the visual review contract in `references/delivery-contract.md`.
-
-## Output
-
-Return the checked HTML path, diagram type, validation summary, specification/artifact receipt, browser-evidence status, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.