@eevee-ta/cli 1.0.1 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
-# @eevee/cli
+# @eevee-ta/cli
 
-`@eevee/cli` 是 eevee MCP 服务的业务化命令行客户端和 Agent Skill 管理工具。公开命令采用稳定 `<group> <action>` 规范；也可以继续使用完整 MCP 能力（tools/resources/prompts/request/notify）。CLI 可直接给 Codex、Claude Code 或其他终端 Agent 使用，也适合人工排查 eevee 数据。
+`@eevee-ta/cli` 是 eevee MCP 服务的业务化命令行客户端和 Agent Skill 管理工具。公开命令采用稳定 `<group> <action>` 规范；也可以继续使用完整 MCP 能力（tools/resources/prompts/request/notify）。CLI 可直接给 Codex、Claude Code 或其他终端 Agent 使用，也适合人工排查 eevee 数据。
 
 运行时零依赖，只需要 Node.js 16+。
 
@@ -8,12 +8,12 @@
 
 ### 一键安装（推荐）
 
-后续可将仓库中的 `install.sh` 上传到 OSS 后远程执行：
+使用 OSS 一键安装：
 
 ```bash
-curl -fsSL https://oss.example.com/eevee/install.sh | bash
+curl -fsSL http://tga-doc.oss-accelerate-overseas.aliyuncs.com/eevee-dev/install.sh | bash
 # 或
-wget -qO- https://oss.example.com/eevee/install.sh | bash
+wget -qO- http://tga-doc.oss-accelerate-overseas.aliyuncs.com/eevee-dev/install.sh | bash
 ```
 
 安装器会：
@@ -21,14 +21,14 @@ wget -qO- https://oss.example.com/eevee/install.sh | bash
 1. 检查 `curl/wget`、`tar`、系统架构和 musl/glibc 环境；
 2. 下载并安装新 CLI 前，先检查并删除旧平台 `tant-intl-agent-cli`，避免 `eevee` 命令冲突；
 3. Node.js 缺失或低于 16 时，从 npmmirror 下载用户级 Node.js 到 `~/.eevee/node`；
-4. 使用用户级 npm 全局目录 `~/.eevee/npm`，从国内 npm 镜像安装 `@eevee/cli@latest`，并将两个目录写入 shell PATH；
+4. 使用用户级 npm 全局目录 `~/.eevee/npm`，从国内 npm 镜像安装 `@eevee-ta/cli@latest`，并将两个目录写入 shell PATH；
 5. 自动探测并复制 Skill 到已安装 Agent 的全局目录。
 
 可用环境变量定制：
 
 | 变量 | 默认值 |
 |---|---|
-| `EEVEE_PACKAGE_NAME` | `@eevee/cli` |
+| `EEVEE_PACKAGE_NAME` | `@eevee-ta/cli` |
 | `EEVEE_NODE_VERSION` | `22.21.1` |
 | `EEVEE_NODE_MIRROR` | `https://npmmirror.com/mirrors/node` |
 | `EEVEE_NPM_REGISTRY` | `https://registry.npmmirror.com` |
@@ -49,7 +49,7 @@ npm link           # 同时提供 eevee 和 eevee-cli 命令
 已发布后从 npm 安装：
 
 ```bash
-npm install -g @eevee/cli@latest
+npm install -g @eevee-ta/cli@latest
 ```
 
 npm 包的 `postinstall` 也会自动执行 Skill 迁移；如果安装时使用 `--ignore-scripts`，可手动执行 `eevee skills update --auto --global --force`。
@@ -126,6 +126,7 @@ eevee config unset --token
 | `eevee <group> <action>` | 推荐：执行 project、version、term、translation 等约 50 个业务动作 |
 | `eevee business` / `eevee -h` | 查看全部业务命令；`-h` 会列全协议命令 |
 | `eevee <group> <action> --help` | 查看该动作的 path/query/body 参数和类型 |
+| `eevee i18n scan` | 本地扫描 JS/TS/JSX/Vue 与 Java Spring Boot 项目中的硬编码词条 |
 | `eevee update` | 检查、交互确认并更新到 npm latest，同时迁移 Skill |
 | `eevee config show/set/get/unset/path` | 管理服务器地址和用户 token |
 | `eevee doctor` | 校验配置、MCP 连接、tools/list 和已装 Skill |
@@ -146,6 +147,154 @@ eevee --url https://staging.example.com/mcp \
       ping
 ```
 
+## 国际化扫描与导出
+
+### 服务端词条导出
+
+按项目 `intl.json` 的 `outPaths / projectIds / tags` 配置从 EEVEE 服务端导出词条：
+
+```bash
+eevee i18n export                 # 默认写 path（开发目录）
+eevee i18n export --target build  # 写 buildPath（线上目录）
+eevee i18n export --env online    # --target build 的语义别名
+eevee i18n export --dry-run --json
+```
+
+每次只写入一个目录：`dev/offline` 使用 `path`，`build/online` 使用 `buildPath`。旧配置中以 `/` 开头的输出路径按项目根内路径处理。
+
+导出配置支持：
+
+```json
+{
+  "format": "json",
+  "groupByTag": true,
+  "clean": true,
+  "localeAliases": {
+    "zh-CN": "zh",
+    "en-US": "en"
+  },
+  "outPaths": [
+    {
+      "path": "/apps/gaia/public/intl/",
+      "buildPath": "/apps/gaia/public/intl/",
+      "projectIds": [
+        {
+          "projectId": 12,
+          "branchIds": [21, 22],
+          "tags": ["gaia"]
+        },
+        {
+          "projectId": 1,
+          "branchIds": [],
+          "tags": ["portal", "talos", null]
+        }
+      ]
+    }
+  ]
+}
+```
+
+规则：
+
+- `branchIds` 是 EEVEE 版本 ID 数组，`[]` 表示全部版本。数组内按配置顺序拉取，跨版本重复 key 由后配置版本覆盖；
+- `tags: []` 表示全部词条；
+- `tags: [null]` 表示无标签词条，也可以和普通标签混用；
+- `format` 支持 `json`、`js`、`ts`、`property`、`properties`；`js/ts` 输出 ESM `export default`；
+- `groupByTag: true` 输出 `语言-标签.格式`；`false` 输出 `语言.格式`；
+- `localeAliases` 只影响输出文件名，例如 `zh-CN` 配置为 `zh` 后输出 `zh-web.json`；
+- `clean: true` 时仅清理输出目录中符合当前语言命名规则的旧导出文件，再写入新文件；
+- 项目和标签都按配置顺序处理；不按标签分组合并时，重复 key 由后配置的项目/标签覆盖；
+- token 优先级为 `--token`、`EEVEE_TOKEN`、`intl.json` 的 `token`、本机 CLI 配置；`intl.json` 适合配置基础数据读取 token，个人 token 不建议提交到仓库。
+
+`i18n scan` 迁移自 `@tant/eslint-plugin-eevee` 的核心检查能力，但不要求目标项目安装 ESLint 插件，也不需要 Node 项目改造：
+
+```bash
+eevee i18n scan
+eevee i18n scan /path/to/project
+eevee i18n scan --json
+eevee i18n scan --include 'src/main/java/**/*.java' --exclude '**/generated/**'
+```
+
+CLI 会默认依次查找：
+
+```text
+intl.json
+.eevee/i18n.json
+eevee.i18n.json
+```
+
+旧版 ESLint 插件配置中的 `outPaths`、`includes`、`excludes`、`excludeAscii`、`tagMatchMap`、`excludePropertys`、`execludeTrack` 均继续可用，同时支持更正后的 `excludeProperties` 和 `excludeTrack`：
+
+```json
+{
+  "outPaths": [{ "path": "locales/" }],
+  "includes": ["src/**/*.{js,jsx,ts,tsx,vue}"],
+  "excludes": ["**/*.test.*"],
+  "excludeAscii": true,
+  "tagMatchMap": {
+    "src/pages/**": ["page"]
+  },
+  "excludeProperties": ["description"],
+  "excludeTrack": true
+}
+```
+
+检查规则：
+
+- 扫描 JavaScript / TypeScript 字符串、模板字符串、JSX / Vue 文案；
+- `formatMessage(...)` 内的词条会按 `zh-CN-<tag>.*` 词条文件检查「未登记」和「标签不匹配」；
+- 词条文件支持 JSON、`export default {}` / `module.exports = {}` 常见形态和 Spring properties；JS 词条只做静态解析，不执行项目代码；
+- 默认跳过纯 ASCII、导入导出字符串、对象属性 key、指定属性和埋点调用；
+- 默认跳过测试、Mock、Fixture 和构建生成文件；
+- 默认跳过模板字符串插值里的已国际化表达式；
+- TSX 中 `INTL.操作` 这类成员表达式不视为 JSX 文案；
+- 支持禁用注释：
+  - `// eevee-i18n-disable-next-line`
+  - `// eevee-i18n-disable`
+  - `// eevee-i18n-disable-file`
+- 默认与旧插件一致跳过普通函数调用的直接字符串参数，需要更严格检查时可加 `--check-call-arguments`。
+
+### Java Spring Boot 兼容
+
+CLI 不依赖 ESLint 解析 Java，因此可以直接在 Maven / Gradle 多模块 Spring Boot 仓库执行：
+
+```bash
+cd /path/to/spring-boot-service
+eevee i18n scan
+```
+
+默认包含：
+
+```text
+**/src/main/java/**/*.java
+**/src/main/resources/templates/**/*.{html,htm,jsp,jspf,tag,ftl,vm}
+```
+
+Java 支持包括：
+
+- 普通字符串和 Java 17 文本块；
+- 跳过 Java 注释；
+- 默认跳过注解中的中文说明，可用 `--check-annotations` 打开；
+- 识别 `MessageSource#getMessage` 使用 message key 的常规写法；
+- 支持 Thymeleaf / JSP / Freemarker / Velocity 模板文本和 UI 属性；
+- 跳过 `#{...}`、`${...}`、`<spring:message>`、`<fmt:message>` 等已国际化表达式；
+- 词条输出目录支持 `messages*_zh*_CN*.properties`。
+
+示例配置：
+
+```json
+{
+  "outPaths": ["src/main/resources/messages/"],
+  "includes": [
+    "**/src/main/java/**/*.java",
+    "**/src/main/resources/templates/**/*.{html,jsp}"
+  ],
+  "excludes": ["**/generated/**"]
+}
+```
+
+扫描发现问题会输出文件、行列、规则和词条；CI 中可直接使用非 0 退出码阻断流水线，`--no-fail` 可保留展示但不阻断。
+
 ## Business command layer
 
 Business commands 是主要接口，命名规范固定为 `<group> <action>`。它把底层 `call_api_operation` 封装成语义稳定、参数有类型的命令，不需要手工查找 `operation_id`：
@@ -158,10 +307,22 @@ eevee business
 eevee project list
 eevee project create --name Demo --locales zh-CN,en-US
 eevee project detail 12
+eevee version copy 12 34 --name 'Release 1.1' --description '复制版本资产'
+eevee term check-version-conflicts 12 --term-ids 56,57 --version-id 34
+eevee term move-version 12 --term-ids 56,57 --version-id 34
 eevee translation set-content --id 12 --term-id 34 --locale zh-CN --content 你好
 eevee project delete 12 --yes
 ```
 
+`term move-version` 会先调用冲突预检。交互终端会提示「全部忽略 / 全部覆盖 / 逐项选择」；
+非交互调用保持旧接口兼容语义，默认忽略冲突项，仅迁移无冲突词条。也可以显式指定：
+
+```bash
+eevee term move-version 12 --term-ids 56,57 --version-id 34 --conflict-strategy overwrite
+eevee term move-version 12 --term-ids 56,57 --version-id 34 \
+  --conflict-decisions '{"56":"ignore","57":"overwrite"}'
+```
+
 支持的域包括：project/version/term/translation/tag-group/tag/permission/log/profile/config/user。完整矩阵直接在 `eevee -h` 中列出。每个动作的完整 flag、位置说明、类型和必填状态用 `--help` 查看：
 
 ```bash
@@ -315,12 +476,16 @@ eevee notify notifications/cancelled '{"requestId":"<id>","reason":"user cancell
 
 ## Agent Skill 快速安装
 
-仓库中已经内置 `assets/skills/eevee-mcp/SKILL.md` 和 `reference.md`。
+仓库内置两个 Agent Skill：
+
+- `eevee-mcp`：业务数据操作与 MCP 能力。
+- `eevee-integration`：把 EEVEE 词条导出和代码扫描接入 Java Spring Boot 或 UmiJS 项目；包含项目/版本 ID 询问清单、目录纳入/屏蔽策略、提交钩子和误报处理。
 
 默认自动探测已安装的 Codex、Claude Code、Cursor 和 OpenCode，并复制到对应客户端的全局目录：
 
 ```bash
 eevee skills install
+eevee skills install --skill eevee-integration
 eevee skills agents    # 查看探测结果
 ```
 
@@ -340,6 +505,7 @@ eevee skills install codex
 eevee skills install claudecode
 eevee skills install universal
 eevee skills install --all
+eevee skills install --skill eevee-integration codex,claude
 ```
 
 复制到某个项目的 Claude/Codex 目录：

package/assets/skills/eevee-integration/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: eevee-integration
+description: Integrate @eevee-ta/cli term export and i18n scanning into Java Spring Boot or UmiJS/Umi Max repositories, including intl.json, scripts, Git hooks, project/version IDs, and include/exclude scope. Not for routine eevee data operations; use eevee-mcp for those.
+metadata:
+  short-description: Configure EEVEE CLI for Java or UmiJS repositories
+---
+
+# EEVEE Project Integration
+
+Use this skill when adding or changing EEVEE CLI integration in a application repository. Produce a reproducible configuration, project-specific scripts or npm scripts, documentation, and a commit-time check. Do not merely leave instructions in chat.
+
+## Mandatory intake
+
+Before writing or changing configuration, inspect the repository and ask the user for decisions that cannot be inferred. In particular, ask for all of the following that are not already authoritative in the repository:
+
+1. EEVEE server URL and token policy.
+2. Platform project ID(s). Never guess them.
+3. Version ID list. Clarify whether all versions are wanted (`branchIds: []`) or only selected IDs.
+4. Tag policy: all terms, selected tags, or `[null]` for untagged terms; whether output must be split by tag.
+5. Output directories for development and build artifacts, output format, and language filename aliases.
+6. Source-directory policy: which directories must be scanned, which are generated/test/mock/vendor and must be excluded, and how legacy debt should be handled.
+7. Commit-gate scope: staged files only or full repository.
+
+Use `references/intake.md` for the exact question set and decision rules. If the user supplies only some values, state the reasonable defaults you will use and ask only for decisions that materially change behavior.
+
+## Implementation route
+
+1. Inspect the existing build system, source layout, locale resources, lint scripts, and Git hooks.
+2. Read the mode-specific reference:
+   - Java 11 / Spring Boot / Maven or Gradle: `references/java-springboot.md`
+   - UmiJS / Umi Max / React front end: `references/umijs.md`
+3. Add `intl.json` at the repository root unless an existing configuration is authoritative.
+4. Add a small wrapper script or npm script rather than requiring people to remember long CLI invocations.
+5. Add a commit-time check for staged source files when the user wants commit gating.
+6. Document the configuration, commands, exclusions, suppression comments, and known legacy debt in the repository.
+7. Run dry-run export, real export where authorized, scanning, syntax/build checks, and the commit gate. Record actual commands and results.
+
+## Non-negotiable constraints
+
+- Do not guess project IDs, version IDs, tags, or output paths.
+- Do not commit personal tokens or machine-specific Maven settings. A basic read-only token may be committed only when the user explicitly says it is safe.
+- Prefer narrow, explainable exclusions and inline suppression comments over a long file-by-file baseline.
+- Do not silently overwrite locale resources. Confirm whether the EEVEE project is the source of truth and whether cleanup is enabled.
+- Preserve unrelated user modifications and do not reset a dirty worktree.
+- Keep full scans informational when there is known legacy debt; make the commit gate scan only staged files unless the user explicitly requires a full blocking scan.
+- When a repository uploads terms to EEVEE, include source metadata: `description` (usage location), `params` for placeholders, and `source_info` (`repo`/`branch`/`path`/`line` — all four together or omitted). Refresh existing translations with `translation set-content`; `term update` ignores `--translations`.

package/assets/skills/eevee-integration/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "EEVEE Integration"
+  short_description: "Configure EEVEE CLI for Java or UmiJS repositories"

package/assets/skills/eevee-integration/references/intake.md

@@ -0,0 +1,87 @@
+# EEVEE Integration Intake
+
+Use these questions before changing `intl.json`, wrapper scripts, or hooks. The goal is to make platform metadata and repository scope explicit rather than inferred.
+
+## Required platform questions
+
+Ask these unless the repository already contains authoritative answers:
+
+```text
+1. EEVEE MCP 地址是什么？token 是基础读取 token 还是个人 token？是否允许写入仓库？
+2. 使用哪个 EEVEE 项目 ID？多个项目需要合并导出吗？
+3. 每个项目使用哪些版本 ID？是全部版本（branchIds: []）还是指定 ID 列表？
+4. 词条按什么规则筛选？
+   - tags: [] 表示全部
+   - tags: [null] 表示无标签
+   - tags: ["web", null] 表示指定标签加无标签
+5. 输出是否按标签拆分？
+   - groupByTag: true -> zh-CN-web.json
+   - groupByTag: false -> zh-CN.json
+6. 输出格式是什么：json、js、ts、property、properties？
+7. 每种语言输出文件名是否需要别名？
+   例：zh-CN -> zh，或 zh-CN -> messages_zh_CN
+8. 开发目录 path 和构建目录 buildPath 分别是什么？每次导出只写其中一个，默认写哪个？
+```
+
+If the user knows the project but not IDs, offer discovery commands rather than guessing:
+
+```bash
+eevee project list --json
+eevee version list <project-id> --json
+eevee tag-group list <project-id> --json
+```
+
+`branchIds` is a required array in current CLI versions. Do not use legacy singular `branch` values.
+
+## Required repository-scope questions
+
+Ask these after inspecting the repository:
+
+```text
+1. 哪些源码目录包含用户可见文案，必须纳入扫描？
+2. 哪些目录是生成代码、测试、Mock、Fixture、文档示例、vendor 或构建产物，应该屏蔽？
+3. 存量未国际化文案是立即全量修复、全量阻断、还是先只阻断本次变更文件？
+4. 是否存在组件内部按词条 key 翻译的列配置或动态字典，需要用注释豁免？
+5. locale 资源目录是否只允许 EEVEE 导出，还是还保存手工文件？
+```
+
+### Include policy
+
+Start narrow and expand only with evidence:
+
+- Java: usually `**/src/main/java/**/*.java`; include template resources only when the project has server-rendered templates.
+- UmiJS: usually source directories such as `src/**/*.{ts,tsx,js,jsx}` or application-specific `apps/<app>/src/**`.
+- Scan real source directories, not an entire repository by default.
+- Always let CLI defaults exclude dependencies, build outputs, generated Umi directories, minified files, tests, mocks, and fixtures unless the user explicitly requires otherwise.
+
+### Exclude and suppression policy
+
+Prefer this order:
+
+1. Correct the code by moving user-visible text to the project's i18n mechanism.
+2. Use an inline comment for a semantic false positive:
+   ```ts
+   title: '操作', // eevee-i18n-disable：组件内部按 key 翻译
+   ```
+3. Use a next-line comment for declarations or dynamic dictionary keys:
+   ```ts
+   // eevee-i18n-disable-next-line：动态拼接词条字典 key
+   const title = REPO_INTL[`${isEdit ? '编辑' : '新建'}表`];
+   ```
+4. Use file-level suppression only when the entire file is a term-key map, internal mapping, Mock, or generated equivalent:
+   ```java
+   // eevee-i18n-disable-file：本文件只维护词条 key
+   ```
+5. Add a directory or glob to `excludes` only for generated/test/mock/vendor content or an explicitly approved legacy-debt boundary.
+6. Do not maintain an unexplained list of hundreds of source files. If full scanning has legacy debt, keep it informational with `--no-fail` and gate only staged files.
+
+## Output and gate decisions
+
+Confirm these before writing files:
+
+- Is EEVEE the source of truth? A real export can remove keys that exist locally but are absent in the selected EEVEE project/version/tag set.
+- Is `clean` enabled? Cleanup deletes old generated language-prefix files; hand-written files in the output directory need another location or a non-language prefix.
+- Should the commit hook scan only staged files? This is normally preferred for repositories with legacy debt.
+- Which existing build checks must accompany the EEVEE check?
+
+Record the user's answers and the resulting defaults in project documentation before implementation.

package/assets/skills/eevee-integration/references/java-springboot.md

@@ -0,0 +1,182 @@
+# Java Spring Boot Integration
+
+Use this reference for Java 11+ Spring Boot Maven or Gradle repositories.
+
+## Inspect first
+
+Determine:
+
+- Maven or Gradle multi-module layout.
+- JDK version and Maven version.
+- Spring MessageSource basename, normally in `application*.yml`.
+- Existing resource path, such as:
+  ```yaml
+  spring:
+    messages:
+      basename: static/i18n/messages
+  ```
+- Existing resource naming:
+  ```text
+  messages_zh_CN.properties
+  messages_en_US.properties
+  messages_ja_JP.properties
+  messages_ko_KR.properties
+  ```
+- Existing wrapper scripts, Git hooks, and build validation commands.
+
+## `intl.json` shape
+
+A typical all-version, no-tag Java configuration is:
+
+```json
+{
+  "url": "https://eevee.example.com/mcp",
+  "token": "<basic-read-token-if-approved>",
+  "includes": ["**/src/main/java/**/*.java"],
+  "excludeAscii": true,
+  "excludeTrack": true,
+  "format": "properties",
+  "groupByTag": false,
+  "clean": false,
+  "localeAliases": {
+    "zh-CN": "messages_zh_CN",
+    "en-US": "messages_en_US",
+    "ja-JP": "messages_ja_JP",
+    "ko-KR": "messages_ko_KR"
+  },
+  "outPaths": [
+    {
+      "path": "/src/main/resources/static/i18n/",
+      "buildPath": "/target/classes/static/i18n/",
+      "projectIds": [
+        {
+          "projectId": 3,
+          "branchIds": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+Adjust only after confirming IDs and output expectations with the user. A leading `/` in `path` or `buildPath` is repository-relative, not an absolute filesystem path.
+
+## Wrapper script
+
+Prefer `scripts/eevee-i18n.sh` with actions such as:
+
+```bash
+scripts/eevee-i18n.sh export --dry-run
+scripts/eevee-i18n.sh export
+scripts/eevee-i18n.sh export --target build
+scripts/eevee-i18n.sh scan --no-fail
+scripts/eevee-i18n.sh scan-changed
+scripts/eevee-i18n.sh check
+```
+
+`check` normally performs:
+
+1. `git diff --check`
+2. EEVEE export dry-run
+3. Full EEVEE scan with `--no-fail` for legacy visibility
+4. Blocking scan of staged Java files
+5. Maven `validate`
+
+Use `EEVEE_CLI`, `MVN_CMD`, and `MAVEN_LOCAL_REPO` overrides for developer environments.
+
+## Commit hook
+
+Use `.githooks/pre-commit` and configure:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+Hook behavior:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(git rev-parse --show-toplevel)"
+"$ROOT/scripts/eevee-i18n.sh" scan-changed
+```
+
+`scan-changed` must collect only:
+
+```bash
+git diff --name-only --cached --diff-filter=ACMR | grep -E '\.java$'
+```
+
+Skip cleanly when there are no staged Java files. This prevents thousands of legacy findings from blocking every commit while still checking files changed by the current work.
+
+## Java suppression comments
+
+The scanner understands real Java comments, including block comments:
+
+```java
+// eevee-i18n-disable-next-line：组件内部按 key 翻译
+private String title = "操作";
+```
+
+```java
+private String title = "操作"; // eevee-i18n-disable：内部枚举显示名
+```
+
+```java
+// eevee-i18n-disable-file：本文件只维护后端返回类型标识
+```
+
+Do not put the directive inside a string; it must be an actual comment.
+
+## Validation
+
+Run in this order:
+
+1. `scripts/eevee-i18n.sh export --dry-run`
+2. Real export only after the user confirms EEVEE is the source of truth
+3. Properties consistency:
+   - same key set in every locale
+   - no duplicate keys
+   - expected key count
+   - placeholder parity where applicable
+4. `scripts/eevee-i18n.sh scan --no-fail`
+5. Positive and negative commit-hook tests:
+   - no staged Java file exits 0
+   - a staged temporary Java file with hardcoded user-visible Chinese exits non-zero
+6. Maven validation, usually:
+   ```bash
+   mvn -s settings.xml -Dmaven.repo.local="$HOME/.m2/repository" validate
+   ```
+
+On a clean repository, some Maven `banCircularDependencies` configurations resolve reactor siblings from the local repository. If validate fails with missing sibling artifacts, bootstrap once with the project's known-compatible Maven version:
+
+```bash
+mvn -s settings.xml \
+  -Dmaven.repo.local="$HOME/.m2/repository" \
+  -DskipTests install
+```
+
+Then rerun validate. Keep machine-specific credentials and repository paths out of committed settings.
+
+## Documentation to leave in the repository
+
+Record:
+
+- EEVEE project and version policy
+- whether tags are used
+- output paths and format
+- full command list
+- commit-hook scope
+- known legacy-debt count and policy
+- all non-obvious directory exclusions and suppression examples
+
+
+## Term upload requirements (source metadata)
+
+When backfilling terms extracted from Java sources or resource bundles, upload
+`source_info` (`repo`/`branch`/`path`/`line`, all four together or omitted) and
+`params` for message placeholders, plus `description` recording the class/usage
+location. `term create --translations` sets initial translations; refreshing an
+existing term's translation must go through `translation set-content` per locale
+(`term update` ignores `--translations`). Keep upload scripts idempotent by
+diffing against `eevee term list` before writing.