docs: rewrite README to modern standards with diagrams

[nejdetkadir]

Summary

• Rewrites the README from scratch to current open-source documentation standards: clear value proposition, quick start, accurate references, and deep links into the contractual docs/ directory for contributors and AI agents.
• Adds two mermaid diagrams: a sequence diagram of the full token lifecycle (sign in → authenticated requests → expiry → refresh → revoke) and a token state diagram (active/expired/revoked, including rotation reuse detection).
• Surfaces the security posture prominently: a production security checklist (header-only extraction, rotation, paranoid mode, rate limiting, extra_fields audit, log hygiene) replaces the buried recommendations section.

Changes

• README.md — full restructure:
  • Tagline, feature highlights, and a table of contents
  • How it works with mermaid sequence + state diagrams
  • Requirements table (Ruby >= 2.7, Rails >= 6.0, Devise >= 4.7.2, per the gemspec)
  • Quick start (install → generate → migrate → add :api → curl verification with example response)
  • Endpoints table with curl examples, noting the refresh token travels in the same Authorization slot
  • Protecting your own endpoints — helper table + example controller
  • Response payloads — success/error shapes with common error types, linking to the full catalog in docs/api-reference.md
  • Configuration — complete annotated defaults block (grouped and matching docs/configuration.md)
  • Security checklist, Devise module compatibility (trackable/lockable/confirmable), and Customization (response decorators, base-class swapping with examples, lifecycle hooks, custom services)
  • Documentation section indexing docs/
  • Trimmed development/contributing/license sections; contributing now points at the docs ground rules and known-issues backlog

Architecture Impact

• None — documentation only. No code, schema, or behavior changes. All described behavior was verified against docs/architecture.md, docs/api-reference.md, and docs/configuration.md.

Test Plan

• Verify mermaid diagrams render on GitHub
• Verify anchors in the table of contents and links into docs/ resolve

🤖 Generated with Claude Code