Comprehensive documentation update for HN launch

[waleedkadous]

Context

We're preparing for an HN submission of the Tour of CodevOS article. The README was just updated (#557), but the broader documentation needs a thorough review and refresh.

Scope

Audit and update ALL user-facing documentation in the repo. Key areas:

docs/ directory

• docs/faq.md — Review for accuracy, add any missing common questions
• docs/tips.md — Ensure tips reflect current CLI commands and workflows
• docs/why.md — Update the narrative with latest results and capabilities
• docs/releases/ — Ensure release notes are current

codev/resources/ (user-facing)

• codev/resources/cheatsheet.md — Verify all commands, concepts, and examples are current
• codev/resources/commands/overview.md — CLI command reference accuracy
• codev/resources/commands/codev.md — codev CLI reference
• codev/resources/commands/agent-farm.md — af CLI reference
• codev/resources/commands/consult.md — consult CLI reference

Key reference material to incorporate

• Tour of CodevOS: https://waleedk.medium.com/a-tour-of-codevos-1db0fe0e4516
• Latest VIBE vs SPIR comparison (R4): codev/resources/vibe-vs-spir-r4-comparison-2026-02.md
• Development analysis: codev/resources/development-analysis-2026-02-17.md
• Current version: Check packages/codev/package.json for latest version number

What to look for

• Stale command syntax or outdated CLI examples
• References to old features or removed functionality
• Missing documentation for recent features (porch checks, analytics, workspace scoping, etc.)
• Broken internal links
• Inconsistencies between docs and actual codebase
• Tone: professional, concise, technically credible (HN audience)

AGENTS.md / CLAUDE.md

• Verify these are in sync with each other and with current project state