docs(claude): improve CLAUDE.md with mise, secrets.d, and cleanup

Add mise tool manager section to Architecture. Add secrets.d gotcha
documenting the auto-source pattern. Remove duplicated context-mode
boilerplate block (already in global CLAUDE.md). Unpin Yarn version.
This commit is contained in:
2026-03-20 04:38:35 +02:00
parent cff83e4738
commit c17b4d6a8b

View File

@@ -98,6 +98,13 @@ and most scripts in `local/bin/`.
- `dfm scripts` — run scripts from `scripts/` (discovered via `@description` tags)
- `dfm tests` — test visualization helpers
### mise — Unified Tool Manager
`config/mise/config.toml` manages language runtimes (Node LTS, Python 3,
Go latest, Rust stable) and CLI tools (fd, ripgrep, eza, neovim, delta,
zoxide, etc.). Activated via `eval "$(mise activate bash)"` in
`config/exports`. Run `mise install` after adding new tools.
### Submodules
External dependencies are git submodules (Dotbot, plugins,
@@ -148,6 +155,10 @@ SC2174 (mkdir -p -m), SC2016 (single-quote expressions).
and excluded from prettier (see `.prettierignore`).
- **Python**: Two scripts (`x-compare-versions.py`,
`x-git-largest-files.py`) linted by Ruff (config in `pyproject.toml`).
- **Fish secrets**: `config/fish/secrets.d/*.fish` files are auto-sourced
by `exports.fish`. Copy `github.fish.example``github.fish` for local
secrets. These files are gitignored; only `*.example` and `README.md`
are tracked.
## Claude Code Configuration
@@ -168,88 +179,4 @@ SC2174 (mkdir -p -m), SC2016 (single-quote expressions).
## Package Manager
Yarn (v4.12.0) is the package manager. Do not use npm.
# context-mode — MANDATORY routing rules
You have context-mode MCP tools available. These rules are NOT optional —
they protect your context window from flooding.
A single unrouted command can dump 56 KB into context and waste the entire session.
## BLOCKED commands — do NOT attempt these
### curl / wget — BLOCKED
Any Bash command containing `curl` or `wget` is intercepted and replaced with an error message. Do NOT retry.
Instead use:
- `ctx_fetch_and_index(url, source)` to fetch and index web pages
- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
### Inline HTTP — BLOCKED
Any Bash command containing `fetch('http`, `requests.get(`, `requests.post(`,
`http.get(`, or `http.request(` is intercepted and replaced with an error message.
Do NOT retry with Bash.
Instead use:
- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
### WebFetch — BLOCKED
WebFetch calls are denied entirely. The URL is extracted and you are told to use `ctx_fetch_and_index` instead.
Instead use:
- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content
## REDIRECTED tools — use sandbox equivalents
### Bash (>20 lines output)
Bash is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `yarn install`, `pip install`,
and other short-output commands.
For everything else, use:
- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
### Read (for analysis)
If you are reading a file to **Edit** it → Read is correct (Edit needs content in context).
If you are reading to **analyze, explore, or summarize**
use `ctx_execute_file(path, language, code)` instead.
Only your printed summary enters context. The raw file content stays in the sandbox.
### Grep (large results)
Grep results can flood context.
Use `ctx_execute(language: "shell", code: "grep ...")` to run searches in sandbox.
Only your printed summary enters context.
## Tool selection hierarchy
1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary tool.
Runs all commands, auto-indexes output, returns search results.
ONE call replaces 30+ individual calls.
2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])`
Query indexed content. Pass ALL questions as array in ONE call.
3. **PROCESSING**: `ctx_execute(language, code)` |
`ctx_execute_file(path, language, code)`
Sandbox execution. Only stdout enters context.
4. **WEB**: `ctx_fetch_and_index(url, source)` then
`ctx_search(queries)` — Fetch, chunk, index, query.
Raw HTML never enters context.
5. **INDEX**: `ctx_index(content, source)`
Store content in FTS5 knowledge base for later search.
## Subagent routing
When spawning subagents (Agent/Task tool), the routing block is automatically
injected into their prompt. Bash-type subagents are upgraded to general-purpose
so they have access to MCP tools.
You do NOT need to manually instruct subagents about context-mode.
## Output constraints
- Keep responses under 500 words.
- Write artifacts (code, configs, PRDs) to FILES — never return them
as inline text. Return only: file path + 1-line description.
- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later.
## ctx commands
| Command | Action |
|---------------|---------------------------------------------------------------------------------------|
| `ctx stats` | Call the `ctx_stats` MCP tool and display the full output verbatim |
| `ctx doctor` | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist |
| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |
Yarn (v4+) is the package manager. Do not use npm.