supex: Instructions file for Codex

AGENTS.md

Guidance for AI agents (Claude, Codex, Gemini, ...) when working on this repository.

CLAUDE.md is a symlink to this file for Claude Code compatibility.

Branch Strategy

• main: Stable releases only. Do not commit directly.
• dev: Active development. All work here.

Guidelines

• NEVER bump version numbers unless explicitly asked
• NEVER commit changes unless explicitly asked
• NEVER read git-ignored files unless explicitly asked
• NEVER use emojis in documentation
• NEVER include vcad/vendor/* submodule pointer changes in regular commits — use the commit-vendor skill instead. All vendored submodules track upstream main directly (no local patches); a pointer must be an upstream commit, otherwise the repo becomes uncloneable. Changes a vendored crate needs go upstream as a PR, never into a patch branch.
• Use git ls-tree -r HEAD to find project files
• Use portable shebangs - #!/usr/bin/env bash, #!/usr/bin/env python3, etc.

For AI Agents — Common Mistakes

# WRONG — git add includes vendor submodule pointer changes
git add -A && git commit -m "Add feature"

# CORRECT — exclude vendor, use commit-vendor skill for submodule changes
git add driver/ runtime/
git diff --cached --name-only | grep -v vcad/vendor/

# WRONG — debug build (SketchUp loads release binary)
cargo build --manifest-path vcad/sidecar/Cargo.toml

# CORRECT — always build release
cargo build --release --manifest-path vcad/sidecar/Cargo.toml

# WRONG — find/ls to discover project files (misses git-ignored state)
find . -name "*.rb"

# CORRECT — git ls-tree shows tracked files only
git ls-tree -r HEAD --name-only | grep '\.rb$'

Project Structure

supex/
├── .github/                   # GitHub Actions workflows and Dependabot config
├── driver/                    # Python MCP driver + CLI
│   └── src/supex_driver/
│       ├── cli/               # CLI commands
│       ├── connection/        # SketchUp socket connection
│       └── mcp/               # MCP server
├── runtime/                   # Ruby SketchUp extension
│   ├── ide_stubs/             # Shims so IDEs resolve sketchup.rb / extensions.rb
│   └── src/
│       ├── supex_runtime.rb   # Extension entry point
│       └── supex_runtime/     # Extension modules
├── stdlib/                    # Standard library (Ruby helpers)
├── mock/                      # Headless SketchUp API mock server (Ruby) for tests without SketchUp
├── vcad/                      # VCAD integration
│   ├── sidecar/               # Rust VCAD evaluator (BRep pipeline)
│   ├── viewer/                # Standalone Tauri geometry viewer
│   └── vendor/                # Git submodules (vcad, loon, tang)
│       ├── vcad/              # BRep CAD kernel
│       ├── loon/              # Loon language
│       └── tang/              # Differentiable computing (autodiff for VCAD)
├── tests/                     # E2E tests (pytest) and the Ruby snippets they execute
├── docs/                      # Documentation
│   ├── agents/                # Agent prompts (user projects symlink guide/ as supex-guide/)
│   └── contracts/             # JSON schemas and example payloads for the wire protocol
├── devtools/                  # Developer tools
│   ├── ci/                    # Dockerfile for the GitHub Actions test image
│   ├── docgen/                # SketchUp API doc generator (+ sketchup-api-stubs submodule)
│   └── radar/                 # Log aggregator / observability
├── assets/                    # README posters and the prompts that generated them
├── scripts/                   # Development scripts
├── examples/                  # Example projects (orphan branches)
├── justfile                   # just recipes: sketchup, test, test-e2e, docs, lint, clear-rust-caches
├── supex, mcp, repl           # Root wrappers: CLI, MCP server, REPL client
└── test, radar, vcad-sidecar  # Root wrappers: test runner, radar TUI, VCAD sidecar