docs(plan): rewrite README and migration guide for agent-first transition

[Delqhi]

Scope

Rewrite the repo docs for the new machine-first layout.

Build requirements

• README for install, usage, exit codes, and migration
• compatibility guidance for existing skill consumers
• explicit mapping from old scripts/templates to new package modules
• examples of JSON outputs and safe agent loops

Acceptance criteria

• humans can still understand the repo purpose
• agents get the exact next-step contract
• migration path is obvious and low-risk