docs: use English and separate plugin agent guidance

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

6 files changed, 151 insertions, 47 deletions

diff --git a/AGENTS/CONVENTIONS.md b/AGENTS/CONVENTIONS.md
index e2c6ebd..a49b381 100644
--- a/AGENTS/CONVENTIONS.md
+++ b/AGENTS/CONVENTIONS.md
@@ -3,6 +3,11 @@
 These invariants span modules. Violating any of them breaks code you didn't touch.
 (Overview and build instructions: `ARCH.md`.)
 
+**Project text must be in English.** This applies to documentation, source comments,
+user-facing messages, examples and test fixtures. Unicode test data must not contain
+Chinese text. Keep user instructions in README files concise; put architecture,
+implementation notes and AI guidance in the relevant `AGENTS/` directory.
+
 **Tokens are raw `int`.** `Lexer::gettok()` returns negative values for the `Token`
 enum (`include/cps/Lexer.h`) and non-negative values for literal ASCII chars (`'('`,
 `'+'`, `'<'`). Parser and CodeGen switch on both forms interchangeably; `BinaryExprAST`
diff --git a/plugin/AGENTS.md b/plugin/AGENTS.md
index f0b45b5..721c6fd 100644
--- a/plugin/AGENTS.md
+++ b/plugin/AGENTS.md
@@ -1,3 +1,7 @@
-Refer to all markdown files in `plugin/AGENTS/`
+Refer to all markdown files in `plugin/AGENTS/`.
 
-@AGENTS/HOW_TO_COMMIT.md (apply global commit conventions)
\ No newline at end of file
+- `plugin/AGENTS/ARCH.md`: implementation, language rules and upstream reuse.
+- `plugin/AGENTS/DEVELOPMENT.md`: development, verification and packaging.
+
+Apply the global conventions in `AGENTS/CONVENTIONS.md` and
+`AGENTS/HOW_TO_COMMIT.md`.
diff --git a/plugin/AGENTS/ARCH.md b/plugin/AGENTS/ARCH.md
new file mode 100644
index 0000000..1f9e84c
--- /dev/null
+++ b/plugin/AGENTS/ARCH.md
@@ -0,0 +1,65 @@
+# Plugin architecture
+
+The extension registers `cie-pseudocode` for `.cps` files. It targets VS Code 1.85+
+and dark themes. Runtime code uses CommonJS JavaScript and the VS Code API, with
+no npm runtime dependencies or connection to the compiler or cpptools.
+
+## Native editor capabilities and upstream references
+
+- VS Code provides the TextMate engine, theme scope resolution, bracket pair
+  colors, automatic bracket closing, formatting commands and keybindings.
+- `language-configuration.json` adapts the built-in C++ configuration for CIE's
+  comments, brackets, quote pairs and identifiers.
+- `syntaxes/cie-pseudocode.tmLanguage.json` adapts small C++ comment, quote and
+  comma rules and uses the same general token scope categories. CIE keyword,
+  builtin, number and operator patterns are locally defined.
+- cpptools was consulted for provider registration. Its formatter and language
+  server are not called, imported or bundled. This extension is not a cpptools
+  fork. The formatting API accepts locally computed edits; it does not implement
+  CIE indentation itself.
+
+Native `indentationRules` and `onEnterRules` are not currently configured. The
+on-type provider uses the same custom block-depth engine as selection formatting.
+
+References, ignored by Git and excluded from the VSIX:
+
+- `reference/vscode-cpptools/`: shallow clone of
+  https://github.com/microsoft/vscode-cpptools
+- `reference/vscode-cpp/`: original configuration and grammar from
+  https://github.com/microsoft/vscode/tree/main/extensions/cpp
+
+Source attribution is retained in `ThirdPartyNotices.md`.
+
+## Custom CIE behavior
+
+- `src/extension.js` registers range and on-type formatting providers and manages
+  invalid bracket decorations for visible editors. Language changes reopen
+  documents, so refresh on document open as well as edits and editor changes.
+- `src/indentation.js` computes block depth from earlier lines and returns edits
+  to leading whitespace only. A selection ending at column zero excludes that
+  final line. Formatting is idempotent and preserves line endings and other text.
+- `src/lexical.js` masks quotes and comments while preserving UTF-16 offsets.
+- `src/brackets.js` uses a stack to report unmatched opening and closing brackets
+  and crossed types. Only invalid brackets receive the red decoration; native
+  bracket coloring handles valid pairs.
+
+## Language rules and defaults
+
+Follow the current compiler, rather than implementing every PDF feature:
+
+- Uppercase, case-sensitive keywords; ASCII `<-` assignment; `//` comments.
+- Double-quoted strings and single-quoted characters have no escapes or multiline
+  continuation. The compiler accepts `'''` as a quote character literal.
+- Blocks: IF/THEN/ELSE/ENDIF, WHILE/DO/ENDWHILE, REPEAT/UNTIL, FOR/NEXT,
+  FUNCTION/ENDFUNCTION, PROCEDURE/ENDPROCEDURE and record TYPE/ENDTYPE.
+- Separate THEN and DO lines activate the pending block once. Enum and pointer
+  `TYPE Name = ...` declarations do not open a record block.
+- Builtins: LENGTH, MID, RIGHT, LEFT, LCASE, UCASE, ASC, CHR, IS_NUM, NUM_TO_STR,
+  STR_TO_NUM and EOF. See the table in `lib/CodeGen/CodeGen.cc`.
+- CASE, classes, SET, DATE and random-file operations are outside the current
+  plugin scope. Do not add them without an explicit scope change.
+
+Language defaults use real Tabs, display width 4, disabled indentation detection,
+full automatic indentation, on-type formatting and native bracket pair colors.
+The default formatter is `ovfor4.cie-pseudocode`. User and workspace settings can
+override editor defaults.
diff --git a/plugin/AGENTS/DEVELOPMENT.md b/plugin/AGENTS/DEVELOPMENT.md
new file mode 100644
index 0000000..6a7da98
--- /dev/null
+++ b/plugin/AGENTS/DEVELOPMENT.md
@@ -0,0 +1,63 @@
+# Plugin development
+
+Keep `plugin/README.md` short and focused on installation and use. Put developer
+and AI notes here and in `ARCH.md`. All project text must be in English.
+
+## Commands
+
+Use Node.js 22+ for development. From `plugin/`:
+
+```sh
+npm ci --ignore-scripts
+npm run check
+npm test
+npm run package
+```
+
+`npm run package` runs syntax checks and the existing Node tests, then uses vsce
+to generate `cie-pseudocode-0.1.0.vsix`. Runtime dependencies are not bundled.
+`@vscode/vsce`, `vscode-textmate` and `vscode-oniguruma` are development tools only.
+
+Do simple verification before each feature commit and follow the global commit
+instructions. Do not introduce a complex test framework for routine changes.
+
+## Verification
+
+The existing tests check real TextMate tokenization, nested block indentation,
+selection context, idempotence and bracket errors. Keep Unicode offset tests,
+using English text and non-CJK characters such as an emoji.
+
+For changes to editor integration, check in VS Code with a dark theme:
+
+- Open `.cps` and confirm the language mode and syntax colors.
+- Press Enter after a block header and type an ending keyword to check Tab depth.
+- Format a selection inside a nested block and check its surrounding context.
+- Check mixed bracket nesting, unmatched left/right brackets, quotes and comments.
+- Repair errors and switch language or files to check decoration cleanup.
+
+Existing local editor smoke scripts, if present, live under the ignored
+`reference/vscode-smoke/` directory. They are not a required build dependency.
+
+## Packaging and installation
+
+`.vscodeignore` excludes tests, agent instructions, dependencies and build
+artifacts. Git ignores dependencies, VSIX files and editor test downloads.
+Check the generated package contains the runtime files, grammar, language
+configuration, concise English README and notices, without `AGENTS/` or tests.
+
+For a local installation, use the Extensions panel's **Install from VSIX...** or:
+
+```sh
+code --install-extension cie-pseudocode-0.1.0.vsix --force
+```
+
+In a remote terminal, `code` installs into the connected remote editor. For an
+isolated Electron test installation, unset `VSCODE_IPC_HOOK_CLI` and explicitly
+set both `--user-data-dir` and `--extensions-dir` on that test editor's CLI.
+For GUI tests in this environment, also unset `ELECTRON_RUN_AS_NODE`; a virtual
+display may be needed. Avoid changing the user's active editor during isolated
+tests.
+
+If user settings disable defaults, inspect the `[cie-pseudocode]` editor settings
+declared in `package.json`: real Tabs, tab size 4, automatic indentation, on-type
+formatting, the extension as default formatter and enabled bracket pair colors.
diff --git a/plugin/README.md b/plugin/README.md
index aa57cc8..a05c5fa 100644
--- a/plugin/README.md
+++ b/plugin/README.md
@@ -1,57 +1,24 @@
 # CIE Pseudocode
 
-用于本项目 `.cps` 文件的 VS Code 插件。需要 VS Code 1.85 或更新版本，仅适配深色主题，语法颜色跟随当前主题，参考 C++ 的配色分类。
+VS Code support for this project's `.cps` files. Requires VS Code 1.85 or newer and a dark theme.
 
-## 安装
+## Install
 
-在 VS Code 的扩展面板点击右上角 `…` → **Install from VSIX…（从 VSIX 安装）**，选择 `cie-pseudocode-0.1.0.vsix`。
-
-也可以在 VSIX 所在目录执行：
+In the Extensions panel, choose **... > Install from VSIX...** and select `cie-pseudocode-0.1.0.vsix`, or run:
 
 ```sh
 code --install-extension cie-pseudocode-0.1.0.vsix
 ```
 
-打开 `.cps` 文件后，右下角语言模式应显示 **CIE Pseudocode**。建议使用 **Dark+** 或其他深色主题。
-
-## 使用
-
-- **自动缩进**：默认每层一个真实 Tab，显示宽度为 4。块开始后回车自动缩进，输入完整的 `ELSE`、`ENDIF`、`NEXT` 等关键字时自动回退。
-- **整理选区**：选中代码，按 macOS 的 **⌘K，然后 ⌘F**；Windows/Linux 为 **Ctrl+K，然后 Ctrl+F**。也可以右键 → **Format Selection（格式化选区）**。只整理选中行的行首缩进，使用前文确定层级，保留其他文本和换行格式。空行整理后为空。
-- **括号**：圆括号和方括号按嵌套层级上色；落单左括号、落单右括号及类型错配立即变红，补齐后恢复。字符串、字符和注释中的括号不参与检查。
-- **高亮**：关键字、类型、布尔值、运算符、字符串、字符、数字、注释和 12 个内置函数使用对应的 C++ 风格配色分类。
-
-缩进支持 IF/ELSE、WHILE、REPEAT、FOR、FUNCTION、PROCEDURE 和记录 TYPE；`THEN`、`DO` 可以单独成行。枚举和指针的单行 `TYPE ... = ...` 不增加缩进。
-
-关键字必须大写；赋值使用 `<-`；注释使用 `//`；字符串及字符没有反斜杠转义。仅覆盖当前编译器已实现的语法，暂不支持 PDF 中的 CASE、类、SET、DATE 等未实现语法。
-
-示例在 [examples/highlighting.cps](examples/highlighting.cps)。这是编辑辅助插件，编译与运行仍使用项目的 `cpsc` 命令。
-
-如果用户或工作区设置覆盖了插件默认值，可在 VS Code 设置中确认：
-
-```json
-"[cie-pseudocode]": {
-  "editor.insertSpaces": false,
-  "editor.tabSize": 4,
-  "editor.detectIndentation": false,
-  "editor.autoIndent": "full",
-  "editor.formatOnType": true,
-  "editor.defaultFormatter": "ovfor4.cie-pseudocode",
-  "editor.bracketPairColorization.enabled": true
-}
-```
-
-## 开发与打包
+Open a `.cps` file. The language mode should show **CIE Pseudocode**.
 
-在 `plugin/` 目录下执行，开发依赖需要 Node.js 22 或更新版本：
+## Features
 
-```sh
-npm ci --ignore-scripts
-npm run check
-npm test
-npm run package
-```
+- C++ style syntax colors that follow your dark theme.
+- Automatic Tab indentation and outdent for block keywords.
+- **Format Selection**: select code, then press **Cmd+K, Cmd+F** on macOS or **Ctrl+K, Ctrl+F** on Windows/Linux. Only indentation changes.
+- Colored `()` and `[]` pairs; unmatched brackets turn red. Quotes and comments are ignored.
 
-打包命令会先检查语法并运行简单测试，然后生成 `cie-pseudocode-0.1.0.vsix`。插件运行时没有 npm 依赖，不需要安装编译器或 cpptools。VSIX、依赖和测试产物不提交 Git。
+Use uppercase keywords, `<-` for assignment and `//` for comments. Support matches the current compiler. Compile and run with `cpsc` separately.
 
-语言配置、注释/字符串规则及配色 scope 改造自 [VS Code 内置 C++ 扩展](https://github.com/microsoft/vscode/tree/main/extensions/cpp)，provider 注册方式参考 [cpptools](https://github.com/microsoft/vscode-cpptools)。本仓库的参考克隆位于 `reference/vscode-cpptools/`，原始 C++ 配置及 grammar 位于 `reference/vscode-cpp/`，均不纳入插件包。
+See [examples/highlighting.cps](examples/highlighting.cps) for an example.
diff --git a/plugin/test/brackets.test.js b/plugin/test/brackets.test.js
index acb18d0..e144335 100644
--- a/plugin/test/brackets.test.js
+++ b/plugin/test/brackets.test.js
@@ -22,7 +22,7 @@ test('comments and quotes are ignored with correct UTF-16 offsets after Unicode
 	assert.deepEqual(unmatchedBrackets('OUTPUT "[( //" // )]\nOUTPUT \'[\''), []);
 	const unfinished = 'OUTPUT "unfinished [\r\nA[';
 	assert.deepEqual(unmatchedBrackets(unfinished), [unfinished.length - 1]);
-	const unicode = 'OUTPUT "你好😀"\r\nA[';
+	const unicode = 'OUTPUT "Hello😀"\r\nA[';
 	assert.deepEqual(unmatchedBrackets(unicode), [unicode.length - 1]);
 	// Backslashes do not escape CIE quotes.
 	assert.deepEqual(unmatchedBrackets('"x\\"['), [4]);