thursday-agent 0.5.0 → 0.7.0

package/skills/interactive-page/scripts/archify/recipes/scenarios.mjs

@@ -0,0 +1,284 @@
+const RAW_RECIPES = [
+  {
+    id: 'system-overview', type: 'architecture', proof: 'web-app',
+    presentation: { preset: 'classic', motion: 'static', views: 'optional' },
+    start: {
+      en: { descriptionPrompt: 'Use Archify to turn this plain-language system description into a high-level architecture diagram: [describe the users, core components, primary path, external dependencies, and boundaries]. No repository is required. Ask only for missing facts that would materially change the diagram, mark any remaining unknowns instead of inventing them, and keep one obvious primary path across 8–12 core components.' },
+    },
+    signals: [['system overview', 12], ['architecture', 10], ['components', 6], ['services', 4], ['repository', 5], ['trust boundary', 8]],
+    en: {
+      title: 'System overview', question: 'What exists, who owns it, and how is it connected?',
+      summary: 'A bounded map of core components, external dependencies, primary paths, and trust boundaries.',
+      useWhen: 'Onboarding, design reviews, repository orientation, or explaining a service landscape.',
+      avoidWhen: 'The audience needs exact call order, state transitions, or row-level data lineage.',
+      include: ['8–12 core components', 'one primary path', 'external dependencies', 'trust boundaries'],
+      prompt: 'Analyze this repository, then use Archify to create a high-level architecture diagram. Show 8–12 core runtime components, one primary request or data path, external dependencies, ownership or trust boundaries, and put supporting detail in cards instead of adding more edges.',
+    },
+  },
+  {
+    id: 'deployment-ownership', type: 'architecture', proof: 'deployment-ownership',
+    presentation: { preset: 'blueprint', motion: 'trace', views: 'recommended' },
+    signals: [['deployment topology', 14], ['region', 7], ['vpc', 9], ['cluster', 6], ['availability zone', 8], ['ownership', 7], ['cloud deployment', 12]],
+    en: {
+      title: 'Deployment ownership', question: 'Where does each workload run, and what crosses a boundary?',
+      summary: 'A deployment-focused map of regions, networks, clusters, workloads, stores, and cross-boundary mechanisms.',
+      useWhen: 'Cloud reviews, production readiness, multi-region planning, or infrastructure ownership handoffs.',
+      avoidWhen: 'Deployment facts are unknown or the real question is application behavior rather than placement.',
+      include: ['regions and networks', 'workload ownership', 'stateful services', 'named boundary crossings'],
+      prompt: 'Use Archify to draw the production deployment topology. Group resources by region, network, cluster, and owner; show workloads and stateful services; label every cross-boundary mechanism. Do not invent deployment facts—mark unknown areas explicitly. If the user wants a fail-closed deployment review, ask before setting meta.engineering_profile to deployment-ownership; otherwise leave the engineering profile unset.',
+    },
+  },
+  {
+    id: 'agent-tool-call', type: 'workflow', proof: 'agent-tool-call',
+    presentation: { preset: 'signal-flow', motion: 'trace', views: 'recommended' },
+    start: {
+      en: { descriptionPrompt: 'Use Archify workflow mode to turn this description into a diagram: [paste the actors, main steps, decisions, approvals, and exception paths]. Use lanes for distinct owners, keep one unmistakable happy path, and mark missing ownership or unresolved branches instead of inventing them.' },
+    },
+    signals: [['agent tool call', 16], ['tool call', 12], ['approval gate', 10], ['human in the loop', 9], ['mcp', 7], ['planner', 6], ['agent loop', 10]],
+    en: {
+      title: 'Agent tool-call loop', question: 'How does an agent plan, get permission, act, recover, and report?',
+      summary: 'A lane-based agent loop with policy gates, tool execution, exception recovery, evidence, and final response.',
+      useWhen: 'Explaining agent runtimes, MCP/tool orchestration, approvals, retries, or observability.',
+      avoidWhen: 'The goal is only to show static agent components or exact API message timing.',
+      include: ['request and planning', 'policy or approval gate', 'tool execution', 'exception and evidence paths'],
+      prompt: 'Use Archify workflow mode to explain this agent tool-call loop. Separate user surface, agent runtime, policy boundary, exception handling, tool execution, and observability into lanes. Make the successful path primary and show approval, retry, blocked, and evidence paths explicitly.',
+    },
+  },
+  {
+    id: 'delivery-workflow', type: 'workflow', proof: 'delivery-workflow',
+    presentation: { preset: 'classic', motion: 'trace', views: 'optional' },
+    signals: [['ci/cd', 14], ['release workflow', 14], ['deployment pipeline', 11], ['pull request', 7], ['staging', 7], ['rollback', 8]],
+    en: {
+      title: 'Delivery workflow', question: 'How does a change move safely from commit to production?',
+      summary: 'A delivery flow with build, checks, environments, approvals, smoke tests, rollback, and ownership lanes.',
+      useWhen: 'CI/CD design, release reviews, deployment governance, or onboarding developers to delivery.',
+      avoidWhen: 'The question is where infrastructure runs or what states a deployment object can occupy.',
+      include: ['trigger and build', 'blocking checks', 'approval and environments', 'rollback and verification'],
+      prompt: 'Use Archify workflow mode to draw this delivery process from commit to production. Separate developer, CI, approval, environment, and exception lanes; mark blocking checks, smoke tests, ownership, and the rollback path. Keep one unmistakable happy path.',
+    },
+  },
+  {
+    id: 'incident-runbook', type: 'workflow', proof: 'incident-runbook',
+    presentation: { preset: 'signal-flow', motion: 'trace', views: 'recommended' },
+    signals: [['incident response', 15], ['runbook', 12], ['outage', 9], ['triage', 8], ['mitigation', 8], ['escalation', 7]],
+    en: {
+      title: 'Incident runbook', question: 'How do responders detect, triage, mitigate, verify, and escalate?',
+      summary: 'An operational workflow that separates signals, responders, mitigation, communications, and recovery proof.',
+      useWhen: 'Incident playbooks, on-call handoffs, reliability reviews, and tabletop exercises.',
+      avoidWhen: 'The audience needs live metrics or a post-incident component topology instead of response actions.',
+      include: ['detection signal', 'triage owner', 'mitigation and rollback', 'verification and communication'],
+      prompt: 'Use Archify workflow mode to turn this incident runbook into responder lanes. Show detection, triage, mitigation, escalation, communication, rollback, and recovery verification. Separate decision gates from actions and make missing ownership visible.',
+    },
+  },
+  {
+    id: 'api-request', type: 'sequence', proof: 'cache-miss',
+    presentation: { preset: 'classic', motion: 'trace', views: 'optional' },
+    start: {
+      en: { descriptionPrompt: 'Use Archify sequence mode to draw this interaction: [paste the participants, calls, returns, fallback, and asynchronous side effects]. Keep message order unambiguous, labels short, and unknown behavior explicit. No repository is required.' },
+    },
+    signals: [['api request', 14], ['request response', 12], ['call chain', 11], ['cache miss', 13], ['jwt', 8], ['who calls whom', 12]],
+    en: {
+      title: 'API request chain', question: 'Who calls whom, in what order, and what returns?',
+      summary: 'A time-ordered request path with authentication, cache fallback, persistence, return traffic, and async trace.',
+      useWhen: 'API documentation, debugging request latency, auth reviews, or explaining cache fallback.',
+      avoidWhen: 'Order is unimportant and the audience only needs the stable service topology.',
+      include: ['callers and callees', 'request and return messages', 'fallback or error path', 'async side effects'],
+      prompt: 'Use Archify sequence mode to show this request from caller to final response. Include authentication, cache hit or miss, persistence fallback, return messages, and asynchronous trace or event emission. Keep message labels short and order unambiguous.',
+    },
+  },
+  {
+    id: 'async-roundtrip', type: 'sequence', proof: 'async-roundtrip',
+    presentation: { preset: 'signal-flow', motion: 'trace', views: 'recommended' },
+    signals: [['async roundtrip', 14], ['webhook', 10], ['callback', 10], ['acknowledgement', 8], ['timeout', 7], ['retry message', 8], ['webhook', 10]],
+    en: {
+      title: 'Async roundtrip', question: 'What happens after the initial request returns?',
+      summary: 'A sequence view of enqueue, acknowledgement, background work, callbacks, retries, timeout, and final consistency.',
+      useWhen: 'Webhooks, jobs, queues, payment callbacks, eventual consistency, or async API contracts.',
+      avoidWhen: 'The primary question is topic topology and consumer ownership rather than time order.',
+      include: ['initial acknowledgement', 'queue or scheduler', 'background work', 'callback, retry, and timeout'],
+      prompt: 'Use Archify sequence mode to explain this asynchronous roundtrip. Show the initial acknowledgement, enqueue or scheduling step, background processing, callback or polling, retry and timeout behavior, and the point where the caller can observe final consistency.',
+    },
+  },
+  {
+    id: 'data-lineage', type: 'dataflow', proof: 'product-analytics',
+    presentation: { preset: 'classic', motion: 'trace', views: 'recommended' },
+    signals: [['data lineage', 15], ['etl', 12], ['warehouse', 9], ['pii', 11], ['governance', 9], ['analytics pipeline', 12]],
+    en: {
+      title: 'Data lineage', question: 'Where does data come from, how does it change, and who consumes it?',
+      summary: 'A governed path from sources through consent, transforms, sensitive stores, warehouse, and consumers.',
+      useWhen: 'Analytics architecture, ETL/ELT review, PII assessment, warehouse design, or model feature lineage.',
+      avoidWhen: 'The audience needs request timing or operational task ownership rather than data assets.',
+      include: ['sources and assets', 'transform stages', 'classification or consent', 'stores and consumers'],
+      prompt: 'Use Archify dataflow mode to map this data lineage. Name every data asset and transform, show consent or classification boundaries, distinguish streaming from batch paths, and identify stores plus downstream consumers. Do not use unlabeled flows.',
+    },
+  },
+  {
+    id: 'event-stream', type: 'dataflow', proof: 'event-stream',
+    presentation: { preset: 'signal-flow', motion: 'trace', views: 'recommended' },
+    start: {
+      en: { descriptionPrompt: 'Use Archify dataflow mode to map this data journey: [paste the sources, data assets, transforms, stores, boundaries, and consumers]. Label every flow, distinguish streaming from batch where relevant, and mark unknown classifications or ownership instead of inventing them.' },
+    },
+    signals: [['event stream', 15], ['kafka topology', 14], ['topic', 8], ['consumer group', 11], ['dead letter', 10], ['dlq', 10]],
+    en: {
+      title: 'Event-stream topology', question: 'Which events move through which topics, processors, groups, and failure paths?',
+      summary: 'A stream map of producers, topics, ordered processors, consumer groups, state, replay, and DLQ.',
+      useWhen: 'Kafka/event-platform design, stream processing reviews, ownership, replay, and failure handling.',
+      avoidWhen: 'Topic names, consumer groups, and delivery semantics are not known—use a generic workflow instead.',
+      include: ['producers and event names', 'topics and ordering', 'processors and consumer groups', 'state, replay, and DLQ'],
+      prompt: 'Use Archify dataflow mode to draw this event-stream topology. Name producers, events, topics, ordered processors, consumer groups, state stores, replay paths, and the DLQ. Show ownership and delivery semantics only when supported by evidence.',
+    },
+  },
+  {
+    id: 'object-lifecycle', type: 'lifecycle', proof: 'agent-run',
+    presentation: { preset: 'classic', motion: 'trace', views: 'optional' },
+    start: {
+      en: { descriptionPrompt: 'Use Archify lifecycle mode to model this object: [paste its states, transition events, waits, retries, cancellation, and terminal outcomes]. Separate active, waiting, recoverable-failure, and terminal states, and never hide an ending. No repository is required.' },
+    },
+    signals: [['state machine', 15], ['object lifecycle', 14], ['status transition', 11], ['terminal state', 9], ['retry state', 8]],
+    en: {
+      title: 'Object lifecycle', question: 'Which states exist, what events move between them, and how does it end?',
+      summary: 'A state model with active work, waits, retries, cancellation, failure, and explicit terminal outcomes.',
+      useWhen: 'Tasks, orders, tickets, subscriptions, jobs, agent runs, or any durable object with status.',
+      avoidWhen: 'The object has no durable state and the real question is participant interaction over time.',
+      include: ['start and active states', 'event-labelled transitions', 'wait and retry states', 'all terminal outcomes'],
+      prompt: 'Use Archify lifecycle mode to model this object. Separate main progress, waiting or interruption states, and terminal outcomes. Label transitions with events, include retry, cancellation, timeout, success, and failure where real, and never hide an ending.',
+    },
+  },
+  {
+    id: 'deployment-lifecycle', type: 'lifecycle', proof: 'deployment-lifecycle',
+    presentation: { preset: 'signal-flow', motion: 'trace', views: 'recommended' },
+    signals: [['deployment lifecycle', 15], ['release state', 10], ['promotion state', 9], ['approval status', 8], ['rollback state', 10]],
+    en: {
+      title: 'Deployment lifecycle', question: 'What state is a release in, and what can happen next?',
+      summary: 'A deployment state model covering queued, building, verifying, approval, promotion, rollback, and terminal outcomes.',
+      useWhen: 'Release controllers, GitOps reconciliation, environment promotion, or deployment status APIs.',
+      avoidWhen: 'The question is the human/CI sequence of delivery actions rather than the deployment object state.',
+      include: ['queued and running states', 'verification and approval', 'promotion and rollback', 'success, failure, cancellation'],
+      prompt: 'Use Archify lifecycle mode to model the deployment object. Show queued, building, verifying, waiting for approval, promoting, rolling back, and every terminal outcome. Label the events and guards that permit each transition.',
+    },
+  },
+];
+
+export const SCENARIO_RECIPES = Object.freeze(RAW_RECIPES.map((recipe) => Object.freeze({
+  ...recipe,
+  presentation: Object.freeze({ ...recipe.presentation }),
+  ...(recipe.start ? { start: Object.freeze({
+    en: Object.freeze({ ...recipe.start.en }),
+  }) } : {}),
+  signals: Object.freeze(recipe.signals.map((signal) => Object.freeze(signal.slice()))),
+  en: Object.freeze({ ...recipe.en, include: Object.freeze(recipe.en.include.slice()) }),
+})));
+
+// This copy carries English only; a requested language resolves to it.
+export function detectGuideLanguage() {
+  return 'en';
+}
+
+export function startPromptsFor(recipe) {
+  const copy = recipe.en;
+  const descriptionPrompt = recipe.start?.en?.descriptionPrompt;
+  if (!descriptionPrompt) {
+    throw new Error(`Scenario recipe ${JSON.stringify(recipe.id)} does not define a start prompt.`);
+  }
+  const repositoryPrompt = recipe.type === 'architecture'
+    ? copy.prompt
+    : `Inspect this repository for evidence, then ${copy.prompt.charAt(0).toLowerCase()}${copy.prompt.slice(1)} Do not invent behavior that the code does not support.`;
+  return { descriptionPrompt, repositoryPrompt };
+}
+
+function normalized(value) {
+  return String(value || '').normalize('NFKC').toLowerCase().replace(/[\s_]+/g, ' ').trim();
+}
+
+function localized(recipe) {
+  const copy = recipe.en;
+  return {
+    id: recipe.id,
+    type: recipe.type,
+    proof: recipe.proof,
+    presentation: { ...recipe.presentation },
+    ...copy,
+    include: copy.include.slice(),
+  };
+}
+
+export function listScenarioRecipes() {
+  return SCENARIO_RECIPES.map((recipe) => localized(recipe));
+}
+
+function scoreRecipe(recipe, query) {
+  const text = normalized(query);
+  if (!text) return { recipe, score: 0, matched: [] };
+  if (text === recipe.id || text === recipe.id.replace(/-/g, ' ')) {
+    return { recipe, score: 100, matched: [recipe.id] };
+  }
+  let score = 0;
+  const matched = [];
+  for (const [signal, weight] of recipe.signals) {
+    if (text.includes(normalized(signal))) {
+      score += weight;
+      matched.push(signal);
+    }
+  }
+  return { recipe, score, matched };
+}
+
+export function recommendScenario(query) {
+  const ranked = SCENARIO_RECIPES.map((recipe) => scoreRecipe(recipe, query))
+    .sort((left, right) => right.score - left.score || SCENARIO_RECIPES.indexOf(left.recipe) - SCENARIO_RECIPES.indexOf(right.recipe));
+  const winner = ranked[0].score > 0 ? ranked[0] : { recipe: SCENARIO_RECIPES[0], score: 0, matched: [] };
+  const confidence = winner.score >= 14 ? 'high' : winner.score >= 7 ? 'medium' : 'low';
+  return {
+    ok: true,
+    mode: 'recommendation',
+    lang: 'en',
+    query: String(query || ''),
+    confidence,
+    matchedSignals: winner.matched.slice(),
+    recommendation: localized(winner.recipe),
+    alternatives: ranked.filter((entry) => entry.recipe.id !== winner.recipe.id && entry.score > 0)
+      .slice(0, 2)
+      .map((entry) => ({ ...localized(entry.recipe), score: entry.score })),
+  };
+}
+
+export function formatScenarioList() {
+  const heading = `Archify scenario recipes (${SCENARIO_RECIPES.length})`;
+  const intro = 'Choose the question before the diagram type. Run: archify guide "your scenario"';
+  return [heading, '', intro, '', ...listScenarioRecipes().flatMap((recipe) => [
+    `${recipe.id}  [${recipe.type}]  ${recipe.title}`,
+    `  ${recipe.question}`,
+  ])].join('\n');
+}
+
+export function formatScenarioRecommendation(result) {
+  const recipe = result.recommendation;
+  const labels = {
+    heading: 'Recommendation', question: 'Question answered', use: 'Use when', avoid: 'Avoid when', include: 'Must include', presentation: 'Presentation', prompt: 'Copy-ready prompt', alternatives: 'Other possible fits', confidence: 'Confidence',
+  };
+  const lines = [
+    `${labels.heading}: ${recipe.title}  [${recipe.type}]`,
+    `${labels.confidence}: ${result.confidence}`,
+    `${labels.question}: ${recipe.question}`,
+    '',
+    `${labels.use}: ${recipe.useWhen}`,
+    `${labels.avoid}: ${recipe.avoidWhen}`,
+    `${labels.include}: ${recipe.include.join('; ')}`,
+    `${labels.presentation}: ${recipe.presentation.preset} · ${recipe.presentation.motion} · views ${recipe.presentation.views}`,
+    '',
+    `${labels.prompt}:`,
+    recipe.prompt,
+  ];
+  if (result.alternatives.length) {
+    lines.push('', `${labels.alternatives}: ${result.alternatives.map((item) => `${item.title} [${item.type}]`).join(' · ')}`);
+  }
+  return lines.join('\n');
+}
+
+export function publicGuideData() {
+  return SCENARIO_RECIPES.map((recipe) => ({
+    ...localized(recipe),
+    en: recipe.en,
+    signals: recipe.signals.map(([signal, weight]) => [signal, weight]),
+  }));
+}

package/skills/interactive-page/scripts/archify/references/authoring-contract.md

@@ -0,0 +1,243 @@
+# 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. 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/interactive-page/scripts/archify/references/delivery-contract.md

@@ -0,0 +1,120 @@
+# 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.
+
+## 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.