2 files changed, 128 insertions, 0 deletions
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.