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 community submissions and release completion

tt-a1iba039f836349
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index f8318532..7c26da71 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -27,3 +27,8 @@ Report automated or browser evidence separately from perceptual review.
## Generated artifacts
Omit this section if generated outputs are unaffected. Otherwise list regenerated files or linked build evidence, and explain freshness of affected outputs left unchanged.
+
+
+## Release follow-up
+
+Omit for changes without release scope. For a release, link the completed or explicitly deferred stages and evidence in the [central release checklist](../CONTRIBUTING.md#release-checklist), including the DSH decision. Do not equate PR completion with publication or deployment.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 7d14c6fe..45fb7699 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -137,7 +137,8 @@ jobs:
- name: Record stable notifier publication follow-up
if: steps.release-kind.outputs.prerelease == 'false'
run: |
+ echo '[Complete the central release checklist](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md#release-checklist), including final-head evidence and public acceptance.' >> "$GITHUB_STEP_SUMMARY"
echo 'After the repository Pages source is set to GitHub Actions, publish docs/skill-updates/archify/stable.json in a follow-up commit; the gated deploy job will verify this Release, its archify.zip digest, and the tagged Skill tree before exposure.' >> "$GITHUB_STEP_SUMMARY"
- name: Record DSH synchronization follow-up
run: |
- echo 'Review CONTRIBUTING.md#release-checklist-dsh-synchronization: record the pinned DSH bundle update and verification, or an explicit deferral. Archify release publication does not publish the independently versioned DSH plugin; keep npm/tag/README/community status accurate until that separate release is verified.' >> "$GITHUB_STEP_SUMMARY"
+ echo '[Central release checklist](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md#release-checklist), including [DSH synchronization](https://github.com/tt-a1i/archify/blob/main/CONTRIBUTING.md#release-checklist-dsh-synchronization): record the pinned DSH bundle update and verification, or an explicit deferral. Archify release publication does not publish the independently versioned DSH plugin; keep npm/tag/README/community status accurate until that separate release is verified.' >> "$GITHUB_STEP_SUMMARY"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 01ea99a8..9eb25370 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,6 +5,7 @@ Archify is Agent-first: people describe systems, and the Skill, typed JSON, rend
## Choose the right path
- Renderer, validator, package, or Viewer defect: use the [bug report form](.github/ISSUE_TEMPLATE/bug-report.yml).
+- Standalone community package: follow the [submission guide](community/README.md#submitting-a-package) and submit one metadata file to `dev`.
- Reproducible real-world diagram: use the [showcase form](.github/ISSUE_TEMPLATE/showcase.yml).
- New schema fields, defaults, acceptance rules, installation/export contracts, or broad product behavior: agree on value, compatibility, and non-goals before substantial implementation. Link the issue or recorded maintainer decision; reuse an existing agreed scope.
- Narrow fixes and small documentation or test corrections can proceed with a concrete reproduction or rationale; a separate planning issue is unnecessary.
@@ -118,6 +119,17 @@ List regenerated files and explain freshness when an affected output is left unc
Treat published versions as immutable. Ordinary feature PRs do not change versions, tags, or distribution identities unless release work is explicitly in scope.
+## Release checklist
+
+Use this single checklist in the release PR or its linked release record. Link evidence at each stage; mark an item complete only when its stated outcome is verified, or record an explicit deferral with an owner, reason, and follow-up. PR completion, release publication, Pages deployment, and updates to live installations are separate outcomes. Existing gates in [CI](.github/workflows/ci.yml) and the [release workflow](.github/workflows/release.yml) already cover release identity, ZIP freshness, installation parser/real Skills CLI tests, three-platform package smoke, browser checks, and the published manifest's actual Release ZIP. Reuse those gates and their receipts rather than creating another release pipeline.
+
+1. [ ] **Scope and revision.** Record the intended version/channel, release scope, final source SHA, comparison base, release notes, known issues, and required integration follow-ups. Follow the `dev` trial-use → `main` promotion process below. Pin evidence to its tested SHA; refresh the record when the candidate changes.
+2. [ ] **Identity and build.** Verify package/Skill identity and generated outputs using the candidate revision's existing checks. Use the canonical Node/zlib toolchain above for `scripts/build-zip.sh`; confirm the committed `archify.zip` matches the clean tracked-source build. Do not change versions or regenerate unrelated artifacts in ordinary feature PRs. Preserve the previous stable manifest until the new stable Release exists.
+3. [ ] **Final-head validation.** Account for the latest target base and verify required CI at the final candidate: identity and ZIP gates, schema/renderer tests, installation parser and real Skills CLI discovery, package smoke on Linux/macOS/Windows, browser/WebM checks, and affected website checks. Record run URLs, SHA, real-use evidence, and any skipped or unavailable checks; an earlier green head or zero checks is not final acceptance. Use commands from that revision's manifests/workflows: current `dev` installs root and renderer dependencies and runs `npm test`, `npm run test:browser`, and `npm run test:webm` at the repository root (see [Local setup](#local-setup-and-verification)); older `main`/release revisions may run these from `archify/`. Website commands run in `website/`. Do not transplant a command or its working directory across revisions without checking.
+4. [ ] **Authorized publication.** Confirm authorization for the exact release version/channel and source SHA before pushing a release tag. Stable `v<version>` tags must be annotated and resolve to the verified commit; the workflow checks tag/package identity and the release channel. Verify the resulting GitHub Release and its `archify.zip` asset, digest, and expected stable/prerelease status. Do not overwrite existing versions, tags, or assets to repair a release. Installing or updating a user's live installation requires its own authorization.
+5. [ ] **Manifest, website, and integrations.** After the stable Release exists, publish `docs/skill-updates/archify/stable.json` in a follow-up commit through the normal branch process. Retain the `published-update-manifest` result that compares the actual Release ZIP, tagged archive, digest, and tagged Skill tree; wait for the gated `main` Pages deployment. Development/prerelease tags do not advance the stable notifier. Complete the [DSH synchronization checklist](#release-checklist-dsh-synchronization) or record an explicit deferral. Evaluate other integrations by their actual distribution mechanism: [Hermes](integrations/hermes-agent/README.md#install-shows-up-in-available-skills) installs the main Skill identifier; do not invent a separate Hermes release simply because Archify changed. Record any documentation/compatibility update or indexing lag that needs follow-up.
+6. [ ] **Public acceptance and closure.** Check the public download and advertised installation/discovery paths against the released artifact in an isolated environment, without changing live user installations. Verify the public stable manifest, Pages version, installation instructions, and community catalog source/evidence/compatibility links describe what users can actually obtain; distinguish published, pending, and explicitly deferred integration versions. Record the final release/tag/SHA, asset digest, CI and deployment receipts, public acceptance result, and every remaining owner/follow-up. Only describe each channel as complete after its own verification.
+
### Release checklist: DSH synchronization
For every Archify release, record the DSH decision in the release PR or its linked follow-up. The Skill source is pinned: releasing Archify or updating `main` does not update the DSH package or existing installations. Use the [DSH release maintenance procedure](integrations/deepseek-harness/README.md#release-maintenance) for commands and host requirements.
diff --git a/README.md b/README.md
index 35cacef8..11414721 100644
--- a/README.md
+++ b/README.md
@@ -418,6 +418,8 @@ Connect with other users and developers, share ideas, request features, report b
## Contributing
+Building a standalone package on Archify? [Submit it to the community catalog](community/README.md#submitting-a-package); the guide includes a collapsible example and complete Chinese steps.
+
Issues, pull requests, and real-world diagrams are welcome. Start with the [contribution guide](CONTRIBUTING.md), use the reproducible bug form for failures, or submit a validated diagram through the [community showcase form](https://github.com/tt-a1i/archify/issues/new?template=showcase.yml).&nbsp;·&nbsp;[LINUX&nbsp;DO](https://linux.do)
## Support Archify
diff --git a/README_EN.md b/README_EN.md
index 35cacef8..11414721 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -418,6 +418,8 @@ Connect with other users and developers, share ideas, request features, report b
## Contributing
+Building a standalone package on Archify? [Submit it to the community catalog](community/README.md#submitting-a-package); the guide includes a collapsible example and complete Chinese steps.
+
Issues, pull requests, and real-world diagrams are welcome. Start with the [contribution guide](CONTRIBUTING.md), use the reproducible bug form for failures, or submit a validated diagram through the [community showcase form](https://github.com/tt-a1i/archify/issues/new?template=showcase.yml).&nbsp;·&nbsp;[LINUX&nbsp;DO](https://linux.do)
## Support Archify
diff --git a/README_ZH.md b/README_ZH.md
index 7e6a226d..d3e0c010 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -422,6 +422,8 @@ node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tm
## 参与贡献
+基于 Archify 做了独立包?[提交到社区目录](community/README.md#中文摘要)。详细步骤和 JSON 示例默认折叠,按需展开即可。
+
欢迎提交 Issue、Pull Request 和真实场景图。请先阅读[贡献指南](CONTRIBUTING.md);遇到问题时使用可复现 Bug 表单,也可以通过[社区 Showcase 表单](https://github.com/tt-a1i/archify/issues/new?template=showcase.yml)提交已验证成品。
较大的功能或行为调整请先通过 Issue 对齐价值、兼容边界和非目标,再基于最新 `main` 开发。一个 PR 尽量只解决一个问题;核心代码和回归测试先行,生成物最后统一重建。Archify 坚持 Agent-first,优先完善稳定的机器可读诊断和现有权威合同,避免新增容易与 CLI 漂移的重复说明。&nbsp;·&nbsp;[LINUX&nbsp;DO](https://linux.do)
diff --git a/community/README.md b/community/README.md
index 99744ff7..16f47d05 100644
--- a/community/README.md
+++ b/community/README.md
@@ -21,8 +21,8 @@ Archify has **no in-process plugin API, and none is planned for this registry**.
## Submitting a package
1. Publish your package in your own repository (or npm). Archify does not host package content.
-2. Fork this repository and add **one metadata file**: `community/packages/<name>.json`, following [`package.schema.json`](package.schema.json). `<name>` is lowercase kebab-case and must equal the `name` field.
-3. Validate locally before opening the PR:
+2. Fork this repository, branch from the latest `dev`, and add **one metadata file**: `community/packages/<name>.json`, following [`package.schema.json`](package.schema.json). `<name>` is lowercase kebab-case and must equal the `name` field.
+3. From the repository root, validate locally before opening the PR (Node.js 18+, no npm dependencies needed):
```bash
node scripts/check-community-packages.mjs
@@ -30,6 +30,62 @@ Archify has **no in-process plugin API, and none is planned for this registry**.
4. Open a PR **targeting `dev`** (per [CONTRIBUTING.md](../CONTRIBUTING.md)) that adds only your metadata file. Include evidence links in the `evidence` field — validation receipts, screenshots, rendered example artifacts.
+A merge into `dev` does not publish the website. The public catalog updates after promotion to `main` and a successful Pages deployment; there is no promised review or publication time.
+
+[Schema](package.schema.json) · [Existing entries](packages/) · [完整中文步骤](#中文摘要)
+
+<details>
+<summary>Submission example, field requirements, and updates</summary>
+
+Start in a local clone of your fork. Add `upstream` only if it is not already configured; otherwise verify that it points to this repository.
+
+```bash
+git remote add upstream https://github.com/tt-a1i/archify.git
+git fetch upstream dev
+git switch -c community/my-archify-recipes upstream/dev
+```
+
+Save the following as `community/packages/my-archify-recipes.json`. Replace the name, author, descriptions, and **all example.com URLs** with your public package and evidence. The version `3.0.1` and IR `[1]` illustrate the format, not a compatibility claim for your package; use versions you have actually verified.
+
+```json
+{
+ "name": "my-archify-recipes",
+ "type": "recipe",
+ "summary": {
+ "en": "Example recipe library for explaining web application request flows.",
+ "zh": "用于说明 Web 应用请求流程的场景配方库示例。"
+ },
+ "author": {
+ "name": "YOUR_NAME",
+ "url": "https://example.com/author"
+ },
+ "repository": "https://example.com/my-archify-recipes",
+ "archify": "3.0.1",
+ "schemaVersions": [1],
+ "tags": ["recipes", "web"],
+ "evidence": [
+ {
+ "label": "Example artifact and validation receipt",
+ "url": "https://example.com/my-archify-recipes/evidence"
+ }
+ ]
+}
+```
+
+Run `node scripts/check-community-packages.mjs` from the repository root, commit only your metadata file, push the branch to your fork, and open a PR against **`tt-a1i/archify:dev`** using the repository PR template. Report the check result and link evidence for the claimed behavior and compatibility. Do not include credentials, private source, personal information, or customer data in evidence.
+
+- Required fields: `name`, `type`, `summary`, `author`, `repository`, `archify`, and `schemaVersions`. Unknown fields are rejected.
+- `name`: 3–64 lowercase letters, digits, or hyphens, starting and ending with a letter or digit; the file name must match. `summary.en`: 10–160 characters; `summary.zh`: 6–120 characters. `author.name` is required.
+- `archify`: an exact version, caret/tilde range, or bounded range such as `3.0.1`, `^3.0.1`, `~3.0.1`, or `>=3.0.0 <4.0.0`. `latest`, wildcards, and prerelease suffixes are not accepted by this metadata contract.
+- `schemaVersions`: the nonempty, unique list of positive-integer Archify JSON IR `schema_version` values your package supports, not your package version.
+- Optional fields are `author.url`, `homepage`, `tags` (up to 6 unique items), and `evidence` (up to 8 `{label, url}` items). Although the schema does not require `evidence`, the submission instructions above ask for evidence links. Follow the schema for remaining length and character limits.
+
+The check validates metadata and URL syntax; it does not fetch links, verify that claimed versions exist, prove compatibility, or execute your package. Supply evidence for those claims. Passing the check is not review approval or endorsement.
+
+**Updating a listing:** publish the package update in your own repository or registry, edit the existing metadata file with any changed compatibility, summary, and evidence, then validate and submit a PR to `dev` again. Keep published and pending versions distinct. Authors maintain their own packages; removal follows [Takedown](#takedown).
+
+</details>
+
Review follows the tiers in [REVIEWING.md](../REVIEWING.md). Approval criteria:
- Metadata passes `scripts/check-community-packages.mjs`. Links must be parseable HTTPS URLs with a host, no credentials, whitespace, control characters, or backslashes (the validator checks these URL semantics in addition to the schema). Website builds use the same validator and reject invalid entries.
@@ -46,3 +102,29 @@ Removal is also a PR, on record. Maintainers may remove a listing when the packa
## 中文摘要
社区 package 是**独立产物**,依赖并调用 Archify,而不是被 Archify 加载的插件。提交方式:fork 本仓库,按 `package.schema.json` 在 `community/packages/` 下新增一个元数据文件,本地跑 `node scripts/check-community-packages.mjs` 校验,然后向 `dev` 分支提 PR。收录不代表官方背书;下架同样以 PR 形式留痕。
+
+
+<details>
+<summary>展开中文提交步骤、字段说明和维护指南</summary>
+
+可提交五种独立包:`skill`(领域技能包)、`recipe`(场景配方库)、`brand-marks`(品牌标识或预设)、`locale`(`meta.translations` 语言目录)、`wrapper`(生成 JSON IR 并调用 CLI 的独立工具)。它们由作者维护,不会被 Archify 渲染器加载执行。
+
+1. 在自己的公开仓库或 npm 发布包,写清用途、使用方式、实际测试过的 Archify 和 IR 版本。准备公开的校验回执、示例产物或截图,移除凭据、私人源码、个人信息和客户数据。
+2. Fork 本仓库,在本地副本中从最新 `dev` 建分支。上方英文折叠区给出了 `upstream` 和建分支命令;已有 `upstream` 时先核对地址,不重复添加。
+3. 按上方 JSON 示例新增 `community/packages/<name>.json`,替换作者、简介、名称、全部占位 URL 和版本。示例中的 `example.com` 不是可提交的证据,`3.0.1` / `[1]` 也不代表你的包已经通过兼容性验证。
+4. 在仓库根目录运行 `node scripts/check-community-packages.mjs`。需要 Node.js 18+,这个检查无需安装 npm 依赖。
+5. 只提交新增的元数据文件,推送到自己的 fork,按仓库 PR 模板向 **`tt-a1i/archify:dev`** 提 PR,附实际校验结果与证据。校验通过不等于审核批准;进入 `main` 且 Pages 部署成功后才会更新公开目录,不承诺审核或上线时限。
+
+必填字段是 `name`、`type`、`summary`、`author`、`repository`、`archify`、`schemaVersions`。`summary.en` 为 10–160 字符,`summary.zh` 为 6–120 字符,两种语言都要填;`author.name` 必填。名称为 3–64 个小写字母、数字或连字符,首尾不能为连字符,并须与文件名一致。其他长度和字符限制见 [schema](package.schema.json)。
+
+`archify` 支持精确版本、`^3.0.1`、`~3.0.1`、`>=3.0.0 <4.0.0` 这些形式,不接受 `latest`、通配符或预发布后缀。`schemaVersions` 是实际支持的 Archify JSON IR 版本,填非空、无重复的正整数数组。校验器只检查格式,不检查版本是否真实存在或是否实际兼容,别填写未经验证的宽范围。
+
+可选字段为 `author.url`、`homepage`、`tags`(最多 6 个且不重复)、`evidence`(最多 8 个 `{label, url}`)。`evidence` 虽非 schema 必填项,提交指南仍要求提供证据。所有 URL 必须为 HTTPS,且不能含凭据、空白、控制字符或反斜杠;检查不会请求这些链接,也不会执行你的包。字段必须来自 schema,不要添加自定义审批或精选字段。
+
+安全要求沿用现有规则:无遥测、不以托管服务为必需条件、不在 Archify 内执行第三方代码。收录不代表官方背书,元数据校验也不是功能或安全认证。
+
+**更新条目:** 先在自己的仓库或包注册表发布更新,再修改原 JSON 的简介、兼容声明和证据,重新校验并向 `dev` 提 PR;清楚区分已发布和待发布版本。目前没有另行承诺的更新频率或响应时限。
+
+**申请移除:** 作者可随时通过 PR 或 issue 申请移除自己的条目。恶意包、已弃维护且源码链接损坏、兼容声明长期失真的条目可由维护者移除,下架通过 PR 留痕。完整规则见 [Takedown](#takedown)。
+
+</details>
diff --git a/website/src/pages/community.astro b/website/src/pages/community.astro
index 24e430c7..d52b8e9c 100644
--- a/website/src/pages/community.astro
+++ b/website/src/pages/community.astro
@@ -29,6 +29,7 @@ const activeTypes = typeOrder.filter((type) => typeCounts[type] > 0);
<div class="lead-label" data-en="Community registry / standalone packages" data-zh="社区注册表 / 独立包">Community registry / standalone packages</div>
<h1 data-translation-html data-en="Built on Archify.<br><em>Shared by everyone.</em>" data-zh="基于 Archify 构建,<br><em>由社区共享。</em>">Built on Archify.<br><em>Shared by everyone.</em></h1>
<p class="hero-copy" data-en="Community packages are standalone works that wrap the Archify CLI — skill packs, recipe libraries, brand kits, locales, and wrappers. Nothing here is a plugin: no third-party code ever runs inside the renderer." data-zh="社区包是围绕 Archify CLI 构建的独立产物——技能包、场景配方、品牌套件、语言包与命令行封装。这里没有插件:任何第三方代码都不会进入渲染器内部运行。">Community packages are standalone works that wrap the Archify CLI — skill packs, recipe libraries, brand kits, locales, and wrappers. Nothing here is a plugin: no third-party code ever runs inside the renderer.</p>
+ <a class="card-link submission-link" href="https://github.com/tt-a1i/archify/tree/main/community#submitting-a-package" target="_blank" rel="noopener noreferrer" data-en="Submit your package ↗" data-zh="提交你的包 ↗">Submit your package ↗</a>
</div>
<div class="proof-board" aria-label="Registry summary">
<div class="proof-row"><span class="proof-value">{packages.length}</span><span class="proof-label" data-translation-html data-en="packages listed<br>from the registry" data-zh="个已收录包<br>来自注册表">packages listed<br>from the registry</span></div>
@@ -107,21 +108,22 @@ const activeTypes = typeOrder.filter((type) => typeCounts[type] > 0);
<div class="pipeline-step"><span class="pipeline-num">01</span><span class="pipeline-label" data-en="Publish your package in your own repo" data-zh="在你自己的仓库发布你的包">Publish your package in your own repo</span><span class="pipeline-state you">YOU</span></div>
<div class="pipeline-step"><span class="pipeline-num">02</span><span class="pipeline-label" data-en="Add one metadata file under community/packages/" data-zh="在 community/packages/ 下添加一个元数据文件">Add one metadata file under community/packages/</span><span class="pipeline-state you">YOU</span></div>
<div class="pipeline-step"><span class="pipeline-num">03</span><span class="pipeline-label" data-en="Validate with check-community-packages.mjs" data-zh="运行 check-community-packages.mjs 校验">Validate with check-community-packages.mjs</span><span class="pipeline-state">PASS</span></div>
- <div class="pipeline-step"><span class="pipeline-num">04</span><span class="pipeline-label" data-en="Open a PR targeting dev — merge means listed" data-zh="向 dev 分支提 PR——合并即收录">Open a PR targeting dev — merge means listed</span><span class="pipeline-state">PASS</span></div>
+ <div class="pipeline-step"><span class="pipeline-num">04</span><span class="pipeline-label" data-en="Open a PR targeting dev — publication follows main deployment" data-zh="向 dev 提 PR——进入 main 并部署后上线">Open a PR targeting dev — publication follows main deployment</span><span class="pipeline-state">PASS</span></div>
</div>
</div>
<div class="method-code">
<div class="method-code-bar"><span>submit locally</span><span>zero dependencies</span></div>
- <pre><span class="accent">$ node scripts/check-community-packages.mjs</span>
-
-community registry: {packages.length} package(s) OK
- {packages.map((entry) => entry.name).join(', ')}
-
-<span class="accent">$ git checkout -b community/my-pack origin/dev</span>
+ <pre># from your fork, track upstream dev
+<span class="accent">$ git fetch upstream dev</span>
+<span class="accent">$ git switch -c community/my-pack upstream/dev</span>
# add community/packages/my-pack.json
-# open PR → review → listed here</pre>
- <a class="card-link method-link" href="https://github.com/tt-a1i/archify/tree/main/community" target="_blank" rel="noopener noreferrer" data-en="Read the submission guide ↗" data-zh="阅读提交指南 ↗">Read the submission guide ↗</a>
+# validate from the repository root
+<span class="accent">$ node scripts/check-community-packages.mjs</span>
+
+# open PR to dev → review
+# promote to main → deploy → public catalog</pre>
+ <a class="card-link method-link" href="https://github.com/tt-a1i/archify/tree/main/community#submitting-a-package" target="_blank" rel="noopener noreferrer" data-en="Read the submission guide ↗" data-zh="阅读提交指南 ↗">Read the submission guide ↗</a>
</div>
</div>
</section>
diff --git a/website/src/styles/community.css b/website/src/styles/community.css
index bc252c82..5a449c3e 100644
--- a/website/src/styles/community.css
+++ b/website/src/styles/community.css
@@ -217,3 +217,5 @@
@media (max-width:640px) { .method-code pre { padding:1.25rem; font-size:.75rem; } }
.method-link { align-self:flex-start; margin:0 1.9rem 1.9rem; border-color:var(--line-hi); color:var(--text); }
.method-link:hover { border-color:var(--accent); color:var(--accent); }
+
+ .submission-link { margin-top: 1.25rem; }