@seemseam/architec 0.2.10 → 0.2.12

package/README.md

@@ -1,303 +1,12 @@
-# Architec
+# @seemseam/architec
 
-**Incremental architecture review for AI-assisted codebases.**
+Compatibility shim for the renamed `@seemseam/archi` package.
 
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
-[![CLI](https://img.shields.io/badge/CLI-archi-222222)](#quick-start)
-[![Login](https://img.shields.io/badge/login-not_required-green)](#no-login-required)
-
-[English](README.md) | [中文](README.zh-CN.md)
-
-Architec is a Python 3.11+ command-line tool that reviews architecture risk in
-code changes. It builds compact evidence from the repository, asks the
-configured LLM to interpret that evidence, and writes advisory reports for
-humans and coding agents.
-
-The practical question it helps answer is:
-
-> Will this change make the codebase harder to maintain?
-
-Architec does not edit code, approve merges, or prove runtime correctness. It
-reports risks worth checking: duplicated logic, shadow implementations, unclear
-module boundaries, stale structure, cleanup candidates, hotspots, and topology
-pressure.
-
-## Package Status
-
-This checkout is prepared for Python packaging and has a draft npm launcher:
-
-| Registry | Package name | CLI command | Status in this checkout |
-| --- | --- | --- | --- |
-| PyPI | `architec` | `archi` | Metadata, README, license, and wheel/sdist contents are configured. Do not publish until companion dependencies are available on the target index and a new release version/tag is chosen. |
-| npm | `@seemseam/architec` | `archi` | Scoped launcher package is configured, but the scope ownership, Trusted Publishing setup, and Python dependency chain still need release validation. |
-
-The unscoped npm package name `architec` is already occupied by an unrelated
-package, so npm publishing should use a scope you control. The Python
-distribution name and command name are intentionally different: the
-distribution is `architec`, while the installed console command is `archi`.
-
-Use registry install commands only after the relevant package page shows the
-intended version. As of this audit, the existing `v0.2.10` tag points to an
-older commit, so a future registry release should use a new version and tag.
-
-## Install
-
-Architec requires Python 3.11 or newer.
-
-Local development install from this checkout:
-
-```bash
-python3 -m pip install -e .
-```
-
-The package declares registry-style dependencies on `llmgateway>=0.1.1` and
-`hippocampus>=0.1.7` for PyPI compatibility. If those companion versions are
-not available from your configured package index yet, install the companion
-projects from source first, or wait for their registry releases before using
-normal dependency resolution.
-
-After a verified PyPI release, the expected install form is:
-
-```bash
-python3 -m pip install --user architec
-```
-
-Do not add that command to automation until the PyPI project page shows the
-intended version.
-
-npm distribution is prepared as a thin launcher package. After a verified npm
-release, the expected install form is:
-
-```bash
-npm install -g @seemseam/architec
-```
-
-That package exposes the same `archi` command, then creates a user-cache Python
-virtual environment on first run and installs the matching Architec GitHub tag.
-It requires Node.js, Python 3.11+, git, and network access on first run.
-
-## How It Fits Together
-
-Architec is the architecture review layer. It uses two companion components:
-
-| Component | Command / package | Role |
-| --- | --- | --- |
-| **Architec** | `archi` / `architec` | Runs architecture review, calls the LLM through llmgateway, and writes results under `.architec/`. |
-| **Hippo** | `hippo` / `hippocampus` | Builds structural project snapshots under `.hippocampus/`: file manifests, code signatures, repository indexes, structure prompts, and metrics. |
-| **llmgateway** | `llmgateway` | Owns provider credentials, base URLs, API style, model names, and strong/weak model routing. |
-
-```text
-source tree + git changes
-        |
-        v
-Hippo structural snapshot  ->  .hippocampus/
-        |
-        v
-Architec evidence builder  ->  selected-scope or full-project context
-        |
-        v
-llmgateway LLM call        ->  strong / weak model tiers
-        |
-        v
-Architec review output     ->  .architec/
-```
-
-Day-to-day `archi` runs use the LLM, but they do not refresh the full Hippo
-snapshot unless needed. `archi --full` reviews the whole project. Use
-`archi --refresh-from-hippo --full` when you want to refresh structural inputs
-before a full review.
-
-## Configure LLM Access
-
-Architec gets LLM access through **llmgateway**. Configure provider credentials,
-base URL, API style, and model tiers in:
-
-```text
-~/.llmgateway/config.yaml
-```
-
-Minimal shape:
-
-```yaml
-version: 1
-provider:
-  provider_type: openai
-  api_style: openai_responses
-  base_url: https://your-llm-endpoint.example/v1
-  api_key: <set-locally>
-settings:
-  strong_model: your-strong-model
-  weak_model: your-fast-model
-```
-
-Keep this file local and do not commit it. Architec does not store LLM provider
-credentials in `.architec/`; llmgateway owns provider configuration and request
-routing.
-
-Check the installation and LLM route:
-
-```bash
-archi --check .
-```
-
-If the check reports missing LLM configuration, update
-`~/.llmgateway/config.yaml`.
-
-## Quick Start
-
-Review the current git changes in the current directory:
-
-```bash
-archi
-```
-
-Review another project path:
-
-```bash
-archi /path/to/project
-```
-
-Run whole-project architecture review:
-
-```bash
-archi --full
-```
-
-Refresh Hippo inputs before whole-project review:
-
-```bash
-archi --refresh-from-hippo --full
-```
-
-Save JSON output:
-
-```bash
-archi --out review.json
-archi --full --out full-review.json
-```
-
-## CLI Command Summary
-
-| Command | Purpose |
-| --- | --- |
-| `archi` | Incremental LLM architecture review for current git changes. |
-| `archi <path>` | Incremental review for another project root. |
-| `archi --full` | Full-project LLM architecture review. |
-| `archi --refresh-from-hippo --full` | Refresh Hippo structural inputs, then run full review. |
-| `archi --check .` | Validate Hippo bundle state and llmgateway configuration. |
-| `archi --out review.json` | Save incremental review JSON. |
-| `archi --version` | Show the installed CLI version and latest release status when available. |
-| `archi update` | Reinstall the latest public Architec build through the configured installer. |
-| `archi uninstall --yes` | Remove the installed launcher, managed assets, configs, and dependencies. |
-
-Some compatibility commands and hidden flags remain for older automation, such
-as `archi code-review --full .`, `archi code-review --diff .`, `archi
-plan-review`, `archi status --snapshot`, and `archi fix-advice --review
-review.json`. New users should start with the top-level commands above and
-inspect the installed binary with:
-
-```bash
-archi --help
-```
-
-## What Architec Reports
-
-Architec reports advisory concerns and signals, including:
-
-- **Duplication**: repeated logic and suspicious near-duplicates.
-- **Shadow implementations**: second implementations of similar behavior.
-- **Architecture contracts**: import-boundary or dependency-direction pressure.
-- **Cleanup/archive candidates**: stale or legacy-looking code and docs.
-- **Hotspots**: churn-heavy or structurally risky areas.
-- **Topology pressure**: flat or confusing project structure.
-- **Snapshot freshness**: missing, stale, or unknown Hippo context.
-- **Risk context**: optional external facts attached to existing concerns.
-
-The output is advice, not a pass/fail gate.
-
-## Outputs
-
-Architec writes generated files under `.architec/`:
-
-```text
-.architec/
-  architec-analysis.json
-  architec-summary.md
-  architec-viz.html
-  code-review-concerns.json
-  code-review-discovery.json
-  review-events.jsonl
-  cache/
-```
-
-Hippo writes structural inputs under `.hippocampus/`.
-
-Start with `.architec/architec-summary.md` for the human-readable report. Use
-`.architec/architec-analysis.json` for exact scores, concerns, signals, and
-artifact paths. Both `.architec/` and `.hippocampus/` are generated local
-project state and are normally not package payload.
-
-## Dependencies
-
-The Python package declares:
-
-- `llmgateway>=0.1.1`;
-- `hippocampus>=0.1.7`;
-- `PyYAML`, `certifi`, and `cryptography` from Python package indexes.
-
-Before a PyPI release, maintainers must confirm that the companion package
-versions are available from the intended registry. Before an npm release,
-maintainers must confirm the npm scope, Git tag, and Python install target that
-the launcher will use.
-
-## No Login Required
-
-Architecture analysis commands do not require `archi login`.
-
-Architec sends selected architecture evidence only to the LLM provider
-configured in llmgateway. Review your provider configuration before running
-analysis on private code. Do not commit local provider credentials,
-`.llmgateway/` config, or generated `.architec/` and `.hippocampus/` outputs
-unless you intentionally want to share them.
-
-Account-related commands may exist in the source tree for diagnostics or future
-commercial workflows, but they are not required for the GitHub/local analysis
-workflow described here.
-
-## Development
-
-Run tests:
-
-```bash
-PYTHONPATH=src python3 -m pytest -q
-```
-
-Run Architec from this checkout:
+Install the primary package for new setups:
 
 ```bash
-PYTHONPATH=src python3 -m architec --help
-PYTHONPATH=src python3 -m architec
-PYTHONPATH=src python3 -m architec --full
+npm install -g @seemseam/archi
 ```
 
-## Release Maintainer Notes
-
-- `pyproject.toml`, `package.json`, and `src/architec/_version.py` currently
-  declare version `0.2.10`.
-- The existing `v0.2.10` tag points to an older commit. Do not reuse or move it
-  for a different release state.
-- Use a new `vX.Y.Z` git tag only after the version, package metadata, README,
-  and dependency strategy are final.
-- Do not publish from a dirty worktree unless that dirty state is explicitly
-  accepted for the release.
-- PyPI publishing should verify the `architec` project name, target version,
-  wheel/sdist contents, dependency resolution, and long description rendering.
-- npm publishing should verify the package scope, `bin` entry, files allowlist,
-  launcher smoke test, and Trusted Publishing configuration.
-- npm release details live in [docs/npm-release.md](docs/npm-release.md).
-
-## More Documentation
-
-- [Usage manual](docs/usage-manual.md)
-- [Architecture stability notes](docs/advisory-review/topics/architecture-stability.md)
-- [Evidence model](docs/advisory-review/topics/evidence-model.md)
+This package keeps the historical `@seemseam/architec` name installable and
+forwards the `archi` command to `@seemseam/archi`.

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("@seemseam/archi/lib/archi-dispatcher");
+
+main(process.argv.slice(2))
+  .then((status) => {
+    process.exit(status === undefined || status === null ? 0 : status);
+  })
+  .catch((error) => {
+    console.error(`archi npm shim: ${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/package.json

@@ -1,14 +1,7 @@
 {
   "name": "@seemseam/architec",
-  "version": "0.2.10",
-  "description": "npm launcher for the Architec Python architecture-review CLI.",
-  "keywords": [
-    "architecture",
-    "code-review",
-    "cli",
-    "llm",
-    "python"
-  ],
+  "version": "0.2.12",
+  "description": "Compatibility shim for the renamed @seemseam/archi package.",
   "homepage": "https://github.com/SeemSeam/architec#readme",
   "author": "SeemSeam",
   "bugs": {
@@ -16,7 +9,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/SeemSeam/architec.git"
+    "url": "https://github.com/SeemSeam/architec",
+    "directory": "npm/architec-shim"
   },
   "license": "MIT",
   "bin": {
@@ -24,8 +18,12 @@
   },
   "files": [
     "bin/",
-    "docs/npm-release.md"
+    "README.md",
+    "LICENSE"
   ],
+  "dependencies": {
+    "@seemseam/archi": "0.2.12"
+  },
   "engines": {
     "node": ">=18"
   },

package/README.zh-CN.md

@@ -1,255 +0,0 @@
-# Architec
-
-**面向 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)](#快速开始)
-[![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 不会自动修改代码，不会替你批准合并，也不能证明运行时正确性。它报告的是值得检查的架构风险，例如重复逻辑、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 .
-```
-
-为了满足 PyPI 发布兼容性，当前包声明了 registry 形式依赖：`llmgateway>=0.1.1` 和 `hippocampus>=0.1.7`。如果这些 companion 版本还不能从你配置的包索引安装，请先从源码安装 companion projects，或等待它们的 registry release 后再使用普通依赖解析。
-
-PyPI 包发布并验证后，预期安装方式是：
-
-```bash
-python3 -m pip install --user architec
-```
-
-在 PyPI 项目页显示目标版本之前，不要把这条命令写进自动化流程。
-
-npm 分发已按轻量 launcher 包方案准备。npm 包发布并验证后，预期安装方式是：
-
-```bash
-npm install -g @seemseam/architec
-```
-
-该 npm 包暴露同一个 `archi` 命令，并在首次运行时创建用户缓存 Python 虚拟环境，安装匹配版本的 Architec GitHub tag。它要求 Node.js、Python 3.11+、git，并且首次运行需要网络访问。
-
-## Architec、Hippo 和 llmgateway
-
-Architec 是架构审查层，依赖两个运行时组件：
-
-| 组件 | 命令 / 包 | 作用 |
-| --- | --- | --- |
-| **Architec** | `archi` / `architec` | 执行架构审查，通过 llmgateway 调用 LLM，并把结果写入 `.architec/`。 |
-| **Hippo** | `hippo` / `hippocampus` | 在 `.hippocampus/` 下生成结构快照，包括文件清单、代码签名、仓库索引、结构 prompt 和指标。 |
-| **llmgateway** | `llmgateway` | 管理 provider 凭据、base URL、API 风格、模型名，以及 strong/weak 模型路由。 |
-
-```text
-源码树 + git 变更
-        |
-        v
-Hippo 结构快照       ->  .hippocampus/
-        |
-        v
-Architec 证据构建    ->  增量范围或全项目上下文
-        |
-        v
-llmgateway LLM 调用  ->  strong / weak 模型
-        |
-        v
-Architec 审查输出    ->  .architec/
-```
-
-日常 `archi` 会使用 LLM，但不会默认刷新完整 Hippo 快照。`archi --full` 用于全项目审查。如果希望先刷新结构输入，再做全量审查，可以运行 `archi --refresh-from-hippo --full`。
-
-## 配置 LLM
-
-Architec 的 LLM 访问全部通过 **llmgateway**。provider 凭据、base URL、API 风格和模型分层写在：
-
-```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>
-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
-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`。新用户应优先使用上面的顶层命令，并用下面的命令检查本机安装版本：
-
-```bash
-archi --help
-```
-
-## Architec 会报告什么
-
-Architec 会输出建议型 concerns 和 signals，包括：
-
-- **重复逻辑**：重复实现和可疑近似重复。
-- **Shadow implementation**：相似行为的第二套实现。
-- **架构契约**：import 边界或依赖方向压力。
-- **清理/归档候选**：陈旧代码、历史路径或需要整理的文档。
-- **热点区域**：churn 高、结构风险更大的文件或模块。
-- **拓扑压力**：过平、混乱或难以扩展的目录结构。
-- **快照新鲜度**：Hippo 上下文缺失、陈旧或 freshness 不可判断。
-- **风险上下文**：附加到现有 concerns 的可选外部事实。
-
-这些输出是建议，不是 pass/fail gate。
-
-## 输出目录
-
-Architec 会把生成文件写入 `.architec/`：
-
-```text
-.architec/
-  architec-analysis.json
-  architec-summary.md
-  architec-viz.html
-  code-review-concerns.json
-  code-review-discovery.json
-  review-events.jsonl
-  cache/
-```
-
-Hippo 会把结构输入写入 `.hippocampus/`。
-
-建议先读 `.architec/architec-summary.md`。需要精确分数、concern、signal 和 artifact 路径时，再看 `.architec/architec-analysis.json`。`.architec/` 和 `.hippocampus/` 都是本地生成的项目状态，通常不属于包发布内容。
-
-## 依赖关系
-
-当前 Python 包声明：
-
-- `llmgateway>=0.1.1`；
-- `hippocampus>=0.1.7`；
-- 来自 Python 包索引的 `PyYAML`、`certifi` 和 `cryptography`。
-
-发布 PyPI 前，维护者必须确认 companion package 版本能从目标 registry 安装。发布 npm 前，维护者必须确认 npm scope、Git tag，以及 launcher 使用的 Python 安装目标。
-
-## 无需登录
-
-架构分析命令不需要 `archi login`。
-
-Architec 只会把选中的架构证据发送给 llmgateway 中配置的 LLM provider。对私有代码运行分析前，请先确认 provider 配置。不要提交本机 provider 凭据、`.llmgateway/` 配置，或生成的 `.architec/`、`.hippocampus/` 输出，除非你明确希望共享它们。
-
-源码中可能存在账号相关命令，用于诊断或未来商业工作流；它们不是这里描述的 GitHub/本地分析流程的必要步骤。
-
-## 开发
-
-运行测试：
-
-```bash
-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)
-- [架构稳定性说明](docs/advisory-review/topics/architecture-stability.md)
-- [证据模型](docs/advisory-review/topics/evidence-model.md)

package/docs/npm-release.md

@@ -1,65 +0,0 @@
-# npm Release Notes
-
-This repository is a Python 3.11 CLI. The npm package is intentionally a thin
-launcher, not a Node.js rewrite.
-
-## 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.
-
-## Trusted Publishing
-
-After the first package exists on npm, configure npm Trusted Publishing with:
-
-- 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
-
-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.