graphitect 0.2.0__py3-none-any.whl

graphify/wiki.py

@@ -0,0 +1,405 @@
+# Wiki export - Wikipedia-style markdown articles from the knowledge graph
+# Generates an agent-crawlable wiki: index.md + one article per community + god node articles
+from __future__ import annotations
+from collections import Counter
+from pathlib import Path
+import re
+import networkx as nx
+
+from graphify.build import edge_data
+from graphify.paths import stem_filename_budget
+
+# Room _unique_slug needs for the collision suffix ("_2" … "_9999") it appends
+# after _safe_filename has already capped the slug. The suffix is technically
+# unbounded, but 5 chars ("_" + 4 digits) covers ~10k identical stems, far past
+# anything real; sizing it to 3 digits let a 1000th collision overrun MAX_PATH.
+_SLUG_SUFFIX_RESERVE = 5
+
+# Characters a slug may not contain, because the article's LINK and its ON-DISK
+# NAME have to be the same string (#2597). Anything left here must be legal,
+# unescaped, in a CommonMark link destination:
+#   < > : " / \ | ? *   Windows-reserved in filenames (pre-existing set)
+#   ( )                 parentheses delimit/nest a link destination
+#   #                   starts a fragment, so `a#b.md` resolves to the file `a`
+#   %                   reads as the start of a percent-escape
+#   control chars       forbidden in a link destination, hostile in a filename
+#
+# Non-ASCII is deliberately NOT stripped. It is legal raw in a link destination
+# and resolves fine on every filesystem graphify targets; stripping it would
+# reduce a CJK, Cyrillic or accented wiki to a wall of underscores.
+_UNSAFE_SLUG_CHARS = re.compile(r'[<>:"/\\|?*#%\x00-\x1f\x7f]')
+
+
+def _safe_filename(name: str, limit: int = 200) -> str:
+    """Make a label safe for use as a filename across platforms AND as a
+    markdown link destination.
+
+    Substitutes characters that Windows reserves in filenames
+    (< > : " / \\ | ? *) plus the ones that would make the emitted link stop
+    matching the file on disk, and strips trailing dots/spaces, also reserved.
+    Falls back to 'unnamed' for empty results and caps length at ``limit``
+    chars (default 200) to stay well under common filesystem limits; ``to_wiki``
+    lowers ``limit`` when the wiki directory leaves less than that inside
+    Windows' MAX_PATH window (#2655).
+
+    Parentheses are DROPPED rather than substituted: every callable node is
+    labelled ``foo()``, and substituting would leave a trailing ``foo__`` on
+    each of them — and would mangle Python dunders (``__init__()`` ->
+    ``_init_``) if the resulting runs were then collapsed. Dropping keeps
+    ``__init__`` intact. Two labels that collapse to one slug are still
+    separated by ``_unique_slug``.
+    """
+    s = name.replace("/", "-").replace(" ", "_").replace(":", "-")
+    s = s.replace("(", "").replace(")", "")
+    s = _UNSAFE_SLUG_CHARS.sub('_', s)
+    s = s.strip('. ')
+    return s[:limit] if s else 'unnamed'
+
+
+def _md_link(label: str, resolver: dict[str, str]) -> str:
+    """Render a link to another wiki article as a portable relative markdown link.
+
+    ``resolver`` maps an article's display label to the slug (filename stem) it
+    was written under. When the label has an article, emit a standard
+    ``[label](slug.md)`` link whose target is the on-disk name VERBATIM.
+
+    The target is deliberately not percent-encoded (#2597). ``quote()`` turned
+    ``_make_id().md`` into ``_make_id%28%29.md`` while the file stayed raw, so
+    the link pointed at a path that does not exist. Renderers hid it by
+    decoding before resolving, but the wiki's whole purpose is to be
+    agent-crawlable, and an agent that reads the target off disk verbatim got a
+    FileNotFoundError. ``_safe_filename`` now keeps the slug free of everything
+    that would need encoding, so raw emission and the filename are the same
+    string by construction — one source of truth instead of two spellings that
+    happened to agree only for URL-safe labels.
+
+    The old ``[[label]]`` form only resolved inside Obsidian, because the
+    on-disk filename differs from the label — _safe_filename turns spaces into
+    underscores and substitutes reserved characters — so e.g.
+    ``[[Domain Data Models]]`` pointed at a non-existent
+    ``Domain Data Models.md`` everywhere else.
+
+    Labels with no article — most node-level links, since only communities and
+    god nodes get article files — render as plain text instead of a dead link
+    that points nowhere even inside Obsidian.
+    """
+    text = label.replace("[", r"\[").replace("]", r"\]")
+    slug = resolver.get(label)
+    if slug is None:
+        return text
+    return f"[{text}]({slug}.md)"
+
+
+def _cross_community_links(G: nx.Graph, nodes: list[str], own_cid: int, labels: dict[int, str], node_community: dict[str, int]) -> list[tuple[str, int]]:
+    """Return (community_label, edge_count) pairs for cross-community connections, sorted descending."""
+    counts: dict[str, int] = Counter()
+    for nid in nodes:
+        for neighbor in G.neighbors(nid):
+            ncid = node_community.get(neighbor)
+            if ncid is not None and ncid != own_cid:
+                counts[labels.get(ncid, f"Community {ncid}")] += 1
+    return sorted(counts.items(), key=lambda x: -x[1])
+
+
+def _community_article(
+    G: nx.Graph,
+    cid: int,
+    nodes: list[str],
+    label: str,
+    labels: dict[int, str],
+    cohesion: float | None,
+    node_community: dict[str, int] | None = None,
+    resolver: dict[str, str] | None = None,
+) -> str:
+    resolver = resolver or {}
+    top_nodes = sorted(nodes, key=lambda n: G.degree(n), reverse=True)[:25]
+    cross = _cross_community_links(G, nodes, cid, labels, node_community or {})
+
+    # Edge confidence breakdown, over every edge INCIDENT to the community (the
+    # cross-community ones included — those are disproportionately the uncertain
+    # edges, and AMBIGUOUS is what ARCHITECTURE.md flags for human review).
+    #
+    # ``G.edges(nbunch)`` reports each incident edge exactly once. Walking
+    # ``nodes x G.neighbors`` instead visited an edge once per endpoint inside
+    # the community, so an intra-community edge was counted TWICE while a
+    # crossing one was counted once. Intra-community edges are overwhelmingly
+    # the high-confidence EXTRACTED ones — that is what makes a community — so
+    # the split was biased towards confidence and understated the review
+    # burden. On a MultiGraph this also counts parallel edges individually
+    # rather than collapsing them to the first (``edge_data``), which is the
+    # same understatement: an AMBIGUOUS edge parallel to an EXTRACTED one used
+    # to be invisible here.
+    conf_counts: Counter = Counter(
+        d.get("confidence", "EXTRACTED") for *_, d in G.edges(nodes, data=True)
+    )
+    total_edges = sum(conf_counts.values()) or 1
+
+    sources = sorted({G.nodes[n].get("source_file") or "" for n in nodes} - {""})
+
+    lines: list[str] = []
+    lines += [f"# {label}", ""]
+
+    meta_parts = [f"{len(nodes)} nodes"]
+    if cohesion is not None:
+        meta_parts.append(f"cohesion {cohesion:.2f}")
+    lines += [f"> {' · '.join(meta_parts)}", ""]
+
+    lines += ["## Key Concepts", ""]
+    for nid in top_nodes:
+        d = G.nodes[nid]
+        node_label = d.get("label", nid)
+        src = d.get("source_file", "")
+        degree = G.degree(nid)
+        src_str = f" — `{src}`" if src else ""
+        lines.append(f"- **{node_label}** ({degree} connections){src_str}")
+    remaining = len(nodes) - len(top_nodes)
+    if remaining > 0:
+        lines.append(f"- *... and {remaining} more nodes in this community*")
+    lines.append("")
+
+    lines += ["## Relationships", ""]
+    if cross:
+        for other_label, count in cross[:12]:
+            lines.append(f"- {_md_link(other_label, resolver)} ({count} shared connections)")
+    else:
+        lines.append("- No strong cross-community connections detected")
+    lines.append("")
+
+    if sources:
+        lines += ["## Source Files", ""]
+        for src in sources[:20]:
+            lines.append(f"- `{src}`")
+        lines.append("")
+
+    lines += ["## Audit Trail", ""]
+    for conf in ("EXTRACTED", "INFERRED", "AMBIGUOUS"):
+        n = conf_counts.get(conf, 0)
+        pct = round(n / total_edges * 100)
+        lines.append(f"- {conf}: {n} ({pct}%)")
+    lines.append("")
+
+    lines += ["---", "", f"*Part of the graphify knowledge wiki. See {_md_link('index', resolver)} to navigate.*"]
+    return "\n".join(lines)
+
+
+def _god_node_article(G: nx.Graph, nid: str, labels: dict[int, str], node_community: dict[str, int] | None = None, resolver: dict[str, str] | None = None) -> str:
+    resolver = resolver or {}
+    d = G.nodes[nid]
+    node_label = d.get("label", nid)
+    src = d.get("source_file", "")
+    cid = (node_community or {}).get(nid)
+    community_name = labels.get(cid, f"Community {cid}") if cid is not None else None
+
+    lines: list[str] = []
+    lines += [f"# {node_label}", ""]
+    lines += [f"> God node · {G.degree(nid)} connections · `{src}`", ""]
+
+    if community_name:
+        lines += [f"**Community:** {_md_link(community_name, resolver)}", ""]
+
+    # Group neighbors by relation type
+    by_relation: dict[str, list[str]] = {}
+    for neighbor in sorted(G.neighbors(nid), key=lambda n: G.degree(n), reverse=True):
+        nd = G.nodes[neighbor]
+        ed = edge_data(G, nid, neighbor)
+        rel = ed.get("relation", "related")
+        neighbor_label = nd.get("label", neighbor)
+        conf = ed.get("confidence", "")
+        conf_str = f" `{conf}`" if conf else ""
+        by_relation.setdefault(rel, []).append(f"{_md_link(neighbor_label, resolver)}{conf_str}")
+
+    lines += ["## Connections by Relation", ""]
+    for rel, targets in sorted(by_relation.items()):
+        lines.append(f"### {rel}")
+        for t in targets[:20]:
+            lines.append(f"- {t}")
+        # The cap keeps god-node articles readable, but silently dropping the
+        # tail made the body disagree with the header's degree count with
+        # nothing telling the reader anything was cut (#3127). Entries are
+        # degree-sorted, so what is hidden is the low-degree tail.
+        if len(targets) > 20:
+            lines.append(
+                f"- *…and {len(targets) - 20} more `{rel}` "
+                f"connection(s) not listed (lowest-degree first to go)*"
+            )
+        lines.append("")
+
+    lines += ["---", "", f"*Part of the graphify knowledge wiki. See {_md_link('index', resolver)} to navigate.*"]
+    return "\n".join(lines)
+
+
+def _index_md(
+    communities: dict[int, list[str]],
+    labels: dict[int, str],
+    god_nodes_data: list[dict],
+    total_nodes: int,
+    total_edges: int,
+    resolver: dict[str, str] | None = None,
+) -> str:
+    resolver = resolver or {}
+    lines: list[str] = [
+        "# Knowledge Graph Index",
+        "",
+        "> Auto-generated by graphify. Start here — read community articles for context, then drill into god nodes for detail.",
+        "",
+        f"**{total_nodes} nodes · {total_edges} edges · {len(communities)} communities**",
+        "",
+        "---",
+        "",
+        "## Communities",
+        "(sorted by size, largest first)",
+        "",
+    ]
+
+    for cid, nodes in sorted(communities.items(), key=lambda x: -len(x[1])):
+        label = labels.get(cid, f"Community {cid}")
+        lines.append(f"- {_md_link(label, resolver)} — {len(nodes)} nodes")
+    lines.append("")
+
+    if god_nodes_data:
+        lines += ["## God Nodes", "(most connected concepts — the load-bearing abstractions)", ""]
+        for node in god_nodes_data:
+            lines.append(f"- {_md_link(node['label'], resolver)} — {node['degree']} connections")
+        lines.append("")
+
+    lines += [
+        "---",
+        "",
+        "*Generated by [graphify](https://github.com/safishamsi/graphify)*",
+    ]
+    return "\n".join(lines)
+
+
+def to_wiki(
+    G: nx.Graph,
+    communities: dict[int, list[str]],
+    output_dir: str | Path,
+    community_labels: dict[int, str] | None = None,
+    cohesion: dict[int, float] | None = None,
+    god_nodes_data: list[dict] | None = None,
+) -> int:
+    """Generate a Wikipedia-style wiki from the graph.
+
+    Writes:
+      - index.md            — agent entry point, catalog of all articles
+      - <CommunityName>.md  — one article per community
+      - <GodNodeLabel>.md   — one article per god node
+
+    Returns the number of articles written (excluding index.md).
+    """
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    if not communities:
+        raise ValueError(
+            "communities dict is empty — refusing to clear wiki/. "
+            "Run `graphify extract .` or `graphify cluster-only .` first."
+        )
+
+    # Filter stale node IDs that exist in communities but not in G.
+    # Analysis JSON can drift from the graph after dedup / re-extract / update.
+    # NetworkX 3.x returns DegreeView({}) for missing nodes instead of raising,
+    # which crashes sorted() with TypeError; G.neighbors()/G.nodes[] also raise.
+    import sys as _sys
+    _g_nodes = set(G.nodes)
+    _orig_total = sum(len(ns) for ns in communities.values())
+    communities = {cid: [n for n in nodes if n in _g_nodes] for cid, nodes in communities.items()}
+    communities = {cid: nodes for cid, nodes in communities.items() if nodes}
+    _kept_total = sum(len(ns) for ns in communities.values())
+    if _kept_total < _orig_total:
+        print(
+            f"wiki: dropped {_orig_total - _kept_total} stale node ID(s) not in graph "
+            f"({len(communities)} communities remaining)",
+            file=_sys.stderr,
+        )
+
+    if not communities:
+        raise ValueError(
+            "all community node IDs are stale — none exist in the graph. "
+            "Re-run `graphify extract .` to regenerate .graphify_analysis.json."
+        )
+
+    # Clear stale .md files from previous runs to prevent orphan accumulation.
+    # Community labels are LLM-generated (per skill.md Step 5) and non-deterministic
+    # across runs — the same conceptual community may be named differently each time
+    # (e.g. "AutoAgent Skills" → "AutoAgent Methodology"), leaving the previous file
+    # as an orphan. Since to_wiki() owns wiki/ entirely (always writes the full set),
+    # it can safely clear .md files at the start of each call.
+    for old_article in out.glob("*.md"):
+        old_article.unlink()
+
+    labels = community_labels or {cid: f"Community {cid}" for cid in communities}
+    cohesion = cohesion or {}
+    god_nodes_data = god_nodes_data or []
+
+    # Build node->community lookup once; node attrs never carry community (it lives in
+    # the communities dict), so _cross_community_links and _god_node_article need this.
+    node_community: dict[str, int] = {n: cid for cid, nodes in communities.items() for n in nodes}
+
+    count = 0
+    used_slugs: set[str] = set()
+
+    # Articles are capped against THIS wiki directory, not just NAME_MAX: on
+    # Windows a 200-char slug under an ordinary graphify-out/wiki/ overruns
+    # MAX_PATH and write_text raises FileNotFoundError partway through the
+    # export (#2655). No-op on POSIX.
+    _slug_limit = stem_filename_budget(out, reserve=_SLUG_SUFFIX_RESERVE)
+
+    def _unique_slug(base: str) -> str:
+        # Fold case in the collision check: two labels differing only by case
+        # (e.g. "Parser" vs "parser") resolve to one path on case-insensitive
+        # filesystems (macOS/APFS, Windows/NTFS), so they must dedup against each
+        # other while still emitting the original-case filename.
+        slug = base
+        n = 2
+        while slug.lower() in used_slugs:
+            slug = f"{base}_{n}"
+            n += 1
+        used_slugs.add(slug.lower())
+        return slug
+
+    # First pass: assign every article its slug before rendering any body, so the
+    # bodies can link to one another. A link's target is the on-disk filename (the
+    # slug), which differs from the label — _safe_filename turns spaces into
+    # underscores and substitutes reserved chars, and a slug may pick up a numeric
+    # suffix from collision dedup — so the final slug must be known up front.
+    # resolver maps display label -> slug; labels with no article are absent, so
+    # _md_link renders them as plain text. Communities are slugged before god nodes
+    # (and setdefault keeps the first), preserving the filename-assignment order
+    # the case-collision dedup relies on.
+    resolver: dict[str, str] = {"index": "index"}
+
+    community_slugs: dict[int, str] = {}
+    for cid in communities:
+        label = labels.get(cid, f"Community {cid}")
+        slug = _unique_slug(_safe_filename(label, _slug_limit))
+        community_slugs[cid] = slug
+        resolver.setdefault(label, slug)
+
+    god_articles: list[tuple[str, str]] = []  # (node_id, slug)
+    for node_data in god_nodes_data:
+        nid = node_data.get("id")
+        if nid and nid in G:
+            slug = _unique_slug(_safe_filename(node_data['label'], _slug_limit))
+            god_articles.append((nid, slug))
+            resolver.setdefault(node_data['label'], slug)
+
+    # Second pass: render and write each article with the full resolver in hand.
+    for cid, nodes in communities.items():
+        label = labels.get(cid, f"Community {cid}")
+        article = _community_article(G, cid, nodes, label, labels, cohesion.get(cid), node_community, resolver)
+        (out / f"{community_slugs[cid]}.md").write_text(article, encoding="utf-8")
+        count += 1
+
+    for nid, slug in god_articles:
+        article = _god_node_article(G, nid, labels, node_community, resolver)
+        (out / f"{slug}.md").write_text(article, encoding="utf-8")
+        count += 1
+
+    # Index
+    (out / "index.md").write_text(
+        _index_md(communities, labels, god_nodes_data, G.number_of_nodes(), G.number_of_edges(), resolver),
+        encoding="utf-8",
+    )
+
+    return count

graphitect/__init__.py

@@ -0,0 +1,28 @@
+"""graphitect - graph(ify) + (arch)itect.
+
+Orchestrates Graphify (structure) and archify (diagrams) to produce a
+sourced, confidence-tagged design doc alongside the architecture diagram.
+See plan.md in the project root for the full design.
+"""
+
+__version__ = "0.2.0"
+
+from .models import (
+    Claim,
+    Confidence,
+    DesignDocSection,
+    Evidence,
+    GroundedUnderstanding,
+    QuestionOption,
+    RationaleQuestion,
+)
+
+__all__ = [
+    "Claim",
+    "Confidence",
+    "DesignDocSection",
+    "Evidence",
+    "GroundedUnderstanding",
+    "QuestionOption",
+    "RationaleQuestion",
+]

graphitect/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

graphitect/_vendor/__init__.py

@@ -0,0 +1,2 @@
+"""Third-party runtimes bundled into the Graphitect distribution."""
+

graphitect/_vendor/archify/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI
+
+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.

graphitect/_vendor/archify/SKILL.md

@@ -0,0 +1,137 @@
+---
+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.17"
+  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.
+
+## 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.