Update CLAUDE.md with all 31 sx-tree MCP tools

The tool table was listing only the original 11 tools. Now documents all 31
including smart editing, project-wide search, dev workflow, and git integration.
Also updated the protocol to mention pattern-based editing and sx_write_file.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -4,9 +4,7 @@ Cooperative web platform: federated content, commerce, events, and media process
 
 ## S-expression files — reading and editing protocol
 
-**Never use `str_replace` or `write_file` on `.sx` or `.sxc` files for structural edits.** These tools operate on text and have no understanding of tree structure. Bracket mismatches produced this way corrupt files silently — a single extra `)` caused the home page to go blank for an hour (25 March 2026).
-
-Use the `sx-tree` MCP server tools instead. These operate on the parsed tree, not raw text. Bracket errors are impossible by construction.
+**Never use `Edit`, `Read`, or `Write` on `.sx` or `.sxc` files.** A hook blocks these tools on `.sx`/`.sxc` files. Use the `sx-tree` MCP server tools instead — they operate on the parsed tree, not raw text. Bracket errors are impossible by construction.
 
 ### Before doing anything in an `.sx` file
 
@@ -14,42 +12,100 @@ Use the `sx-tree` MCP server tools instead. These operate on the parsed tree, no
 2. Call `sx_read_subtree` on the region you intend to work in
 3. Call `sx_get_context` on specific nodes to understand their position
 4. Call `sx_find_all` to locate definitions or patterns by name
+5. For project-wide searches, use `sx_find_across`, `sx_comp_list`, or `sx_comp_usage`
 
 **Never proceed to an edit without first establishing where you are in the tree using the comprehension tools.**
 
 ### For every s-expression edit
 
+**Path-based** (when you know the exact path):
 1. Call `sx_read_subtree` on the target region to confirm the correct path
 2. Call `sx_replace_node` / `sx_insert_child` / `sx_delete_node` / `sx_wrap_node`
 3. Call `sx_validate` to confirm structural integrity
 4. Call `sx_read_subtree` again on the edited region to verify the result
 
+**Pattern-based** (when you can describe what to find):
+- `sx_rename_symbol` — rename all occurrences of a symbol in a file
+- `sx_replace_by_pattern` — find + replace first/all nodes matching a pattern
+- `sx_insert_near` — insert before/after a pattern match (top-level)
+- `sx_rename_across` — rename a symbol across all `.sx` files (use `dry_run=true` first)
+
+### Creating new `.sx` files
+
+Use `sx_write_file` — it validates the source by parsing before writing. Malformed SX is rejected.
+
 ### On failure
 
 Read the error carefully. Fragment errors give the parse failure in the new source. Path errors tell you which segment was not found. Fix the specific problem and retry the tree edit. **Never fall back to raw file writes.**
 
-### When raw file access is acceptable
-
-- Searching for a string literal or reading prose content with `Read` is fine
-- Creating a **new** `.sx` file with `Write` is fine (there's no existing tree to corrupt)
-- Any question about structure, nesting, or tree position goes through the tree tools
-
 ### Available MCP tools (sx-tree server)
 
+**Comprehension:**
+
 | Tool | Purpose |
 |------|---------|
-| `sx_read_tree` | Full annotated tree with path labels |
+| `sx_read_tree` | Annotated tree — auto-summarises large files. Params: `focus` (expand matching subtrees), `max_depth`, `max_lines`/`offset` |
 | `sx_summarise` | Folded overview at configurable depth |
 | `sx_read_subtree` | Expand a specific subtree by path |
 | `sx_get_context` | Enclosing chain from root to target |
-| `sx_find_all` | Search by pattern, returns paths |
+| `sx_find_all` | Search by pattern in one file, returns paths |
 | `sx_get_siblings` | Siblings of a node with target marked |
 | `sx_validate` | Structural integrity checks |
+
+**Path-based editing:**
+
+| Tool | Purpose |
+|------|---------|
 | `sx_replace_node` | Replace node at path with new source |
 | `sx_insert_child` | Insert child at index in a list |
 | `sx_delete_node` | Remove node, siblings shift |
 | `sx_wrap_node` | Wrap in template with `_` placeholder |
 
+**Smart editing (pattern-based):**
+
+| Tool | Purpose |
+|------|---------|
+| `sx_rename_symbol` | Rename all occurrences of a symbol in a file |
+| `sx_replace_by_pattern` | Find + replace first/all nodes matching a pattern. `all=true` for all matches |
+| `sx_insert_near` | Insert before/after a pattern match (top-level). `position="before"` or `"after"` |
+| `sx_rename_across` | Rename symbol across all `.sx` files in a directory. `dry_run=true` to preview |
+
+**Project-wide:**
+
+| Tool | Purpose |
+|------|---------|
+| `sx_find_across` | Search pattern across all `.sx` files in a directory |
+| `sx_comp_list` | List all definitions (defcomp/defisland/defmacro/defpage/define) across files |
+| `sx_comp_usage` | Find all uses of a component/symbol across files |
+
+**Development:**
+
+| Tool | Purpose |
+|------|---------|
+| `sx_pretty_print` | Reformat an `.sx` file with indentation. Also used automatically by all edit tools |
+| `sx_write_file` | Create/overwrite `.sx` file with parse validation |
+| `sx_build` | Build JS bundle (`target="js"`) or OCaml binary (`target="ocaml"`) |
+| `sx_test` | Run test suite (`host="js"` or `"ocaml"`, `full=true` for extensions) |
+| `sx_format_check` | Lint: empty bindings, missing bodies, duplicate params |
+| `sx_macroexpand` | Evaluate expression with a file's macro definitions loaded |
+| `sx_eval` | REPL — evaluate SX expressions in the MCP server env |
+
+**Git integration:**
+
+| Tool | Purpose |
+|------|---------|
+| `sx_changed` | List `.sx` files changed since a ref with structural summaries |
+| `sx_diff_branch` | Structural diff of all `.sx` changes on branch vs base ref |
+| `sx_blame` | Git blame for `.sx` file, optionally focused on a tree path |
+
+**Analysis:**
+
+| Tool | Purpose |
+|------|---------|
+| `sx_diff` | Structural diff between two `.sx` files (ADDED/REMOVED/CHANGED) |
+| `sx_doc_gen` | Generate component docs from signatures across a directory |
+| `sx_playwright` | Run Playwright browser tests for the SX docs site |
+
 ## Deployment
 
 - **Do NOT push** until explicitly told to. Pushes reload code to dev automatically.