docs: reorganize both READMEs around a Quick Start, add ecosystem diagram

[bacsystem]

Summary

Both READMEs had grown as an organic history of incremental additions (Cursor section, Gemini CLI section, demo section, bug-reporting section, all appended over the session) rather than a clear path for a new user finding this repo cold. Requested reorganization: proper table of contents, a real Quick Start, and clearer separation between "using cys" (most users) and "building from source" (contributors/advanced).

New structure (both languages, kept in exact parallel):

1. What is cys? (plugin + engine, skill table, embedded Mermaid ecosystem diagram)
2. See it in action (60 seconds) — unchanged, kept as the hook
3. Quick Start (new) — plugin install → /cys:flow → done
4. Installing the cys plugin (Claude Code / Cursor / Gemini CLI, detailed)
5. One-time permissions setup (merges)
6. Using cys — step-by-step guide, manual invocation reference, /run-plan, Handoff phase, branch topology
7. Building from source (for contributors / advanced engine use)
8. How it works
9. Safety checks & known limitations
10. Reporting bugs & contributing (now links CONTRIBUTING.md)

Real finding surfaced along the way: verified via commands/flow.md's CLAUDE_PLUGIN_ROOT resolution and marketplace.json's source: "./" that installing the cys plugin via the marketplace already materializes a ready-to-run, pre-built copy of this repo — no manual clone/npm run build needed for a typical first run. The old README put the clone-and-build section ahead of any usage content, reading as a requirement it isn't. This reorg makes that explicit and moves "Building from source" to a clearly-labeled contributor/advanced section.

Also embedded docs/diagram/flujo-cys-ecosystem.mmd directly as a rendered Mermaid diagram (GitHub renders it natively) in both READMEs instead of only linking the file, and fixed examples/README.md's now-stale #usage anchor (renamed to #using-cys).

No content was dropped — every existing caveat, permissions note, and known limitation survived the reorg verbatim, just regrouped. Verified all TOC and in-body cross-reference anchor links resolve to real headings (28-29 links checked per file, zero mismatches).

Version

0.6.18 → 0.6.19 (patch, pre-1.0 docs rule)

Test plan

• npm test — 153/153 pass (no test references README content directly)
• Verified all TOC + in-body #anchor links resolve against actual heading slugs in both files (script-checked, zero mismatches)
• Grepped the repo for other files referencing old README anchors (#usage, #installation, #requirements) — found and fixed one live reference in examples/README.md

https://claude.ai/code/session_0145sjAtP5b5kvhR1XCgg3K3