AGENTS.md.example: advertise the jerboa MCP server and tools
ober
972e9b8274101ec3c60e8fe7a4fcf48a0aa59720
--- a/AGENTS.md.example +++ b/AGENTS.md.example @@ -14,6 +14,45 @@ Never write raw Chez `.sls` files with `#!chezscheme` + R6RS application logic in another language (shell, Python, Rust, etc.) — that bypasses Jerboa entirely and defeats the purpose of these repos. +## Jerboa MCP server — USE IT + +You have a **`jerboa` MCP server** connected. Do not guess at Jerboa syntax, +module paths, or function signatures from memory — Jerboa is not a public +language, so your training data is unreliable here. **Look it up and verify +with the tools instead.** Re-check after every edit. + +Core tools (call them by these names): + +| Tool | Use it to | +|------|-----------| +| `jerboa_compile_check` | Compile a file or snippet and see real errors. **Run after every edit.** Pass `file_path` + `project_path` (repo root). | +| `jerboa_run_tests` | Run a test file/suite. Pass `file_path` + `project_path`. | +| `jerboa_eval` | Evaluate an expression to check behavior before wiring it in. | +| `jerboa_check_syntax` | Fast syntax-only check (no full compile). | +| `jerboa_make` | Build via the project's build setup. | +| `jerboa_apropos` | **Search for symbols/procedures by keyword** when you don't know the name. | +| `jerboa_module_exports` | List everything a `(std …)` module exports. | +| `jerboa_module_exists` | Confirm a module path before importing it. | +| `jerboa_function_signature` | Get a procedure's exact arity/signature. | +| `jerboa_howto` / `jerboa_howto_get` | Search and read cookbook recipes for common patterns. | +| `jerboa_verify` | Run the project's verification/checks. | +| `jerboa_security_scan` / `jerboa_security_profile` | Audit code for unsafe patterns. | + +### Finding additional tools + +The list above is the common set; the server exposes more. To discover them: + +- Call the **`jerboa` dispatcher** with `{"tool": "list"}` to enumerate every + available tool, and `{"tool": "describe", "args": {"name": "<tool>"}}` to get + one tool's arguments. Write tools (e.g. `howto_add`, `suggest_feature`) live + behind this dispatcher — call them as `{"tool": "<name>", "args": {…}}`. +- Use `jerboa_apropos` to find the right procedure when you only know what it + should *do*, and `jerboa_module_exports` to see what a module offers. + +**Workflow:** look up the API (`apropos` / `module_exports` / `function_signature`) +→ write Jerboa → `jerboa_compile_check` → fix → `jerboa_run_tests`. Don't +brute-force compile-fail loops when a one-line lookup answers the question. + ## Build Contract The Makefile must provide these targets: