@seemseam/architec 0.2.10 → 0.2.11

package/README.zh-CN.md

@@ -3,75 +3,59 @@
 **面向 AI 辅助开发代码库的增量架构审查 CLI。**
 
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
-[![CLI](https://img.shields.io/badge/CLI-archi-222222)](#快速开始)
+[![CLI](https://img.shields.io/badge/CLI-archi-222222)](README.md#quick-start)
 [![Login](https://img.shields.io/badge/login-not_required-green)](#无需登录)
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-Architec 是一个 Python 3.11+ 命令行工具，用来审查代码变更里的架构风险。它会从仓库中构建紧凑证据，交给你配置好的 LLM 解释，然后把建议型报告写给人类 reviewer 或 coding agent。
-
-它关注的实际问题是：
+Architec 是一个建议型架构分析工具，核心问题是：
 
 > 这次改动会不会让项目更难长期维护？
 
-Architec 不会自动修改代码，不会替你批准合并，也不能证明运行时正确性。它报告的是值得检查的架构风险，例如重复逻辑、shadow implementation、模块边界不清、结构陈旧、清理候选、热点文件和目录拓扑压力。
-
-## 包状态
-
-当前 checkout 已经具备 Python 发布配置，并准备了 npm launcher 草案：
-
-| Registry | 包名 | CLI 命令 | 当前 checkout 状态 |
-| --- | --- | --- | --- |
-| PyPI | `architec` | `archi` | 包元数据、README、许可证、wheel/sdist 内容已经配置。必须等 companion dependencies 可从目标索引安装，并选择新的 release version/tag 后再发布。 |
-| npm | `@seemseam/architec` | `archi` | scoped launcher 包已经配置，但 scope 所有权、Trusted Publishing 设置和 Python 依赖链仍需发布前验证。 |
-
-未加 scope 的 npm 包名 `architec` 已被无关包占用，所以 npm 发布应使用你控制的 scope。Python 侧的发行名和命令名是刻意分开的：发行名是 `architec`，安装后的控制台命令是 `archi`。
-
-只有在对应 registry 页面显示目标版本后，才使用 registry 安装命令。根据本次审计，现有 `v0.2.10` tag 指向较旧提交，未来 registry release 应使用新的版本和 tag。
-
-## 安装
-
-Architec 需要 Python 3.11 或更新版本。
-
-从当前 checkout 做本地开发安装：
+默认命令是：
 
 ```bash
-python3 -m pip install -e .
+archi
 ```
 
-为了满足 PyPI 发布兼容性，当前包声明了 registry 形式依赖：`llmgateway>=0.1.1` 和 `hippocampus>=0.1.7`。如果这些 companion 版本还不能从你配置的包索引安装，请先从源码安装 companion projects，或等待它们的 registry release 后再使用普通依赖解析。
-
-PyPI 包发布并验证后，预期安装方式是：
+它会审查当前 git 变更，构建紧凑的架构证据，并通过 LLM 给出可读的架构建议。
+如果需要查看整个项目的架构基线，使用：
 
 ```bash
-python3 -m pip install --user architec
+archi --full
 ```
 
-在 PyPI 项目页显示目标版本之前，不要把这条命令写进自动化流程。
+Architec 只给建议，不做合并判定，不自动修改代码，也不要求登录。
 
-npm 分发已按轻量 launcher 包方案准备。npm 包发布并验证后，预期安装方式是：
+## 为什么需要 Architec
 
-```bash
-npm install -g @seemseam/architec
-```
+AI 辅助开发会显著加快编码速度，但也容易带来架构漂移：
 
-该 npm 包暴露同一个 `archi` 命令，并在首次运行时创建用户缓存 Python 虚拟环境，安装匹配版本的 Architec GitHub tag。它要求 Node.js、Python 3.11+、git，并且首次运行需要网络访问。
+- 新实现重复造轮子；
+- 兼容路径和主实现混在一起；
+- 小改动绕过了模块边界；
+- helper 逐渐膨胀成无归属子系统；
+- 陈旧代码、陈旧文档和清理候选长期堆积；
+- 高风险文件在高 churn 区域继续扩张。
 
-## Architec、Hippo 和 llmgateway
+Architec 会把这些信号整理成结构化审查结果，帮助人类 reviewer 或 coding agent
+更快判断哪些建议值得进一步检查。
 
-Architec 是架构审查层，依赖两个运行时组件：
+## Architec、Hippos 和 llmgateway
+
+Architec 本身是架构审查层，依赖两个运行时组件：
 
 | 组件 | 命令 / 包 | 作用 |
 | --- | --- | --- |
 | **Architec** | `archi` / `architec` | 执行架构审查，通过 llmgateway 调用 LLM，并把结果写入 `.architec/`。 |
-| **Hippo** | `hippo` / `hippocampus` | 在 `.hippocampus/` 下生成结构快照，包括文件清单、代码签名、仓库索引、结构 prompt 和指标。 |
+| **Hippos** | `hippos` / `seemseam-hippos` | 生成 `.hippos/` 结构快照，包括文件清单、代码签名、仓库索引、结构 prompt 和指标。 |
 | **llmgateway** | `llmgateway` | 管理 provider 凭据、base URL、API 风格、模型名，以及 strong/weak 模型路由。 |
 
 ```text
 源码树 + git 变更
         |
         v
-Hippo 结构快照       ->  .hippocampus/
+Hippos 结构快照       ->  .hippos/
         |
         v
 Architec 证据构建    ->  增量范围或全项目上下文
@@ -83,66 +67,104 @@ llmgateway LLM 调用  ->  strong / weak 模型
 Architec 审查输出    ->  .architec/
 ```
 
-日常 `archi` 会使用 LLM，但不会默认刷新完整 Hippo 快照。`archi --full` 用于全项目审查。如果希望先刷新结构输入，再做全量审查，可以运行 `archi --refresh-from-hippo --full`。
+日常 `archi` 仍然会使用 LLM，但不会默认刷新完整 Hippos 快照。`archi --full`
+更依赖 Hippos 的全项目结构信息；如果要先刷新结构快照，可以运行：
+
+```bash
+archi --refresh-from-hippos --full
+```
+
+## 工作原理
+
+Architec 结合确定性代码信号和 LLM 解释：
+
+1. **选择范围**
+   - `archi` 读取当前 git 变更，聚焦 changed files。
+   - `archi --full` 审查整个项目。
+
+2. **读取结构上下文**
+   - Hippos 生成 `.hippos/` 快照。
+   - Architec 判断快照是否存在、是否陈旧、是否无法判断 freshness。
+
+3. **构建架构证据**
+   - 静态扫描重复逻辑、shadow implementation、边界压力、清理候选、热点、拓扑压力等。
+   - 增量审查会把 selected-change concerns 和全局上下文分开，避免小 diff 被全局噪音淹没。
+
+4. **交给 LLM 解释**
+   - Architec 把紧凑证据发送给 llmgateway。
+   - llmgateway 根据配置选择 strong 或 weak 模型，并负责 provider 凭据。
+
+5. **输出建议**
+   - Architec 对 concerns 排序，保留原始 artifacts，并生成 Markdown / JSON 输出。
+   - 输出是架构建议，不是 pass/fail，也不是运行时正确性的证明。
+
+## 安装
+
+需要 Python 3.11+。
+
+推荐从 PyPI 安装：
+
+```bash
+python3 -m pip install --user architec
+```
+
+这会安装：
+
+- `archi`：Architec CLI；
+- `seemseam-llmgateway`：提供 LLM provider 网关能力的包；
+- `seemseam-hippos`：提供 Hippos 结构快照能力的包。
+
+运行时 import 名仍是 `llmgateway` 和 `hippos`，不需要额外配置 Python 包索引。
+
+本地开发安装：
+
+```bash
+python3 -m pip install -e .
+```
 
 ## 配置 LLM
 
-Architec 的 LLM 访问全部通过 **llmgateway**。provider 凭据、base URL、API 风格和模型分层写在：
+Architec 的 LLM 调用全部通过 **llmgateway**。请在下面的文件中配置 provider
+和 strong/weak 模型：
 
 ```text
 ~/.llmgateway/config.yaml
 ```
 
-最小结构示例：
+最小示例：
 
 ```yaml
 version: 1
 provider:
   provider_type: openai
   api_style: openai_responses
-  base_url: https://your-llm-endpoint.example/v1
-  api_key: <set-locally>
+  base_url: https://your-llm-endpoint/v1
+  api_key: sk-...
 settings:
   strong_model: your-strong-model
   weak_model: your-fast-model
 ```
 
-这个文件应该只保存在本机，不要提交到仓库。Architec 不会把 LLM provider 凭据写入 `.architec/`；provider 配置和请求路由由 llmgateway 负责。
-
 检查安装和 LLM 路由：
 
 ```bash
 archi --check .
 ```
 
-如果检查提示缺少 LLM 配置，请更新 `~/.llmgateway/config.yaml`。
+## 快速使用
 
-## 快速开始
-
-审查当前目录里的 git 变更：
+审查当前变更：
 
 ```bash
 archi
 ```
 
-审查另一个项目路径：
-
-```bash
-archi /path/to/project
-```
-
 全项目架构审查：
 
 ```bash
 archi --full
 ```
 
-先刷新 Hippo 输入，再做全项目审查：
-
-```bash
-archi --refresh-from-hippo --full
-```
-
 保存 JSON 输出：
 
 ```bash
@@ -150,44 +172,26 @@ archi --out review.json
 archi --full --out full-review.json
 ```
 
-## CLI 命令速查
-
-| 命令 | 用途 |
-| --- | --- |
-| `archi` | 对当前 git 变更做增量 LLM 架构审查。 |
-| `archi <path>` | 对另一个项目根目录做增量审查。 |
-| `archi --full` | 对整个项目做 LLM 架构审查。 |
-| `archi --refresh-from-hippo --full` | 刷新 Hippo 结构输入后运行全量审查。 |
-| `archi --check .` | 检查 Hippo bundle 状态和 llmgateway 配置。 |
-| `archi --out review.json` | 保存增量审查 JSON。 |
-| `archi --version` | 显示当前 CLI 版本，并在可用时检查最新发布状态。 |
-| `archi update` | 通过配置的安装器重新安装最新公开构建。 |
-| `archi uninstall --yes` | 移除已安装的 launcher、托管资源、配置和依赖。 |
-
-仓库里仍保留一些兼容命令和隐藏参数，供旧自动化使用，例如 `archi code-review --full .`、`archi code-review --diff .`、`archi plan-review`、`archi status --snapshot` 和 `archi fix-advice --review review.json`。新用户应优先使用上面的顶层命令，并用下面的命令检查本机安装版本：
+刷新 Hippos 快照后再全量审查：
 
 ```bash
-archi --help
+archi --refresh-from-hippos --full
 ```
 
-## Architec 会报告什么
-
-Architec 会输出建议型 concerns 和 signals，包括：
+## 命令速查
 
-- **重复逻辑**：重复实现和可疑近似重复。
-- **Shadow implementation**：相似行为的第二套实现。
-- **架构契约**：import 边界或依赖方向压力。
-- **清理/归档候选**：陈旧代码、历史路径或需要整理的文档。
-- **热点区域**：churn 高、结构风险更大的文件或模块。
-- **拓扑压力**：过平、混乱或难以扩展的目录结构。
-- **快照新鲜度**：Hippo 上下文缺失、陈旧或 freshness 不可判断。
-- **风险上下文**：附加到现有 concerns 的可选外部事实。
-
-这些输出是建议，不是 pass/fail gate。
+| 命令 | 用途 |
+| --- | --- |
+| `archi` | 对当前 selected changes 进行增量 LLM 架构审查。 |
+| `archi --full` | 对整个项目进行 LLM 架构审查。 |
+| `archi --out review.json` | 保存增量审查 JSON。 |
+| `archi --full --out full-review.json` | 保存全量审查 JSON。 |
+| `archi --refresh-from-hippos --full` | 刷新 Hippos 结构输入后运行全量审查。 |
+| `archi --check .` | 检查 Hippos bundle 状态和 llmgateway 配置。 |
 
-## 输出目录
+## 输出
 
-Architec 会把生成文件写入 `.architec/`：
+Architec 写入 `.architec/`：
 
 ```text
 .architec/
@@ -200,27 +204,31 @@ Architec 会把生成文件写入 `.architec/`：
   cache/
 ```
 
-Hippo 会把结构输入写入 `.hippocampus/`。
+Hippos 写入 `.hippos/`。
 
-建议先读 `.architec/architec-summary.md`。需要精确分数、concern、signal 和 artifact 路径时，再看 `.architec/architec-analysis.json`。`.architec/` 和 `.hippocampus/` 都是本地生成的项目状态，通常不属于包发布内容。
+建议先读 `.architec/architec-summary.md`，需要精确字段时再看
+`.architec/architec-analysis.json`。
 
-## 依赖关系
+## Agent 命令兼容
 
-当前 Python 包声明：
+当前公开工作流是 `archi` 和 `archi --full`。部分旧版本 `archi` 可能仍显示旧命令形态：
+全量审查是 `archi .`，增量审查是 `archi --diff .`。
 
-- `llmgateway>=0.1.1`；
-- `hippocampus>=0.1.7`；
-- 来自 Python 包索引的 `PyYAML`、`certifi` 和 `cryptography`。
+Agent 和自动化脚本应先检查本机命令：
 
-发布 PyPI 前，维护者必须确认 companion package 版本能从目标 registry 安装。发布 npm 前，维护者必须确认 npm scope、Git tag，以及 launcher 使用的 Python 安装目标。
-
-## 无需登录
+```bash
+archi --help
+```
 
-架构分析命令不需要 `archi login`。
+| Help 输出 | 增量审查 | 全量审查 |
+| --- | --- | --- |
+| 包含 `--full` | `archi` | `archi --full` |
+| 不包含 `--full` 但包含 `--diff` | `archi --diff .` | `archi .` |
 
-Architec 只会把选中的架构证据发送给 llmgateway 中配置的 LLM provider。对私有代码运行分析前，请先确认 provider 配置。不要提交本机 provider 凭据、`.llmgateway/` 配置，或生成的 `.architec/`、`.hippocampus/` 输出，除非你明确希望共享它们。
+## 无需登录
 
-源码中可能存在账号相关命令，用于诊断或未来商业工作流；它们不是这里描述的 GitHub/本地分析流程的必要步骤。
+架构分析不需要 `archi login`。账号相关命令可能用于诊断，但不是日常 Architec
+分析流程的一部分。
 
 ## 开发
 
@@ -233,21 +241,10 @@ PYTHONPATH=src python3 -m pytest -q
 从当前 checkout 运行 Architec：
 
 ```bash
-PYTHONPATH=src python3 -m architec --help
 PYTHONPATH=src python3 -m architec
 PYTHONPATH=src python3 -m architec --full
 ```
 
-## 发布维护说明
-
-- `pyproject.toml`、`package.json` 和 `src/architec/_version.py` 当前声明版本为 `0.2.10`。
-- 现有 `v0.2.10` tag 指向较旧提交。不要为了新的 release state 复用或移动它。
-- 只有在版本、包元数据、README 和依赖策略都确定后，才创建新的 `vX.Y.Z` git tag。
-- 除非明确接受当前 dirty 状态，否则不要从 dirty worktree 发布。
-- PyPI 发布前需要验证 `architec` 项目名、目标版本、wheel/sdist 内容、依赖解析和 long description 渲染。
-- npm 发布前需要验证 package scope、`bin` 入口、files allowlist、launcher smoke test 和 Trusted Publishing 配置。
-- npm 发布细节见 [docs/npm-release.md](docs/npm-release.md)。
-
 ## 更多文档
 
 - [使用手册](docs/usage-manual.md)

package/bin/archi.js

@@ -1,135 +1,13 @@
 #!/usr/bin/env node
 "use strict";
 
-const fs = require("node:fs");
-const os = require("node:os");
-const path = require("node:path");
-const { spawnSync } = require("node:child_process");
-
-const PACKAGE_ROOT = path.resolve(__dirname, "..");
-const PACKAGE_JSON = JSON.parse(
-  fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"),
-);
-const VERSION = PACKAGE_JSON.version;
-const DEFAULT_SOURCE = `architec @ git+https://github.com/SeemSeam/architec.git@v${VERSION}`;
-const PYTHON_SPEC = process.env.ARCHITEC_NPM_PIP_SPEC || DEFAULT_SOURCE;
-const CACHE_ROOT =
-  process.env.ARCHITEC_NPM_CACHE_DIR ||
-  path.join(os.homedir(), ".cache", "architec", "npm");
-const VENV_DIR = path.join(CACHE_ROOT, VERSION, "venv");
-const MARKER_PATH = path.join(CACHE_ROOT, VERSION, "install.json");
-
-function fail(message, detail) {
-  console.error(`archi npm launcher: ${message}`);
-  if (detail) {
-    console.error(detail);
-  }
-  process.exit(1);
-}
-
-function run(command, args, options = {}) {
-  return spawnSync(command, args, {
-    stdio: options.stdio || "pipe",
-    encoding: options.encoding === false ? undefined : "utf8",
-    env: process.env,
-  });
-}
-
-function commandWorks(command) {
-  const result = run(command, ["--version"]);
-  return !result.error && result.status === 0;
-}
-
-function pythonVersion(command) {
-  const result = run(command, [
-    "-c",
-    "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')",
-  ]);
-  if (result.error || result.status !== 0) {
-    return null;
-  }
-  const [major, minor] = String(result.stdout || "").trim().split(".").map(Number);
-  if (!Number.isInteger(major) || !Number.isInteger(minor)) {
-    return null;
-  }
-  return { major, minor };
-}
-
-function findPython() {
-  const configured = process.env.ARCHITEC_NPM_PYTHON;
-  const candidates = configured ? [configured] : ["python3", "python"];
-  for (const candidate of candidates) {
-    if (!commandWorks(candidate)) {
-      continue;
-    }
-    const version = pythonVersion(candidate);
-    if (version && (version.major > 3 || (version.major === 3 && version.minor >= 11))) {
-      return candidate;
-    }
-  }
-  return null;
-}
-
-function venvPython() {
-  if (process.platform === "win32") {
-    return path.join(VENV_DIR, "Scripts", "python.exe");
-  }
-  return path.join(VENV_DIR, "bin", "python");
-}
-
-function installedMarkerMatches() {
-  try {
-    const marker = JSON.parse(fs.readFileSync(MARKER_PATH, "utf8"));
-    return marker.version === VERSION && marker.pythonSpec === PYTHON_SPEC;
-  } catch {
-    return false;
-  }
-}
-
-function ensureVenv() {
-  const targetPython = venvPython();
-  if (fs.existsSync(targetPython) && installedMarkerMatches()) {
-    return targetPython;
-  }
-
-  const python = findPython();
-  if (!python) {
-    fail(
-      "Python 3.11+ is required.",
-      "Set ARCHITEC_NPM_PYTHON to a Python 3.11+ executable, or install the Python package directly with pip.",
-    );
-  }
-
-  fs.mkdirSync(path.dirname(VENV_DIR), { recursive: true });
-  let result = run(python, ["-m", "venv", VENV_DIR], { stdio: "inherit" });
-  if (result.error || result.status !== 0) {
-    fail("failed to create the Python virtual environment");
-  }
-
-  result = run(targetPython, ["-m", "pip", "install", "--upgrade", PYTHON_SPEC], {
-    stdio: "inherit",
+const { main } = require("../lib/archi-dispatcher");
+
+main(process.argv.slice(2))
+  .then((status) => {
+    process.exit(status === undefined || status === null ? 0 : status);
+  })
+  .catch((error) => {
+    console.error(`archi npm dispatcher: ${error.message}`);
+    process.exit(1);
   });
-  if (result.error || result.status !== 0) {
-    fail(
-      "failed to install the Architec Python CLI.",
-      `Tried: ${targetPython} -m pip install --upgrade "${PYTHON_SPEC}"`,
-    );
-  }
-
-  fs.writeFileSync(
-    MARKER_PATH,
-    `${JSON.stringify({ version: VERSION, pythonSpec: PYTHON_SPEC }, null, 2)}\n`,
-  );
-  return targetPython;
-}
-
-const python = ensureVenv();
-const child = spawnSync(python, ["-m", "architec", ...process.argv.slice(2)], {
-  stdio: "inherit",
-  env: process.env,
-});
-
-if (child.error) {
-  fail("failed to start the Architec Python CLI", child.error.message);
-}
-process.exit(child.status === null ? 1 : child.status);

package/docs/npm-release.md

@@ -1,65 +1,85 @@
 # npm Release Notes
 
-This repository is a Python 3.11 CLI. The npm package is intentionally a thin
-launcher, not a Node.js rewrite.
+`@seemseam/architec` is a binary dispatcher for the Architec CLI. It is not a
+Node.js rewrite and it must not bundle the Python source trees for `architec`,
+`seemseam_hippos`, or `seemseam_llmgateway`.
 
 ## Package Identity
 
-- Recommended npm package name: `@seemseam/architec`.
-- The unscoped `architec` package name is already occupied on npm and does not
-  belong to this project.
-- CLI command exposed by npm: `archi`.
-- npm package version must match `pyproject.toml` and
-  `src/architec/_version.py`.
-
-## Runtime Strategy
-
-The npm `archi` bin uses Node.js only as a launcher. On first run it:
-
-1. finds Python 3.11+;
-2. creates a user-cache virtual environment under
-   `~/.cache/architec/npm/<version>/venv`;
-3. installs the matching GitHub tag with pip:
-   `architec @ git+https://github.com/SeemSeam/architec.git@v<version>`;
-4. executes `python -m architec` with the original CLI arguments.
-
-Environment overrides:
-
-- `ARCHITEC_NPM_PYTHON`: Python 3.11+ executable to use.
-- `ARCHITEC_NPM_CACHE_DIR`: cache root for the managed virtual environment.
-- `ARCHITEC_NPM_PIP_SPEC`: alternate pip requirement spec for smoke tests or
-  emergency repoints.
-
-This strategy requires Node.js, Python 3.11+, git, and network access on first
-run. It keeps npm installation lightweight and avoids postinstall side effects,
-but the npm tarball provenance covers the launcher, not the Python source tree
-installed later by pip.
-
-## Publication Preconditions
-
-- Own or create the npm scope used by `@seemseam/architec`.
-- Keep `package.json`, `pyproject.toml`, and `src/architec/_version.py` on the
-  same SemVer value.
-- Ensure the `vX.Y.Z` Git tag exists and points to the intended release commit
-  before publishing that npm version.
-- Do not reuse the existing `v0.2.10` tag for a different release commit.
-- Ensure the Python dependency chain is installable from the launcher target.
-  As of this audit, `llmgateway>=0.1.1` and `hippocampus>=0.1.7` still need
-  registry-ready releases before Architec can be published cleanly.
-- Run `npm pack --dry-run` and inspect the included files before publishing.
-- Do not publish from a dirty or unreviewed release state.
+- npm package: `@seemseam/architec`
+- CLI command: `archi`
+- npm version: must match the released Architec version on PyPI and the
+  GitHub tag, for example `0.2.11` and `v0.2.11`
+- source package: PyPI `architec`
+- binary source: GitHub Release standalone `archi` assets
+
+The unscoped npm package `architec` is owned by someone else and is not used.
+
+## Dispatcher Strategy
+
+The npm package contains a small Node.js dispatcher. On first run it:
+
+1. maps the current OS/CPU to a release asset name;
+2. downloads `archi-v<version>-checksums.txt` from the matching GitHub Release;
+3. downloads the matching `archi-v<version>-<platform>` binary;
+4. verifies the SHA-256 checksum before caching the binary;
+5. executes the cached binary on later runs.
+
+Default release URL:
+
+```text
+https://github.com/SeemSeam/architec/releases/download/v<version>/
+```
+
+The first npm release gate requires these assets for the selected platform
+matrix:
+
+```text
+archi-v0.2.11-linux-x64
+archi-v0.2.11-darwin-x64
+archi-v0.2.11-darwin-arm64
+archi-v0.2.11-win32-x64.exe
+archi-v0.2.11-checksums.txt
+```
+
+`linux-arm64` is supported by the dispatcher if an asset exists, but it is not
+part of the default first-release gate until a real Linux arm64 build runner and
+smoke test are selected.
+
+## Local Verification
+
+```bash
+npm test
+npm run pack:dry-run
+ARCHITEC_NPM_REQUIRED_TRIPLETS=linux-x64 npm run release-assets:check
+```
+
+The dispatcher smoke test uses a local file URL fixture and does not contact
+GitHub. `release-assets:check` contacts GitHub and fails until the matching
+GitHub Release binary assets and checksum file exist.
 
 ## Trusted Publishing
 
-After the first package exists on npm, configure npm Trusted Publishing with:
+Configure npm Trusted Publishing for the existing package:
+
+```text
+Provider: GitHub Actions
+Organization or user: SeemSeam
+Repository: architec
+Workflow filename: npm.yml
+Environment name: <blank>
+Allowed actions: npm publish
+```
+
+The workflow must exist at `.github/workflows/npm.yml`, use a GitHub-hosted
+runner, use Node 24 with npm 11.5.1 or newer, set `permissions:
+id-token: write`, and publish without `NODE_AUTH_TOKEN`.
 
-- Provider: GitHub Actions
-- Organization or user: `SeemSeam`
-- Repository: `architec`
-- Workflow filename: `release.yml`
-- Environment: blank unless the npm job uses a GitHub environment
-- Allowed actions: `npm publish`, or `npm stage publish` if staged publishing is
-  preferred
+## Release Order
 
-The GitHub Actions job should use a GitHub-hosted runner, Node 24, npm 11.5.1
-or newer, `permissions: id-token: write`, and no publish token.
+1. Publish `architec` to PyPI.
+2. Build standalone `archi` binaries from the released PyPI package set.
+3. Upload binaries and `archi-v<version>-checksums.txt` to the matching GitHub
+   Release.
+4. Verify `npm test`, `npm pack --dry-run`, and `release-assets:check`.
+5. Publish `@seemseam/architec@<version>` through npm Trusted Publishing.