Contributing to Archify

Archify is Agent-first: people describe systems, and the Skill, typed JSON, renderers, validators, and delivery receipts produce reproducible diagrams. Keep each contribution focused on one user-visible behavior or one tightly related delivery slice. Maintainers and Agents reviewing a PR or a revised head follow Reviewing.

Choose the right path

• Renderer, validator, package, or Viewer defect: use the bug report form.
• Standalone community package: follow the submission guide and submit one metadata file to dev.
• Reproducible real-world diagram: use the showcase form.
• Changes to generation, layout/routing, validation, interaction, performance, dependencies, tests, or other behavior require a related issue and explicit maintainer agreement on the problem, value, and intended scope before substantial implementation or a formal PR. Use the bug form for defects and the improvement proposal for changes. Link an existing issue or recorded maintainer decision when available; a second approval thread is unnecessary.
• Purely mechanical documentation corrections, such as typos or repairing a broken link to its intended destination, may go directly to a PR. Describe why the change is mechanical. Authoring instructions, new policy, behavioral documentation, and test changes are not exempt just because they are small or text-only.
• Security vulnerabilities: follow SECURITY.md.

Agreement on direction allows implementation to proceed; final acceptance still depends on the implementation, user-visible results, and maintenance cost. Draft PRs may support early discussion but do not replace scope agreement.

Do not include secrets, access tokens, credentials, private repository content, personal data, or customer data in fixtures, logs, screenshots, artifacts, or package tests.

Coordinate related work

These steps apply to contributors, maintainers, and Agents:

• Before implementing, search existing issues and open PRs for the same problem, including related fixes under review.
• On the relevant issue, state your intended scope. Link the agreed discussion in the PR; use a draft only when an implementation sketch helps that discussion. Apply the mechanical-correction exception above without a separate planning issue.
• If work is already in progress, discuss the remaining gap on that issue or PR and agree on collaboration, a distinct scope, or consolidation before starting an overlapping implementation.
• When consolidating, link both PRs, explain which contributions are retained, and preserve attribution through original commits or appropriate co-author credit. Close the superseded PR once the retained contribution and attribution are present in the continuing PR.

A scope comment signals active work, not permanent ownership. If work pauses or changes direction, leave an update; others can propose taking it forward in the same thread.

Prepare a reviewable change

Start from the latest dev and target dev for fixes and features. Check whether its existing controls already solve the reported case. Record the comparison base and candidate head.

Use Draft for unresolved scope or early implementation feedback. At this stage, provide the smallest reproduction and relevant checks. Prepare broad integration evidence and generated artifacts once the approach is settled.

Before requesting final review, explain:

• The current-base trigger, intended outcome, and why the benefit justifies the implementation and ongoing maintenance cost.
• The changed behavior and shared callers, existing behavior that must remain stable, and any intended compatibility changes.
• The applicable checks, actual results, and reproducible evidence links.

Use the PR template; link existing receipts or CI output instead of transcribing long logs. Classify impact by behavior and callers, not file extension or diff size.

AI assistance and contributor responsibility

AI-assisted contributions are welcome. The same scope, evidence, and accountability requirements apply to contributors and maintainers, whether work is manual or delegated to an Agent.

Every PR must disclose whether AI was used. If used, name the tool(s), model when known, and the work they performed: investigation, design, code, tests, review, or writing/translation. Identify affected areas rather than estimating a percentage of generated lines. If model identity is unavailable, say so. Translation-only use can be disclosed in one sentence.

A human contributor must review the submitted changes and explanation, understand the approach and its impact, and be able to explain the choices and answer review questions. Name that accountable person by GitHub handle when an Agent or bot submits on their behalf. Agents may prepare changes, run checks, and draft replies under that person's direction; they must not claim human review or check a personal confirmation without that person's explicit confirmation. Project-approved automated review comments remain advisory evidence, not human acceptance.

Describe the problem's origin honestly: observed usage, a reproducible defect found during inspection, a synthetic probe, or a proposed improvement. Code inspection can reveal valid bugs; do not present a constructed case as a naturally occurring Agent failure. AI-generated descriptions and replies must be checked for factual accuracy, kept concise, and reflect the contributor's understanding. Translation and editing assistance are allowed.

Link actual validation results in the existing Tests run / Visual evidence sections. Distinguish checks run by an Agent, CI, and human inspection; preserve failures and disclose untested areas. An AI review, a green test run, or a disclosure checkbox alone does not establish useful or correct behavior. Full sessions are required only where the agreed benchmark/evidence scope calls for them; do not upload unrelated private conversations or hidden model reasoning.

Maintainers may request missing disclosure or evidence, defer review, or close a PR that lacks agreed scope, cannot be explained by its contributor, or contains unverified claims. Give a specific reason and a route back through the relevant issue. Repeated submissions that ignore this feedback may be restricted. Evaluate observable conduct and evidence rather than guessing AI use from writing style or an automated detector. Do not bulk-close older PRs solely because they predate this disclosure field.

Policy references consulted on 2026-10-16: Ghostty, LLVM, and Astral. Archify's requirements are defined here; other projects' restrictions do not apply automatically.

PR improvement check

Before requesting final review of a behavior-changing PR, assess the changed behavior, direct callers, and affected tests with the project Skills:

• test-value: use its implementation or pre-commit review mode to decide which tests to add, adapt, reuse, or retire. Protect user outcomes and real failure boundaries at proportionate cost.
• simplify-codebase: use Focused Survey mode when the diff introduces or touches duplicate logic/state, dead paths, redundant layers, or another concrete complexity concern. Trace the relevant consumers before recommending a cut.

Keep this check within the PR's changed ownership boundaries. A conclusion of “no worthwhile improvement” is valid. Pure prose or generated-only refreshes with no behavior change may skip it; authored Skill instructions and behavioral build inputs still need assessment. Apply proved improvements within the task's existing authorization. Report changes that would retire a supported capability or compatibility contract for maintainer decision.

Summarize useful findings, implemented improvements, or the reason for skipping in the PR's existing problem/impact and test sections. Reuse applicable evidence under Choose evidence by impact; this check adds no separate audit report or CI gate. Repository instructions govern scope and publication authority. Treat the two vendored Skills as read-only guidance in ordinary PRs; update their pinned sources through a dedicated reviewed change. See Skill sources for provenance and update procedure.

Choose evidence by impact

| Impact | Typical change | Evidence to prepare | | --- | --- | --- | | Text or review policy | Explanatory prose, links, contributor/reviewer procedure | Check content, links, and consistency with affected templates or automation. No local renderer suite for repository-only prose. | | Local behavior | One CLI path, focused test correction | Reproduction or rationale, affected tests, and relevant failure/compatibility cases. | | Shared behavior | Geometry, text measurement, shared Viewer, evidence or delivery helpers | Trace callers; identify affected modes and contracts; compare fixed representative inputs on base and candidate, including relevant historical failures. | | Contract change | Schema, defaults, validation acceptance, Skill or authoring instructions | Agreed scope and explicit allowed/preserved behavior, plus local/shared evidence appropriate to the implementation. |

Skill instructions, authored examples, build inputs, and generated-site sources are behavioral inputs even when they look like documentation. Policy changes need process review; runtime evidence depends on whether they affect runtime inputs.

Start with npm test for the core product smoke or focused checks for the affected behavior. Use npm run test:full when shared infrastructure, broad changes, or findings require wider coverage. Final review needs sufficient evidence for the impact above; relevant CI results can supply that coverage without repeating the same run locally. Identify the revision and coverage of reused results, and explain material gaps. Required remote CI and branch protection still apply.

Tests should protect a user outcome or a real failure boundary. Prefer rendered content, successful interaction, preserved authored intent, and bounded work to matching implementation source or freezing automatic layout coordinates. A better automatic route, clearer copy, or equivalent refactor should not fail a test merely because it differs from the old implementation. Delete redundant source assertions when a behavior test owns that protection. Keep explicit geometry, compatibility, accessibility, failure cleanup, and protection against lost or corrupted output as observable contracts.

Real generation comparisons

For PRs that change diagram generation, select and link before/after evidence using the real repository benchmark. Its initial rollout is an agreed three-PR pilot; record the selected scope or a justified exemption before running. Contributors supply the comparison and session records; maintainers review outcomes and sample evidence. Synthetic error injection alone does not establish real Agent benefit. Reuse unaffected evidence at its recorded revision.

CI by affected responsibility

CI uses the ownership groups in scripts/ci-scope.mjs. Product changes run core CLI coverage on the maintained Node versions and the affected regression suites. Renderer and Viewer changes also run the real browser gate and generated-output checks. Filesystem, process, dependency, build, and workflow changes retain the full regression and relevant Windows/package gates. New or modified test files are executed; test helpers and fixtures take the conservative full path. Repository prose and website-only changes use their own checks.

Unknown paths, an empty comparison, and an unavailable development-push base select full coverage. An invalid PR comparison fails classification. Required job names remain present, and a failed classification cannot turn into successful skips. Main pushes and manual CI runs use complete coverage; releases explicitly run test:full. New pushes cancel obsolete CI runs for the same PR.

Product and compatibility contracts

• Existing schema-v1 typed JSON remains valid unless a reviewed change explicitly introduces a breaking rule and migration path.
• Preserve authored topology and intent; explicit geometry remains authoritative unless the contract says otherwise. Consult the authoring contract and relevant renderer documentation for details.
• standard preserves broad compatibility. A new showcase failure must identify a real, repairable defect and avoid rejecting necessary routing.
• Agent-facing failures belong in diagnostics[]: use a stable code, precise subject, concrete evidence, and executable supportedFixes. Preserve non-zero CLI exits and machine-readable receipts for failed stages.
• A validation rule expressing taste should begin with evidence or a warning. Before making it a hard error, check legitimate obstacles, shared ports, explicit routes, nested boundaries, and existing examples.
• Keep one canonical contract per behavior. Link the existing source instead of copying CLI stages, receipt fields, or error tables.

Local setup and verification

The renderer package is in archify/; repository tests and their dependencies live at the root. Install both dependency sets before running tests. The supported Node range is defined in both package manifests.

npm ci
npm --prefix archify ci
npm test
npm run test:focus -- test/geometry.test.mjs

For the development loop, select the files covering the changed behavior with npm run test:focus -- test/<name>.test.mjs [test/<other>.test.mjs ...]. This runs only those suites, without the generated-output checks or golden pass. It requires at least one file and rejects unknown files rather than silently running the full suite. Paths are relative to the repository root; absolute paths also work. Use --list with the same selection to inspect it without running tests. A focused pass is evidence for that selection only.

To narrow a large file further, add a quoted Node test-name pattern (Node 18.11+):

npm run test:focus -- test/cli.test.mjs '--test-name-pattern=cli: validate'

Nested tests follow Node's filtering rules: include their parent test names in the pattern as well. Check the reported pass/skip counts for the intended cases.

| Command | What it establishes | | --- | --- | | npm test / npm run test:core | Ten diagram types run through the public CLI, frozen v1 inputs remain usable, delivery receipts bind the actual files, and failed delivery preserves the previous artifact. No browser or perceptual acceptance is implied. | | npm run test:focus -- test/<name>.test.mjs | Only the selected behavior or regression. | | npm run test:generated | Viewer, brand marks, validators, release identity, and checked-in examples match their authoritative sources. Freshness does not establish visual quality. | | npm run test:full | Generated checks followed by every discovered Node test file, including the detailed process, filesystem, installation, and failure matrices. |

The Node 18, 20, and 24 compatibility lanes run the same core product smoke via test:compat. Detailed fault-injection matrices run on canonical Node 22 when their responsibility is affected and in complete verification. The separate browser, WebM, Windows, and package gates retain their distinct claims. Do not repeat an unchanged complete run locally just because CI is also running it.

For full CI, Node 22 runs every discovered test file across two independent machines using node scripts/run-tests.mjs --shard=1/2 and --shard=2/2. One shard also runs generated checks and the Hermes adapter contract once, using the same installed dependencies. The existing test (22) check requires both shards to succeed without reinstalling dependencies afterward. Other scopes do not start these shards. Node 18, 20 and 24 compatibility checks start after scope classification, without waiting for the complete regression shards. --list --shard=1/2 shows the selected files; shards cannot be combined with explicit files or test-name filtering. Locally and in tagged releases, npm run test:full still runs the complete inventory without sharding.

The Windows Node 22 lane owns the complete filesystem and fault-injection matrices. Node 24 runs the core CLI smoke instead of repeating those matrices. Both lanes, including tagged releases, still run the controlled case-sensitive NTFS, UNC, extended-path, and 8.3-path scenarios. Use node scripts/run-windows-path-tests.mjs --list (or --smoke --list) to inspect the selected groups without running tests or creating Windows fixtures.

The test runners accept --concurrency=N to tune the number of simultaneous test files on Node 18.19+, for example npm run test:focus -- test/geometry.test.mjs --concurrency=4. Headless repository and compatibility runs default to the available CPU count, capped at 4. Setting ARCHIFY_CHROME or running test:browser keeps the default at 2. Older Node versions that lack this concurrency option retain Node's default. Compare timing and results on the same machine before increasing concurrency; browser tests can become slower or unstable under CPU contention.

Test through public behavior such as render, validate, deliver, visual-check, or final SVG/HTML. Behavioral fixes should include a regression that demonstrates the original failure. Private helper checks can supplement that evidence.

For geometry and layout changes, use the smallest redacted JSON reproduction, relevant checked-in examples, and frozen compatibility fixtures. Compare base and candidate with the same input and browser conditions. Identify intended changes and investigate unexpected ones; updating golden files alone does not establish visual or compatibility acceptance.

A visual PR must provide enough evidence to evaluate whether the intended user value was achieved, using screenshots, recordings, or reproducible steps. Keep viewport, theme, preset, diagram mode, zoom, and page state comparable. Report automated or browser evidence separately from perceptual review. Non-visual changes may omit the Visual evidence section.

Static SVG/XML checks cannot establish browser layout, font settling, or interaction behavior. When the adaptive reader or Viewer layout changes, run the real browser test from the repository root with Chrome available:

In a POSIX shell:

ARCHIFY_CHROME="/path/to/chrome" npm run test:browser -- test/desktop-reader-browser.test.mjs

In Windows PowerShell:

$env:ARCHIFY_CHROME = 'C:\Program Files\Google\Chrome\Application\chrome.exe'
npm run test:browser -- test/desktop-reader-browser.test.mjs

Replace the example Chrome path with your installed executable's path. In PowerShell, the environment variable remains set for the current session.

A browser test skipped because Chrome was unavailable is skipped, not passed. Follow the delivery contract for visual evidence, receipts, and failure stages. Successful validation, atomic delivery, browser checks, and perceptual review establish different claims.

PR CI and tag releases run the same browser regression gate:

ARCHIFY_CHROME="/path/to/chrome" npm run test:browser

This command requires a usable Chrome/Chromium and fails when none is available. Its maintained file list is in scripts/browser-test-inventory.mjs; add new browser suites there so both workflows keep t