Tracking: improve first-diagram reliability, readability, and maintenance focus

[tt-a1i]

Objective

Make an ordinary Agent's path from a bounded system description to a readable, verified diagram more reliable and less expensive to repair. Use the existing issues below as the implementation owners, with one selected approach per behavior.

Assessment baseline: 920543baa1c6137803c5b45a69d8977152773d35, checked on 2026-09-08. Local reproduction used that commit's tracked archify.zip (2.17.0-dev.1) on macOS, Node v26.3.0, and Chrome. The CI run for the same commit passed.

Current maintenance status — 2026-09-08

This section records the current maintainer decisions. The assessment below remains historical evidence from its stated baseline, not a description of current main.

Work item	Current disposition	Next action / boundary
#332 credential-safe evidence	Completed; issue closed.	Preserve credential redaction regression coverage.
#324 packaged examples	Completed via merged #325; issue closed.	Preserve the packaged examples' browser checks.
#143 / #301 portable repository evidence	Completed via merged #354 (b86b607); both issues closed.	Keep GitHub/Gitee web links and other hosts' local-only validation as the bounded supported scope. No broad forge-adapter expansion.
#242 / #277 offline fonts	#256 remains open at 502c22e; 12 CI checks and CodeRabbit status pass. Independent collaborator approval is still required.	Do not bypass last-push approval. Triage the two latest bot suggestions about package-wide font detection and positive staging coverage before final acceptance; a green bot status is not a resolved review thread.
#340 / #282 default typography / authored scale	Deferred by maintainer decision; issues remain open.	Do not change default font sizing or add a typography-scale contract in this workstream. Retain the existing Viewer zoom controls. This is a scope decision, not a claim that zoom proves default readability is satisfactory.
#175 / #214 / #336 generation efficiency and repair rounds	Open; not established as solved. #353 has collaborator approval and passing CI at 62e7c4d.	#353 is a bounded workflow-overflow diagnostic improvement. Its Luna trial failed before the new guidance was exercised, so it does not demonstrate fewer repair rounds. Rebase/revalidate against current main before integration, then evaluate matched tasks while retaining failures and timeouts. Do not close these issues from diagnostic tests alone.
#343 Viewer source organization	Open; not implemented.	Keep at P2. Inventory dependencies for one capability before selecting a small extraction. No broad rewrite or framework migration.

Active sequence

1. Finish fix(viewer): embed the viewer font so delivered pages stay self-contained #256 review and resolve any confirmed remaining findings; merge only after the required independent approval and current-head checks.
2. Integrate/evaluate the bounded fix(visual-check): explain workflow overflow with measured lane evidence #353 diagnostic slice without expanding its claim into general layout convergence. Keep first-pass success, repair rounds, and elapsed time separate.
3. Use that evidence to select one next slice under perf: reduce multi-diagram generation latency without weakening quality gates #175/Showcase validation convergence is very slow for modestly dense diagrams (~25 rounds for an 8-node architecture map) #214/Feature: plan-first mode for manual edge routing in skill instructions #336. Keep refactor(viewer): modularize source incrementally while preserving standalone HTML #343 queued until one concrete extraction boundary and compatibility evidence are agreed.

#344 stays open. Implementation merged into main is distinct from a published release; a deferred item is distinct from a completed fix.

Evidence and proposed sequence

Priority	Work item	Existing owner and acceptance direction
P0	Credential-safe repository evidence	#332 — same-repository credentialed HTTPS must verify, and every diagnostic surface must redact credentials. Independent reproduction.
P1	A usable installed starting point	#324 — all five bundled examples must pass the required real-browser viewport checks. Independent reproduction. Preserve meaningful nodes, relationships, labels, cards, and the existing quality gates.
P1	Earlier feedback and fewer repair rounds	#175, #214, #336 — expose usable layout/viewport budgets earlier and provide evidence-based repair guidance; compare matched tasks before selecting a solution.
P1	Comfortable default typography	#340, #282 — evaluate font size, node dimensions, wrapping, and canvas layout together, with real Chinese and English content and browser review.
P1	Portable evidence and offline delivery	#301/#143 and #242/#277 — separate local Git verification from provider-specific source links; select and test a predictable offline font strategy.
P2	Bounded Viewer maintenance	#343 — extract one cohesive source capability while retaining deterministic, single-file delivery and installed-Skill compatibility.

Specific observations behind this ordering:

• Three packaged examples fail all four desktop containment checks. Fresh Data Flow delivery still reports 9/9 with zero errors and warnings and produces the exact same failing HTML. Deterministic delivery, browser evidence, and perceptual review need distinct results throughout the workflow.
• The current projected node-text floor is 6px. In the audited default Architecture example, the minimum measured node text was 8.65px. Passing the existing floor does not establish comfortable reading.
• Repository identity currently restricts evidence to GitHub, while the Viewer template requests Google Fonts.
• The approximately 25 repair rounds in Showcase validation convergence is very slow for modestly dense diagrams (~25 rounds for an 8-node architecture map) #214 are the reporter's observation. This audit did not rerun that Agent session or establish a current model-wide success rate.

Scope and contribution coordination

• Begin with credential safety and the five packaged examples; then evaluate the convergence and reading improvements on fixed inputs.
• Keep about 3–5 work items actively progressing, with an explicit implementation owner and acceptance evidence for each.
• Resolve overlapping approaches before expanding implementation. CLI SVG export already has feat: add CLI export command for SVG output #264, feat: add standalone SVG delivery #272, and Add archify export svg for a standalone, styled SVG #328; choose one public command/receipt contract and one primary implementation.
• Sequence new diagram types and additional animation surfaces after these reliability improvements.
• This tracker proposes priorities and acceptance evidence. Linked PRs still require their own compatibility assessment and review.

Acceptance evidence

• [Bug]: repository-evidence rejects credentialed HTTPS remotes and echoes raw origin in diagnostics #332's same-identity case passes and synthetic credentials are absent from all relevant failure outputs.
• The extracted ZIP's five examples pass real Chrome checks at 1440 × 900, 1600 × 1000, 1920 × 1080, and 2048 × 1320, retaining light/dark captures and separate perceptual review.
• Fixed tasks, model settings, source revisions, and package identity are recorded before the convergence comparison. Keep failed and timed-out runs in the results.
• Report first-pass usability, repair-round distribution, and time to a verified artifact separately; demonstrate improvement without losing required semantic content or visual quality.
• Deferred by maintainer decision: changes to default typography / authored scale (架构图中字体太小，看起来费眼睛 #340/[Feature][Architecture] Add an authored typography scale for wide presentation diagrams #282). Existing zoom remains available; this item is not marked as a completed readability improvement.
• Internal-repository and offline-font changes preserve origin/revision/path verification and are checked in their target environments.
• Keep Windows-specific reports such as [Bug]: fs.watch-based live preview crashes with a native libuv assertion on short-name-aliased Windows paths #310 explicitly unverified until reproduced on the affected Windows setup.