trailcode · trailcode · Sep 1, 2026 · Aug 31, 2026 · Aug 31, 2026 · Aug 31, 2026
diff --git a/.github/workflows/source-hygiene.yml b/.github/workflows/source-hygiene.yml
@@ -10,9 +10,14 @@ on:
 jobs:
   ascii-src:
     runs-on: windows-latest
+    env:
+      PYTHONUTF8: "1"
     steps:
       - uses: actions/checkout@v4
 
-      - name: Check src/ for non-ASCII (comments and strings)
-        shell: cmd
-        run: scripts\check-nonascii-src.cmd
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: ASCII in src/ and tests/
+        run: python scripts/agent_check.py
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -766,7 +766,8 @@ if(RES_FILES)
   set_source_files_properties(${RES_FILES_REL} PROPERTIES HEADER_FILE_ONLY TRUE)
 endif()
 
-# Utility scripts: show scripts/ in the IDE (not compiled; same pattern as res/)
+# Utility scripts: show scripts/ in the IDE (not compiled; same pattern as res/).
+# Includes agent_check.py (ASCII) and optional code_style_check.py via this glob.
 file(GLOB_RECURSE EZYCAD_SCRIPT_FILES CONFIGURE_DEPENDS
   LIST_DIRECTORIES false
   "${CMAKE_SOURCE_DIR}/scripts/*")
@@ -782,6 +783,26 @@ if(EZYCAD_SCRIPT_FILES)
   set_source_files_properties(${EZYCAD_SCRIPT_FILES_REL} PROPERTIES HEADER_FILE_ONLY TRUE)
 endif()
 
+# Runnable IDE target: ASCII on src/ and tests/ (python scripts/agent_check.py).
+# Style (code_style_check.py) is optional/local, not this target or CI.
+if(NOT Python3_EXECUTABLE)
+  find_package(Python3 3.8 QUIET COMPONENTS Interpreter)
+endif()
+if(Python3_EXECUTABLE)
+  add_custom_target(ezycad_agent_check
+    COMMAND "${Python3_EXECUTABLE}" "${CMAKE_SOURCE_DIR}/scripts/agent_check.py"
+    WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+    COMMENT "EzyCad agent_check: ASCII (src/ and tests/)"
+    SOURCES
+      "${CMAKE_SOURCE_DIR}/scripts/agent_check.py"
+    VERBATIM
+  )
+  set_target_properties(ezycad_agent_check PROPERTIES
+    FOLDER "scripts"
+    EXCLUDE_FROM_ALL TRUE
+  )
+endif()
+
 # GitHub workflow files: show .github/workflows/*.yml in the IDE under 'github-workflows' folder
 # (so they are visible in Visual Studio Solution Explorer etc. without being compiled)
 file(GLOB_RECURSE GITHUB_WORKFLOW_FILES CONFIGURE_DEPENDS

diff --git a/agents.md b/agents.md
@@ -12,6 +12,7 @@ Pointer for AI coding assistants. Details live in [agents/README.md](agents/READ
 
 - [agents/conventions/ascii-source.md](agents/conventions/ascii-source.md) for `src/` and `tests/`
 - [docs/ezycad_code_style.md](docs/ezycad_code_style.md) for C++ style
+- After creating or editing C++ (`src/`, `tests/`) or Markdown tables: `python scripts/agent_check.py <touched paths>` (ASCII; table alignment for `.md`). Optional local style: `python scripts/code_style_check.py`. Do not run the individual ASCII scripts unless that one failed.
 
 ## When needed
 
@@ -23,8 +24,6 @@ Pointer for AI coding assistants. Details live in [agents/README.md](agents/READ
 - GUI module: [src/doc/gui.md](src/doc/gui.md) (read; update when input routing, modes, or settings change)
 - Script consoles: [src/doc/script.md](src/doc/script.md) (read; update when bindings or console UI change)
 - Utilities: [src/doc/utility.md](src/doc/utility.md) (read; update when utl_* contracts or I/O change)
-- Script consoles: [src/doc/script.md](src/doc/script.md) (read; update when bindings or console UI change)
-- Utilities: [src/doc/utility.md](src/doc/utility.md) (read; update when utl_* contracts or I/O change)
 - Build/test: [agents/workflows/local-dev.md](agents/workflows/local-dev.md) or root README
 - OCCT APIs / WASM (desktop 8 vs wasm 7.9.3): [agents/conventions/occt-wasm-dual-version.md](agents/conventions/occt-wasm-dual-version.md) — until wasm works on OCCT 8
 - OCCT handles (`Handle` vs `*_ptr`): [agents/conventions/occt-handles.md](agents/conventions/occt-handles.md)

diff --git a/agents/README.md b/agents/README.md
@@ -6,24 +6,24 @@ Root markers: [AGENTS.md](../AGENTS.md) / [agents.md](../agents.md).
 
 ## Quick index
 
-| Need                         | File                                                                                                                 |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| ASCII / `src/` edits         | [conventions/ascii-source.md](conventions/ascii-source.md)                                                           |
-| C++ style (full)             | [docs/ezycad_code_style.md](../docs/ezycad_code_style.md)                                                            |
-| User docs when UI changes    | [conventions/user-docs-sync.md](conventions/user-docs-sync.md)                                                       |
-| Sketch module (dev doc)      | [src/doc/sketch.md](../src/doc/sketch.md) — read when editing sketch code; update if API/architecture changes        |
-| Shape module (dev doc)       | [src/doc/shape.md](../src/doc/shape.md) — read when editing `shp_*` code; update if API/operations change            |
+| Need                         | File                                                                                                                                                           |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ASCII / `src/` edits         | [conventions/ascii-source.md](conventions/ascii-source.md) — after edits: `python scripts/agent_check.py <paths>`                                              |
+| C++ style (full)             | [docs/ezycad_code_style.md](../docs/ezycad_code_style.md) — optional local: `python scripts/code_style_check.py` (not CI)                                      |
+| User docs when UI changes    | [conventions/user-docs-sync.md](conventions/user-docs-sync.md)                                                                                                 |
+| Sketch module (dev doc)      | [src/doc/sketch.md](../src/doc/sketch.md) — read when editing sketch code; update if API/architecture changes                                                  |
+| Shape module (dev doc)       | [src/doc/shape.md](../src/doc/shape.md) — read when editing `shp_*` code; update if API/operations change                                                      |
 | GUI module (dev doc)         | [src/doc/gui.md](../src/doc/gui.md) — read when editing `gui_*` / viewer shell; update if routing or settings change; **new Mode/Command → hotkeys checklist** |
-| Script module (dev doc)      | [src/doc/script.md](../src/doc/script.md) — read when editing `scr_*`; update if bindings change                     |
-| Utility module (dev doc)     | [src/doc/utility.md](../src/doc/utility.md) — read when editing `utl_*`; update if shared helpers or I/O change      |
-| Build / test / wasm          | [workflows/local-dev.md](workflows/local-dev.md)                                                                     |
-| OCCT desktop 8 vs wasm 7.9.3 | [conventions/occt-wasm-dual-version.md](conventions/occt-wasm-dual-version.md) — until wasm works on OCCT 8          |
-| OCCT handles (`*_ptr`)       | [conventions/occt-handles.md](conventions/occt-handles.md) — prefer aliases over `Handle()` for clang-format         |
-| Release                      | [workflows/release.md](workflows/release.md)                                                                         |
-| Issue/PR drafts              | [drafts/](drafts/) — [github-drafts.md](conventions/github-drafts.md)                                                |
-| Feature plans (opt-in)       | [plans/](plans/) — load **only** when the prompt matches that feature ([token-lean](conventions/token-lean.md))      |
-| Token-saving rules           | [conventions/token-lean.md](conventions/token-lean.md)                                                               |
-| Markdown tables              | [conventions/markdown-tables.md](conventions/markdown-tables.md) — align GFM pipes for source + preview              |
-| Outreach (optional)          | [outreach/discoverability.md](outreach/discoverability.md)                                                           |
+| Script module (dev doc)      | [src/doc/script.md](../src/doc/script.md) — read when editing `scr_*`; update if bindings change                                                               |
+| Utility module (dev doc)     | [src/doc/utility.md](../src/doc/utility.md) — read when editing `utl_*`; update if shared helpers or I/O change                                                |
+| Build / test / wasm          | [workflows/local-dev.md](workflows/local-dev.md)                                                                                                               |
+| OCCT desktop 8 vs wasm 7.9.3 | [conventions/occt-wasm-dual-version.md](conventions/occt-wasm-dual-version.md) — until wasm works on OCCT 8                                                    |
+| OCCT handles (`*_ptr`)       | [conventions/occt-handles.md](conventions/occt-handles.md) — prefer aliases over `Handle()` for clang-format                                                   |
+| Release                      | [workflows/release.md](workflows/release.md)                                                                                                                   |
+| Issue/PR drafts              | [drafts/](drafts/) — [github-drafts.md](conventions/github-drafts.md)                                                                                          |
+| Feature plans (opt-in)       | [plans/](plans/) — load **only** when the prompt matches that feature ([token-lean](conventions/token-lean.md))                                                |
+| Token-saving rules           | [conventions/token-lean.md](conventions/token-lean.md)                                                                                                         |
+| Markdown tables              | [conventions/markdown-tables.md](conventions/markdown-tables.md) — align GFM pipes for source + preview                                                        |
+| Outreach (optional)          | [outreach/discoverability.md](outreach/discoverability.md)                                                                                                     |
 
 Full user-doc style: [docs/ezycad_doc_style.md](../docs/ezycad_doc_style.md). OCCT build: [docs/building-occt.md](../docs/building-occt.md).
diff --git a/agents/conventions/ascii-source.md b/agents/conventions/ascii-source.md
@@ -4,4 +4,4 @@ Use this as a **Cursor rule** or paste into your assistant context when editing
 
 In `src/` and `tests/`, keep **comments and string literals 7-bit ASCII** (no Unicode punctuation or symbols: smart quotes, en/em dashes, arrows, ellipsis, etc.). Use ASCII equivalents (`-`, `...`, `->`, `sqrt(2)`, plain `'`).
 
-Project style: [docs/ezycad_code_style.md](../../docs/ezycad_code_style.md) (sections **Formatting** / line endings and **Source encoding**). Verify with `scripts/check-nonascii-src.ps1` or `scripts/check-nonascii-src.cmd`.
+Project style: [docs/ezycad_code_style.md](../../docs/ezycad_code_style.md) (sections **Formatting** / line endings and **Source encoding**). After editing or creating `src/` or `tests/` C++, run `python scripts/agent_check.py <touched paths>` (ASCII). CI: `.github/workflows/source-hygiene.yml`. Standalone ASCII: `scripts/check-nonascii-src.ps1` or `check-nonascii-src.cmd`. Optional style (not CI): `python scripts/code_style_check.py`.
diff --git a/agents/conventions/markdown-tables.md b/agents/conventions/markdown-tables.md
@@ -45,10 +45,13 @@ Padding/alignment can make rows slightly longer; that is intentional for source
 ## Re-align helper
 
 ```bash
+python scripts/agent_check.py docs/usage.md
 python scripts/align_md_tables.py
 python scripts/align_md_tables.py --check
 ```
 
+After editing tables, agents should run `python scripts/agent_check.py <md files>` (check only). Use `align_md_tables.py` without `--check` to write aligned files.
+
 Skips `third_party/`, local `build*` trees, `_deps`, and similar vendor/output dirs.
 
 ## Related

diff --git a/agents/conventions/token-lean.md b/agents/conventions/token-lean.md
@@ -7,6 +7,7 @@ Goal: give assistants **only what they need** for the task at hand. Full style g
 1. Root [AGENTS.md](../../AGENTS.md) — pointers only (~20 lines).
 2. [ascii-source.md](ascii-source.md) — when touching `src/` or `tests/`.
 3. [docs/ezycad_code_style.md](../../docs/ezycad_code_style.md) — when writing C++ (do not duplicate in chat).
+4. After creating or editing C++ or Markdown tables: `python scripts/agent_check.py <touched paths>` (ASCII; MD tables if `.md`). Do not run `check-nonascii-src` / `align_md_tables --check` separately. `code_style_check.py` is optional, not CI.
 
 **Do not** auto-load: `workflows/release.md`, `outreach/`, `drafts/archive/`, `plans/` (except the one plan matching the prompt), or full `local-dev.md` unless building/releasing.
 
@@ -24,7 +25,7 @@ Goal: give assistants **only what they need** for the task at hand. Full style g
 | Script consoles (`src/scr*`, bindings)                                               | [src/doc/script.md](../../src/doc/script.md) — read before editing; update when `ezy`/`view` API or console UI changes                         |
 | Utilities (`src/utl*`, results, I/O, geometry)                                       | [src/doc/utility.md](../../src/doc/utility.md) — read before editing; update when shared helper contracts change                               |
 | Docs build                                                                           | [workflows/docs-build.md](../workflows/docs-build.md)                                                                                          |
-| Editing Markdown tables                                                              | [markdown-tables.md](markdown-tables.md) — align GFM pipes; `python scripts/align_md_tables.py`                                                |
+| Editing Markdown tables                                                              | [markdown-tables.md](markdown-tables.md) — align GFM pipes; after edits: `python scripts/agent_check.py <md files>`                            |
 | Release                                                                              | [workflows/release.md](../workflows/release.md)                                                                                                |
 | Specific issue/PR                                                                    | One file under `drafts/issues/active/` or `drafts/prs/active/`                                                                                 |
 | Feature plan under `plans/`                                                          | **Only** the matching file when the prompt is clearly about that feature (see [plans/README.md](../plans/README.md)); never bulk-load `plans/` |

diff --git a/agents/workflows/local-dev.md b/agents/workflows/local-dev.md
@@ -88,27 +88,30 @@ See `scripts/build-occt-793-wasm.ps1`, `scripts/build-occt-v8-wasm.ps1`, and sha
 
 ## Code quality and pre-commit checks
 
-- **Format C++** (run before committing changes under `src/`):
+- **After editing or creating code** (agents: one command, pass the files you touched):
 
   ```powershell
-  .\scripts\format-src.ps1
+  python scripts/agent_check.py src/gui.cpp src/gui.h
   ```
 
-  Requires `clang-format` (either in PATH or at the default LLVM location).
+  Runs ASCII on C++. With `.md` paths, also checks table alignment. Default (no args): `src/` and `tests/`. IDE: `ezycad_agent_check` CMake target. Optional local [code style](../../docs/ezycad_code_style.md) (not CI): `python scripts/code_style_check.py`.
 
-- **Check ASCII-only in src/ and tests/** (EzyCad_tests sources; must pass before commits; also enforced in CI):
+- **Format C++** (run before committing changes under `src/`):
 
   ```powershell
-  .\scripts\check-nonascii-src.ps1
-  # .cmd wrapper also available
+  .\scripts\format-src.ps1
   ```
 
-  See the ASCII rule in [docs/ezycad_code_style.md](../../docs/ezycad_code_style.md) and the summary in [agents/conventions/ascii-source.md](../conventions/ascii-source.md).
+  Requires `clang-format` (either in PATH or at the default LLVM location).
+
+- **ASCII-only** is also in `scripts/check-nonascii-src.ps1` / `.cmd`. CI (`.github/workflows/source-hygiene.yml`) runs `python scripts/agent_check.py`. Prefer that after edits so you do not launch a second checker.
 
 ## Other scripts
 
 - `scripts/ezycad/` — Importable remote client (put `scripts/` on `PYTHONPATH`, then `import ezycad`). Typed `ezy` / `view` / `sketch` API for IPython completion; see [docs/scripting.md](../../docs/scripting.md#remote-python---listen).
 - `scripts/ezycad_remote.py` — CLI wrapper (`python scripts/ezycad_remote.py`, or `python -m ezycad` with `scripts/` on the path). Smoke: `EzyCad --listen 127.0.0.1:8765`, then `python -c "import sys; sys.path.insert(0,'scripts'); import ezycad; print(ezycad.connect().view.sketch_count())"`.
+- `scripts/agent_check.py` — Post-edit ASCII check (Markdown tables if `.md` paths). Agents run this instead of `check-nonascii-src`. Optional `--style` runs `code_style_check.py`.
+- `scripts/code_style_check.py` — Optional local style from [docs/ezycad_code_style.md](../../docs/ezycad_code_style.md) (not CI).
 - `scripts/align_md_tables.py` — Align GFM pipe tables in `.md` files for source + preview readability (see [conventions/markdown-tables.md](../conventions/markdown-tables.md)).
 - `scripts/sync-github-pages-html.ps1` — Sync `web/` changes (EzyCad.html etc.) to the GitHub Pages wasm demo site.
 - `scripts/pbf-to-png.ps1` / `.py` — Icon / asset conversion helpers.

diff --git a/agents/workflows/release.md b/agents/workflows/release.md
@@ -20,7 +20,7 @@ See also the comment in `src/version.h`, the project declaration in `CHANGELOG.m
    - Help > About should start with a bold **EzyCad X.Y.Z** header (pulled from `EZYCAD_VERSION_STRING`).
 5. Run pre-commit checks:
    - `.\scripts\format-src.ps1`
-   - `.\scripts\check-nonascii-src.ps1`
+   - `python scripts/agent_check.py` (ASCII; covers `check-nonascii-src.ps1`)
 6. Commit the release prep changes (version bump + changelog + any doc tweaks).
 7. **Create and push only the annotated tag** (this is the trigger):
    ```powershell
Original file line number	Diff line number	Diff line change
Expand Up		@@ -4,4 +4,4 @@ Use this as a Cursor rule or paste into your assistant context when editing

		In `src/` and `tests/`, keep comments and string literals 7-bit ASCII (no Unicode punctuation or symbols: smart quotes, en/em dashes, arrows, ellipsis, etc.). Use ASCII equivalents (`-`, `...`, `->`, `sqrt(2)`, plain `'`).

		Project style: [docs/ezycad_code_style.md](../../docs/ezycad_code_style.md) (sections Formatting / line endings and Source encoding). Verify with `scripts/check-nonascii-src.ps1` or `scripts/check-nonascii-src.cmd`.
		Project style: [docs/ezycad_code_style.md](../../docs/ezycad_code_style.md) (sections Formatting / line endings and Source encoding). After editing or creating `src/` or `tests/` C++, run `python scripts/agent_check.py <touched paths>` (ASCII). CI: `.github/workflows/source-hygiene.yml`. Standalone ASCII: `scripts/check-nonascii-src.ps1` or `check-nonascii-src.cmd`. Optional style (not CI): `python scripts/code_style_check.py`.