Add developer module docs under src/doc/

CMakeLists.txt

@@ -820,6 +820,22 @@ if(EXISTS ${CHANGELOG_FILE})
     set_source_files_properties(${CHANGELOG_FILE} PROPERTIES HEADER_FILE_ONLY TRUE)
 endif()
 
+# src/doc: developer markdown for src modules (non-compiled; nested folders under src\doc in the IDE)
+file(GLOB_RECURSE SRC_DOC_FILES CONFIGURE_DEPENDS
+  LIST_DIRECTORIES false
+  "${CMAKE_SOURCE_DIR}/src/doc/*")
+if(SRC_DOC_FILES)
+  source_group(TREE "${CMAKE_SOURCE_DIR}/src/doc" PREFIX "src\\doc" FILES ${SRC_DOC_FILES})
+  set(SRC_DOC_FILES_REL)
+  foreach(f ${SRC_DOC_FILES})
+    file(RELATIVE_PATH f_rel "${CMAKE_SOURCE_DIR}" "${f}")
+    list(APPEND SRC_DOC_FILES_REL "${f_rel}")
+  endforeach()
+  target_sources(${PROJECT_NAME}_lib PRIVATE ${SRC_DOC_FILES_REL})
+  target_sources(${PROJECT_NAME} PRIVATE ${SRC_DOC_FILES_REL})
+  set_source_files_properties(${SRC_DOC_FILES_REL} PROPERTIES HEADER_FILE_ONLY TRUE)
+endif()
+
 # Add .clang-format and .gitignore to EzyCad and EzyCad_lib so they appear in VS and other IDEs (at project root)
 set(CLANG_FORMAT_FILE ${CMAKE_SOURCE_DIR}/.clang-format)
 if(EXISTS ${CLANG_FORMAT_FILE})

README.md

@@ -103,6 +103,8 @@ EzyCad is maintained by a small team and we would love more contributors. If you
 
 **Style guides:** [ezycad_code_style.md](docs/ezycad_code_style.md) for C++ in `src/`; [ezycad_doc_style.md](docs/ezycad_doc_style.md) for user guides and [Read the Docs](https://ezycad.readthedocs.io/). Both human developers and AI coding agents should follow the relevant guide.
 
+**Developer module docs:** Maintainer notes for major `src/` modules live under [src/doc/](src/doc/) (sketch, shape, GUI, script, utilities). These are for contributors working in the codebase, not end-user guides.
+
 **AI / agent instructions:** Short repo-local notes for coding assistants live under [agents/](agents/). Root-level discovery markers are `AGENTS.md` and `agents.md`. See [agents/README.md](agents/README.md) for the index (start with [agents/workflows/local-dev.md](agents/workflows/local-dev.md)).
 
 ## In-tree third-party libraries

agents.md

@@ -12,6 +12,13 @@ Pointer for AI coding assistants. Details live in [agents/README.md](agents/READ
 ## When needed
 
 - UI/settings/docs changes: [agents/conventions/user-docs-sync.md](agents/conventions/user-docs-sync.md)
+- Sketch subsystem: [src/doc/sketch.md](src/doc/sketch.md) (read; update when API or architecture changes)
+- Shape module: [src/doc/shape.md](src/doc/shape.md) (read; update when API or operation patterns change)
+- 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
 - Release (maintainers only): [agents/workflows/release.md](agents/workflows/release.md)
 - Open work context: one file under [agents/drafts/](agents/drafts/) if relevant

agents/README.md

@@ -11,6 +11,11 @@ Root markers: [AGENTS.md](../AGENTS.md) / [agents.md](../agents.md).
 | 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 |
+| GUI module (dev doc) | [src/doc/gui.md](../src/doc/gui.md) — read when editing `gui_*` / viewer shell; update if routing or settings change |
+| 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) |
 | Release | [workflows/release.md](workflows/release.md) |
 | Issue/PR drafts | [drafts/](drafts/) — [github-drafts.md](conventions/github-drafts.md) |

agents/conventions/token-lean.md

@@ -16,6 +16,11 @@ Goal: give assistants **only what they need** for the task at hand. Full style g
 | --- | --- |
 | Build / test | [workflows/local-dev.md](../workflows/local-dev.md) — or root [README.md](../../README.md#building-instructions) |
 | User-visible UI/settings | [user-docs-sync.md](user-docs-sync.md) + target `docs/usage-*.md` only |
+| Sketch subsystem (`src/sketch*`, `tests/sketch_tests.cpp`, sketch behavior in `occt_view` / `gui`) | [src/doc/sketch.md](../../src/doc/sketch.md) — read before editing; update when API, invariants, module layout, or workflows change |
+| Shape module (`src/shp*`, shape ops in `occt_view` / `gui`) | [src/doc/shape.md](../../src/doc/shape.md) — read before editing; update when API, operation patterns, or registration/undo change |
+| GUI / viewer shell (`src/gui*`, input routing, settings panes) | [src/doc/gui.md](../../src/doc/gui.md) — read before editing; update when modes, Options, hotkeys, or settings keys change |
+| 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) |
 | Release | [workflows/release.md](../workflows/release.md) |
 | Specific issue/PR | One file under `drafts/issues/active/` or `drafts/prs/active/` |
@@ -28,6 +33,28 @@ Goal: give assistants **only what they need** for the task at hand. Full style g
 - Prefer **GitHub issue/PR links** over pasting long draft bodies into rules.
 - Drop scratch files (`*-pr-body.txt`, duplicate templates).
 
+## Developer docs in `src/doc/`
+
+Module notes live under `src/doc/` (IDE folder `src\doc`; see root `CMakeLists.txt`). They are **not** user guides — do not duplicate `docs/usage-*.md`.
+
+| Module doc | When |
+| --- | --- |
+| [src/doc/sketch.md](../../src/doc/sketch.md) | Editing `src/sketch*`, `tests/sketch_tests.cpp`, or sketch-facing behavior in `occt_view` / `gui` / `mode` |
+| [src/doc/shape.md](../../src/doc/shape.md) | Editing `src/shp*`, shape operations in `occt_view` / `gui`, or 3D solid behavior |
+| [src/doc/gui.md](../../src/doc/gui.md) | Editing `src/gui*`, `Occt_view` in `gui_occt_view*`, input routing, Options/Settings UI |
+| [src/doc/script.md](../../src/doc/script.md) | Editing `src/scr*`, Lua/Python bindings, console behavior |
+| [src/doc/utility.md](../../src/doc/utility.md) | Editing `src/utl*`, `Status`/`Result`, `.ezy` I/O, geometry/settings helpers |
+
+**On sketch changes:** read `sketch.md` first for context. Update it in the same branch when you change public `Sketch` API, coordinator/sub-module boundaries, invariants (IDs, undo, transient vs committed state), or developer usage patterns. Skip updates for internal-only refactors with no doc impact.
+
+**On shape changes:** read `shape.md` first for context. Update it when you change `Shp` API, `Shp_operation_base` contract, operation class behavior, undo/finalize patterns, or how shapes are registered in `Occt_view`. Skip updates for internal-only refactors with no doc impact.
+
+**On GUI changes:** read `gui.md` first for context. Update it when you change input routing, mode/options panels, toolbar commands, settings JSON keys, or pane visibility rules. Sync user docs per `user-docs-sync.md` when behavior is user-visible.
+
+**On script changes:** read `script.md` and sync [`docs/scripting.md`](../../docs/scripting.md) when user-visible bindings change.
+
+**On utility changes:** read `utility.md` when altering `Status`/`Result`, `.ezy` format, asset store, or widely used geometry/settings helpers.
+
 ## Cursor / IDE rules
 
 Keep personal rules minimal: point at `AGENTS.md` and `agents/conventions/ascii-source.md`. Avoid copying whole `local-dev.md` or `release.md` into global rules.

agents/workflows/local-dev.md

@@ -68,8 +68,6 @@ High-level flow (after `emsdk_env`):
    ninja -C build-em-7-9-3
    ```
 
-   **Wasm GLES bisection:** uncomment one toggle in `src/occt_view_wasm_bisect.h`, then `ninja`.
-
 3. Serve locally:
 
    ```powershell

docs/bugs.md

@@ -42,4 +42,4 @@
   - `add_arc_circle_edges` (`sketch_edges.cpp`) may use inconsistent node indices for intersection/knot logic vs `GC_MakeArcOfCircle` (vector is `[start, pick, end]` from `Sketch::add_arc_circle_`; `pt_end` / knot end node must be `node_idxs[2]`, not `[1]`). A long-standing knot bug masked wrong argument order in circle finalize (`sketch_tools.cpp`: `add_arc_circle_(points[0], points[2], points[1])` passes bottom/top as `pt_b` where the API expects arc *end*, with pick on the opposite side).
   - `update_faces()` face walker can loop on parallel shared edges (e.g. slot horizontals); a `Walk_key` step cap was added in `sketch_topo.cpp` as a guard — may hide topology errors rather than fix turn logic.
   - Relevant tests (if re-added): `SlotHorizontalLinesUnsplitBeforeCircleArcs`, `ArcSplit_CircleCrossesSlotLines` in `tests/sketch_tests.cpp`. Use `slot_c` perpendicular to the slot centerline (e.g. `(15, 5)` for `slot_b = (15, 0)`), not `(0, 5)`, to match the slot tool.
-* Wasm / OCCT 8.x GLES shading regression: With OCCT **8.0.0.p1** (`V8_0_0_p1`) and `TKOpenGles`, new solids and extrude previews often render wireframe-only or with partial face shading in the browser. Native desktop (OCCT 8 + `TKOpenGl`) is unaffected. Rebuilding against **7.9.3** (`scripts/build-occt-793-wasm.ps1`) restores correct shading. Workarounds in EzyCad (`SetMaterial` + `Redisplay`, `refresh_shape_shading_`, bisect toggles in `occt_view_wasm_bisect.h`) do not fix the root cause on OCCT 8. Use 7.9.3 for wasm builds and demo publishing until upstream fixes GLES presentation.
+* Wasm / OCCT 8.x GLES shading regression: With OCCT **8.0.0.p1** (`V8_0_0_p1`) and `TKOpenGles`, new solids and extrude previews often render wireframe-only or with partial face shading in the browser. Native desktop (OCCT 8 + `TKOpenGl`) is unaffected. Rebuilding against **7.9.3** (`scripts/build-occt-793-wasm.ps1`) restores correct shading. Workarounds in EzyCad (`SetMaterial` + `Redisplay`, `refresh_shape_shading_`) do not fix the root cause on OCCT 8. Use 7.9.3 for wasm builds and demo publishing until upstream fixes GLES presentation.

docs/building-occt.md

@@ -140,7 +140,7 @@ FreeType wasm configure also disables optional zlib/png/harfbuzz finds to simpli
 | `emcc` not found | Run `emsdk_env.bat` / `emsdk_env.ps1` in the same shell |
 | EzyCad configure hangs on `find_package(OpenCASCADE)` | `emcmake cmake ... --debug-output`; verify `OpenCASCADE_DIR` path |
 | OCCT 8 + ghosted dimension labels | Retest `gui.edge_dim_text_render_mode` (Z-layer Topmost); grid compositing changed in 8.0 |
-| Shaded faces missing / wireframe-only solids (wasm, OCCT 8.x) | Use **7.9.3** (`build-occt-793-wasm.ps1`); see [bugs.md](bugs.md). Bisect toggles in `src/occt_view_wasm_bisect.h` do not fix the OCCT 8 GLES regression |
+| Shaded faces missing / wireframe-only solids (wasm, OCCT 8.x) | Use **7.9.3** (`build-occt-793-wasm.ps1`); see [bugs.md](bugs.md) |
 
 ---