docs: add Claude Code troubleshooting workarounds

docs/TROUBLESHOOTING.md

@@ -0,0 +1,74 @@
+# Troubleshooting
+
+Community-reported workarounds for current Claude Code bugs that can affect ECC users.
+
+These are upstream Claude Code behaviors, not ECC bugs. The entries below summarize the production-tested workarounds collected in [issue #644](https://github.com/affaan-m/everything-claude-code/issues/644) on Claude Code `v2.1.79` (macOS, heavy hook usage, MCP connectors enabled). Treat them as pragmatic stopgaps until upstream fixes land.
+
+## Community Workarounds For Open Claude Code Bugs
+
+### False "Hook Error" labels on otherwise successful hooks
+
+**Symptoms:** Hook runs successfully, but Claude Code still shows `Hook Error` in the transcript.
+
+**What helps:**
+
+- Consume stdin at the start of the hook (`input=$(cat)` in shell hooks) so the parent process does not see an unconsumed pipe.
+- For simple allow/block hooks, send human-readable diagnostics to stderr and keep stdout quiet unless your hook implementation explicitly requires structured stdout.
+- Redirect noisy child-process stderr when it is not actionable.
+- Use the correct exit codes: `0` allows, `2` blocks, other non-zero exits are treated as errors.
+
+**Example:**
+
+```bash
+# Good: block with stderr message and exit 2
+input=$(cat)
+echo "[BLOCKED] Reason here" >&2
+exit 2
+```
+
+### Earlier-than-expected compaction with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`
+
+**Symptoms:** Lowering `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` causes compaction to happen sooner, not later.
+
+**What helps:**
+
+- On some current Claude Code builds, lower values may reduce the compaction threshold instead of extending it.
+- If you want more working room, remove `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` and prefer manual `/compact` at logical task boundaries.
+- Use ECC's `strategic-compact` guidance instead of forcing a lower auto-compact threshold.
+
+### MCP connectors look connected but fail after compaction
+
+**Symptoms:** Gmail or Google Drive MCP tools fail after compaction even though the connector still looks authenticated in the UI.
+
+**What helps:**
+
+- Toggle the affected connector off and back on after compaction.
+- If your Claude Code build supports it, add a `PostCompact` reminder hook that warns you to re-check connector auth after compaction.
+- Treat this as an auth-state recovery step, not a permanent fix.
+
+### Hook edits do not hot-reload
+
+**Symptoms:** Changes to `settings.json` hooks do not take effect until the session is restarted.
+
+**What helps:**
+
+- Restart the Claude Code session after changing hooks.
+- Advanced users sometimes script a local `/reload` command around `kill -HUP $PPID`, but ECC does not ship that because it is shell-dependent and not universally reliable.
+
+### Repeated `529 Overloaded` responses
+
+**Symptoms:** Claude Code starts failing under high hook/tool/context pressure.
+
+**What helps:**
+
+- Reduce tool-definition pressure with `ENABLE_TOOL_SEARCH=auto:5` if your setup supports it.
+- Lower `MAX_THINKING_TOKENS` for routine work.
+- Route subagent work to a cheaper model such as `CLAUDE_CODE_SUBAGENT_MODEL=haiku` if your setup exposes that knob.
+- Disable unused MCP servers per project.
+- Compact manually at natural breakpoints instead of waiting for auto-compaction.
+
+## Related ECC Docs
+
+- [hooks/README.md](../hooks/README.md) for ECC's documented hook lifecycle and exit-code behavior.
+- [token-optimization.md](./token-optimization.md) for cost and context management settings.
+- [issue #644](https://github.com/affaan-m/everything-claude-code/issues/644) for the original report and tested environment.

docs/token-optimization.md

@@ -17,7 +17,6 @@ Add to your `~/.claude/settings.json`:
   "model": "sonnet",
   "env": {
     "MAX_THINKING_TOKENS": "10000",
-    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
     "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
   }
 }
@@ -29,9 +28,12 @@ Add to your `~/.claude/settings.json`:
 |---------|---------|-------------|--------|
 | `model` | opus | **sonnet** | Sonnet handles ~80% of coding tasks well. Switch to Opus with `/model opus` for complex reasoning. ~60% cost reduction. |
 | `MAX_THINKING_TOKENS` | 31,999 | **10,000** | Extended thinking reserves up to 31,999 output tokens per request for internal reasoning. Reducing this cuts hidden cost by ~70%. Set to `0` to disable for trivial tasks. |
-| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 95 | **50** | Auto-compaction triggers when context reaches this % of capacity. Default 95% is too late — quality degrades before that. Compacting at 50% keeps sessions healthier. |
 | `CLAUDE_CODE_SUBAGENT_MODEL` | _(inherits main)_ | **haiku** | Subagents (Task tool) run on this model. Haiku is ~80% cheaper and sufficient for exploration, file reading, and test running. |
 
+### Community note on auto-compaction overrides
+
+Some recent Claude Code builds have community reports that `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` can only lower the compaction threshold, which means values below the default may compact earlier instead of later. If that happens in your setup, remove the override and rely on manual `/compact` plus ECC's `strategic-compact` guidance. See [Troubleshooting](./TROUBLESHOOTING.md).
+
 ### Toggling extended thinking
 
 - **Alt+T** (Windows/Linux) or **Option+T** (macOS) — toggle on/off
@@ -130,7 +132,6 @@ The `configure-ecc` install wizard could offer to set these environment variable
 
 # Environment variables (add to ~/.claude/settings.json "env" block)
 MAX_THINKING_TOKENS=10000
-CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=50
 CLAUDE_CODE_SUBAGENT_MODEL=haiku
 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
 ```