readme-restructurelisted

<!-- Author: jamestexas — drafted by claude-opus-4-7 (2026-05-16) --> # /readme-restructure — README Information Architecture Restructure a README so the value prop and audience signal land before any internals. This skill **does not rewrite content** — it re-orders sections and pushes dense detail behind `<details>` or into separate docs. ## Arguments `$ARGUMENTS` - **`<path-to-README.md>`** — the file to restructure. Defaults to `README.md` in the current working directory. - **`--dry-run`** *(default)* — produce a structure diff and a written restructure plan; do not write. - **`--apply`** — after approval, rewrite the file in place. The original is preserved as `README.md.bak`. - **`--target`** *(default: `both`)* — optimize for `human`, `llm`, or `both`. Affects ordering heuristics: humans skim, LLMs read top-down. ## What this solves A README's job is to land three signals in the first 200 tokens: 1. **What is this?** (category noun + defining trait) 2. **Who is it for?** (audience) 3. **How do I try it in 30 seconds?** (quick-start or one-line install) The user's `mache/README.md` is the motivating example. Its first 1000 chars are good — until paragraph 4: > *"Seventeen MCP tools wrap the projected graph (sixteen read-surface plus `write_file`). Fourteen work standalone; three (`semantic_search`, `get_type_info`, `get_diagnostics`) require ley-line-open enrichment. `find_smells` covers nine structural code-smell rules (`dead_code`, `cyclomatic_complexity`, `