docs: restructure README and correct unshipped commands

[shuvonsec]

Restructures the README around what a new reader needs first: what AXguard is, how to install it, and what its output actually looks like. 819 lines → 595, with more information in it, not less.

Why

The README grew by accretion — each feature added a section. The result buried the basics:

• The author bio ran from line 11 to 42. The first runnable command was line 51; Quick Start was line 154.
• Four sections restated "AI builds → AXguard checks → you ship" with four different ASCII diagrams.
• Two command tables (42 rows and 33 rows) largely duplicated each other.
• ~120 commands were listed and no output was shown anywhere — no finding, no severity line, no report sample.

The important fix: two commands that do not exist

axguard preship and axguard diff are documented on main but are not registered in cli/main.py. There is no parser, no dispatch branch, and no engines/security_diff/. Both live on feat/axguard-preship and feat/axguard-security-diff, which have not merged.

This mattered because axguard preship . was the second section of the README and its flagship example. Anyone following along hit command not found.

The real top-level CLI is 22 commands: about adversary api audit contribute data engage evidence flow github help investigate memory mcp paths (alias attack-paths) predict privacy scan surface twin verify version.

Both are removed here. Pre-ship review is now documented as what actually ships — the axguard-preship and axguard-cso skills over axguard audit. They can go back in the README when their branches land.

This also removes the links to docs/preship.md and docs/security-diff.md, which were referenced three times and do not exist. They were the only two broken relative links in the file.

Smaller accuracy fixes

• --format {text,json,md,html} is documented as scan-only. audit has no --format and always writes all three.
• --fail-on is documented as scan/audit-only. surface, flow, verify, adversary, evidence and paths always return 0 and cannot gate CI — the old CI section implied otherwise.
• The GitHub bot section no longer reads as though a CLI command serves the webhook. axguard github is setup|validate|test|status; running the listener is a self-hosting step.
• Phase numbering is dropped from the prose. Phases 1–6 and 9 exist in code; 7 and 8 do not, so a "1 through 9" narrative was misleading.
• Detection scale is stated plainly: 47 rules across 16 JSON packs plus five hunters, with everything downstream described as post-processing.

New sections

• See it work — real captured output from axguard scan fixtures/vuln_app and axguard audit fixtures/vuln_app, including the severity table from the generated report. Nothing hand-written; it is what the commands print. It also shows VERIFIED=0 UNVERIFIED=12 rather than hiding it.
• Supported languages — Python and JS/TS primary, PHP/Java/Ruby/Go/Rust/Vue secondary, config and IaC. Never stated anywhere before.
• Privacy — promoted from a code comment to its own section. No telemetry, no account, no LLM calls in the analysis path. This is one of the strongest things about the tool and it was invisible.
• Troubleshooting — six real failure modes.
• Uninstall — uninstall.sh existed and was chmod +x'd in Quick Start but never explained.
• Docs index — rebuilt. 26 of 55 docs were unlinked, including mcp-threat-model.md, github/security.md and github/troubleshooting.md.

The author bio, contributions image and AwareXone section move to a Credits section at the bottom. All badges, images and contact details are kept.

Verification

• All relative links resolve; zero broken. Verified with a sweep over every ](path) in the file.
• All three referenced assets/ images resolve.
• Every /axguard-* command in the README has a file in commands/.
• Every axguard <cmd> in the README is checked against the parser; no unknown commands.
• python scripts/validate_skills.py → skills scanned: 38 OK.
• axguard version, axguard help and axguard scan fixtures/vuln_app all run clean.
• No secret-shaped strings in the transcript, for gitleaks.

Only README.md changes.

Follow-ups (not in this PR)

• Version drift, four values: pyproject.toml 0.2.0, .claude-plugin/plugin.json 0.1.0, skills/index.yaml 0.3.0-dev, and the ASCII banner prints v0.1.
• uninstall.sh is incomplete — its hardcoded arrays omit the axguard-security skill and the axguard-contribute.md / axguard-privacy.md commands, so those are left behind.
• CLAUDE.md lists /axguard-diff, which has no command file — same class of error as the one fixed here.
• docs/preship.md and docs/security-diff.md should be written when those features merge.
• No link-checking in CI. Seven workflows and none lints markdown or links, which is why the dead links survived.