Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
docs: clarify receipt binding and output paths
tt-a1id8f2a79581cf
diff --git a/archify.zip b/archify.zipindex cfd1d20b..ccf03d89 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex c52d8d51..76b10270 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -82,7 +82,7 @@ Use the `finalize` command above for the first candidate and after a repair.`finalize` stops at the first non-passing gate. Its compact stdout and `<output-stem>.finalize-summary.json` are ordinary evidence. A passing run creates no screenshots and reports `visualReview: "not-requested"`.-When a passing Architecture receipt reports `visualReviewRecommendation.signals.resolvedCrossovers`, copy the candidate aside and apply the hints in one edit that changes only node positions and sizes: every node, relationship (including its `from` and `to`), label, and source stays as it was. Rerun the complete `finalize` once with `--out-dir <folder>/review-2`, because the previous HTML already owns its browser evidence. `--out-dir` moves only evidence: the HTML is rewritten in place, and previously written same-directory sidecars are stale. If that run fails, reports more crossings, or reports the same crossings with more `signals.routesOverSuggestedBends`, restore the copy and finalize it with `--out-dir <folder>/review-3`. Do not start a second placement round. Hints about extra bends alone are optional.+When a passing Architecture receipt reports `visualReviewRecommendation.signals.resolvedCrossovers`, copy the candidate aside and apply the hints in one edit that changes only node positions and sizes: every node, relationship (including its `from` and `to`), label, and source stays as it was. Rerun the complete `finalize` once with `--out-dir <folder>/review-2`, because the previous HTML already owns its browser evidence. `--out-dir` relocates the new browser-check and default finalize receipts, not the HTML or its delivery receipt. Successful delivery rewrites that pair at the requested output path; earlier review evidence remains bound to its original artifact bytes. See [review evidence paths](references/delivery-contract.md#a-new-candidate-at-an-existing-output-path). If that run fails, reports more crossings, or reports the same crossings with more `signals.routesOverSuggestedBends`, restore the copy and finalize it with `--out-dir <folder>/review-3`. Do not start a second placement round. Hints about extra bends alone are optional.When `layoutReviewRecommendation.action` is `inspect-sequence-width`, follow [Sequence width review](references/delivery-contract.md#sequence-width-review) before handing off a newly authored Sequence.diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex a613720a..40124a45 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -2212,7 +2212,7 @@ function usage() {(Array.isArray(forms) ? forms : [forms]).map(form => ` archify ${command}${form ? ` ${form}` : ''}`));return `Usage:${commands.join('\n')}- (finalize --out-dir moves only evidence: the HTML is rewritten in place and old same-directory sidecars become stale)+ (finalize --out-dir relocates browser-check and default finalize receipts; HTML and its delivery receipt stay at the requested output path)Types:architecture, workflow, sequence, dataflow, lifecycle, erd, tree, class, timeline, waterfalldiff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex c8e1df89..bc7265d4 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -268,7 +268,7 @@ object with gate statuses, bounded actionable diagnostics, artifact identity,and evidence paths. The same compact object is written atomically to`<output-stem>.finalize-summary.json`; use that file for normal failure repair. When diagnostics are truncated, `diagnosticSummary.omittedByCode` counts the unshown entries by diagnostic code without replacing their full subject and repair evidence in the full receipt.Complete stage receipts and timings remain available for auditing in-`<output-stem>.finalize.json`. With `--out-dir`, both files are written there (evidence only; the artifact HTML is rewritten in place);+`<output-stem>.finalize.json`. With `--out-dir`, both files are written there (unless an explicit `--receipt` overrides the finalize receipt path; the artifact HTML stays at the requested output path);`--receipt <path.json>` overrides the full receipt path and derives a distinct`<path>-summary.json`. Read the full receipt only when the compact summary istruncated and its shown subjects and evidence cannot identify a coherent local@@ -562,13 +562,15 @@ a capable environment.## A new candidate at an existing output path-Browser evidence belongs to exact artifact bytes. After editing a candidate whose previous HTML already has browser evidence, choose a fresh evidence directory before running the next `finalize`; this preserves the old receipts and captures without an avoidable ownership-conflict retry. `--out-dir` moves only evidence: the artifact HTML is rewritten in place and rebound to new provenance, while previously written same-directory sidecars become stale and untrusted:+Browser evidence belongs to exact artifact bytes. After editing a candidate whose previous HTML already has browser evidence, choose a fresh evidence directory before running the next `finalize`; this preserves the old receipts and captures without an avoidable ownership-conflict retry. `--out-dir` relocates the new browser-check receipt and, by default, the finalize receipt and summary. An explicit `--receipt` overrides the finalize receipt path; its summary follows that path. Successful delivery still rewrites the requested HTML and its sibling `*.delivery.json`. Earlier browser or visual evidence remains bound to its original artifact bytes and must not be treated as evidence for changed HTML:```bashnode bin/archify.mjs finalize architecture candidate.json diagram.html --quality showcase --repo-root <root> --out-dir diagram.review-2 --jsonnode bin/archify.mjs visual-check diagram.html --out-dir diagram.review-2 --summary --require-provenance```+The evidence directory is not an archive of the HTML. Copying the HTML there alone does not rebind receipt paths or provenance. If a historical snapshot is needed, preserve the candidate and artifact separately before overwriting them; do not assume copied receipts validate a relocated artifact.+Keep the requested HTML path stable. Use a new revision directory for each changed candidate, and retain the same directory for retries of unchanged bytes. For a diagram without repository evidence, omit `--repo-root`. Let the commands create their output directory. A prior validation failure that produced no HTML or browser evidence needs no new directory. Never remove unknown evidence to make a retry pass.## Optional opening