Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs: clarify finalize --out-dir moves only evidence (#921)

zhanhuangchao5908123ee563
diff --git a/archify.zip b/archify.zip
index 00baeb4d..04a05c57 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index cb313b9a..3385a8cc 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. 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` 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 `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.mjs
index 5a32f157..61e6a988 100755
--- a/archify/bin/archify.mjs
+++ b/archify/bin/archify.mjs
@@ -2212,6 +2212,7 @@ function usage() {
(Array.isArray(forms) ? forms : [forms]).map(form => ` archify ${command}${form ? ` ${form}` : ''}`));
return `Usage:
${commands.join('\n')}
+ (--out-dir moves only evidence; the HTML is rewritten in place and old same-directory sidecars become stale)
Types:
architecture, workflow, sequence, dataflow, lifecycle, erd, tree, class, timeline, waterfall
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index ddab4e8b..f538957d 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;
+`<output-stem>.finalize.json`. With `--out-dir`, both files are written there (evidence only; the artifact HTML is rewritten in place);
`--receipt <path.json>` overrides the full receipt path and derives a distinct
`<path>-summary.json`. Read the full receipt only when the compact summary is
truncated and its shown subjects and evidence cannot identify a coherent local
@@ -543,7 +543,7 @@ 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:
+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:
```bash
node bin/archify.mjs finalize architecture candidate.json diagram.html --quality showcase --repo-root <root> --out-dir diagram.review-2 --json