docs: refresh root README around the three Stack pillars

[coderdan]

What

A conversion-focused rewrite of the root README.md, benchmarked against 8 company-backed, high-star OSS READMEs (Supabase, Clerk, Infisical, Vault, Trigger.dev, Prisma, Drizzle, React Email).

The README now:

• Leads with the differentiator — searchable encryption ("search encrypted data without decrypting it") plus a zero-knowledge trust line, instead of a single-bullet "What is the stack?".
• Account-first quick start — step 1 is create a free account, then npx stash init, then a snippet that shows encrypt → search without decrypting → decrypt.
• Covers all three pillars early: 🔐 searchable encryption, 🔗 ORM & database integrations (Supabase / Drizzle / Prisma Next / DynamoDB, as a status matrix), 👤 identity-aware encryption.
• Adds a "How it works" trust section linking the security architecture docs — the trust signal the security-category leaders leave out of their READMEs.
• Reference-style links — all URLs are centralised at the bottom of the file; CipherStash links carry ?utm_source=github&utm_medium=stack_readme for attribution.

Also in this PR:

• Marks @cipherstash/protect (Protect.js) as legacy with a warning banner at the top of its README.
• docs/plans/readme-visual-assets.md — specs for two net-new assets (architecture diagram + type-safety autocomplete GIF), including a ship-today Mermaid version of the diagram.

Auth section — now reflects #497 (OidcFederationStrategy)

The identity-aware encryption pillar has been updated to the new strategy-based API from #497: client-level OidcFederationStrategy (config.strategy, re-exported from @cipherstash/stack) + .withLockContext({ identityClaim }), replacing the deprecated new LockContext() → identify() → .withLockContext(lc) ceremony. This makes every OIDC provider (Clerk, Supabase, Auth0, Okta) first-class. The snippet mirrors #497's own documented example (OidcFederationStrategy.create(workspaceCrn, () => getUserJwt())).

Merge ordering: this depends on #497 (and the @cipherstash/auth release that ships OidcFederationStrategy + the strategy re-exports). Merge/release #497 first, then this. Please re-confirm the OidcFederationStrategy.create(...) signature against the finally-published @cipherstash/auth version before merge — #497 notes the workspaceCrn single-arg form lands in auth 0.40.

Other follow-ups

• npm deprecate @cipherstash/protect — being handled separately (npm not authed in the build env).
• Produce the two visual assets per docs/plans/readme-visual-assets.md.
• Rebase onto main once feat(stack): protect-ffi 0.26.0 + auth 0.39 OidcFederationStrategy (stacked on #496) #497 merges (this PR rewrote the whole README, so expect to resolve a README.md conflict in favour of this branch).

Notes for reviewers

• Render the README on the branch to check the badge row, tables, and reference links resolve.
• Confirm the UTM scope (currently on all cipherstash.com links) matches what analytics expects — easy to dial back since they're all in one block.
• Image assets aren't included yet; the diagram/GIF slots are described in the spec doc, not embedded.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 20e13ae

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 01ee567e-fef1-4ec7-94a6-0d631acfc229

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/readme-refresh

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}