docs(proxy): correct --code-aware default to disabled (#1710)

## Description

The wiki proxy page (`wiki/proxy.md`, which feeds the published docs
site) claimed `--code-aware` defaults to **true**. The CLI deliberately
defaults it to **disabled**: `headroom/cli/proxy.py` resolves the paired
flag to off unless `--code-aware` is passed or
`HEADROOM_CODE_AWARE_ENABLED` is truthy, and the Click help text plus
`docs/content/docs/proxy.mdx` and `wiki/cli.md` already document it as
disabled. This PR aligns the one remaining stale table row and collapses
the self-contradictory separate `--no-code-aware` row into a single
paired-flag entry, matching the style used in
`docs/content/docs/proxy.mdx`.

Fixes #1700

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- `wiki/proxy.md`: replaced the two flag-table rows claiming
`--code-aware` default `true` / `--no-code-aware` default `false` with
one `--code-aware` / `--no-code-aware` row documenting the actual
default (`disabled`), the `headroom-ai[code]` requirement, and the
`HEADROOM_CODE_AWARE_ENABLED=1` env opt-in.

## Testing

- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ python -c "
from click.testing import CliRunner
from headroom.cli.proxy import proxy
r = CliRunner().invoke(proxy, ['--help'])
print([l.strip() for l in r.output.splitlines() if 'code-aware' in l][0])
"
--code-aware / --no-code-aware  Enable/disable AST-based code compression.

$ grep -n "code-aware" wiki/proxy.md
77:| `--code-aware` / `--no-code-aware` | disabled | Enable or disable AST-based code compression. Requires `headroom-ai[code]` (env: HEADROOM_CODE_AWARE_ENABLED=1 to enable) |
```

## Real Behavior Proof

- Environment: Windows 11, local checkout at `upstream/main` (9fbd47ba),
Python 3.13.
- Exact command / steps: `headroom proxy --help` (via Click test runner)
to confirm the CLI help says "Default: disabled"; inspected
`headroom/cli/proxy.py` flag resolution (explicit flag →
`HEADROOM_CODE_AWARE_ENABLED` → off); `grep -rn "code.aware" wiki/
docs/` to find every doc stating a default.
- Observed result: CLI default is disabled;
`docs/content/docs/proxy.mdx:61` and `wiki/cli.md:255-256` already say
disabled/off; only `wiki/proxy.md:77-78` claimed true. After the change
the table matches actual behavior.
- Not tested: rendered docs-site build (content-only table edit).

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Parideboy 2026-07-02 23:19:12 +02:00 committed by GitHub
parent 9fbd47ba6b
commit 1fc5e3d4da
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -74,8 +74,7 @@ When configured, Headroom emits OTLP traces for the shared compression pipeline
| `--no-rate-limit` | `false` | Disable rate limiting |
| `--log-file` | None | Path to JSONL log file |
| `--budget` | None | Daily budget limit in USD |
| `--code-aware` | true | Enable AST-based code compression (env: HEADROOM_CODE_AWARE_ENABLED) |
| `--no-code-aware` | false | Disable code-aware compression |
| `--code-aware` / `--no-code-aware` | disabled | Enable or disable AST-based code compression. Requires `headroom-ai[code]` (env: HEADROOM_CODE_AWARE_ENABLED=1 to enable) |
| `--anthropic-api-url` | `https://api.anthropic.com` | Custom Anthropic API URL endpoint |
| `--openai-api-url` | `https://api.openai.com` | Custom OpenAI API URL endpoint |