add per-folder readmes with diagrams, file tables, and cross-links

[AnkanMisra]

Summary

Adds a README.md to every meaningful folder so each one can be opened in isolation and tell the full story without bouncing back to the root. 12 new files, all tables-and-diagrams style, all cross-linked.

What got covered

Folder	Headline
src/	Server overview + Mermaid request flow + hard rules
src/core/	Types, schemas, engine — full Mermaid of the 5-rule ladder
src/memory/	Store interface + InMemoryStore + ZeroGStore — Mermaid of the soft-failure anchor flow
src/simulator/	HeuristicSimulator — selector-decode flow + heuristic-vs-fork comparison table
src/playbooks/	KeeperHubRunner + WebhookChannel — remediation Mermaid
src/transport/	AxlGossipTransport + NoopGossip — gossip Mermaid + soft-failure contract table
src/risk-gate/	Fastify app + composition root — full env -> adapter table + route Mermaid
src/cli/	Demo runner — four canonical scenes table
tests/	109-spec index + patterns-to-mirror table
docs/	Doc index + reading order Mermaid
docs/sponsors/	Sponsor research index + prize matrix table
scripts/	dev.sh + kh.sh subcommand reference

Test plan

• bun test (109 / 109 pass)
• bun run typecheck:server (zero errors)
• Emoji scan over all new READMEs (no banned bytes)
• Every file path linked from a new README exists on main
• No source code touched

Notes

Pure docs PR. The root README.md is intentionally untouched — kept the user's preferred shape.

---

^{Need help on this PR? Tag @codesmith with what you need.}

• Let Codesmith autofix CI failures and bot reviews

Summary by CodeRabbit

• Documentation
  • Added comprehensive documentation across the project including server architecture, core decision logic, storage layer, remediation workflows, P2P networking, CLI tools, and testing infrastructure.
  • Created a documentation hub and sponsor research index for easier navigation.

[cloudflare-workers-and-pages]

Deploying chainshield with    Cloudflare Pages

Latest commit:	48c5c23
Status:	✅  Deploy successful!
Preview URL:	https://dec04166.chainshield.pages.dev
Branch Preview URL:	https://docs-per-folder-readmes.chainshield.pages.dev

View logs

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR adds comprehensive README documentation across eleven key directories, establishing a hierarchical documentation structure that guides readers through the ChainShield project's architecture, modules, patterns, and operational guides.

Changes

Documentation Hub Initiative

Layer / File(s)	Summary
Documentation Index docs/README.md	Top-level documentation hub with audience-based table, suggested reading order flowchart, conventions (relative links, no emojis, CI scanning), and pointers to all major sections.
Sponsor & Operational Guides docs/sponsors/README.md, scripts/README.md	Sponsor research index mapping notes to adapters with prize matrix; scripts documentation covering dev.sh and kh.sh wrapper usage and conventions.
Core Architecture READMEs src/README.md, src/core/README.md, src/memory/README.md	Server overview with request flow diagram and hard rules; core module decision ladder with invariants; store layer architecture covering pluggable persistence and soft-failure contracts.
Feature Subsystem READMEs src/cli/README.md, src/playbooks/README.md, src/risk-gate/README.md, src/simulator/README.md, src/transport/README.md	CLI demo runner documentation; remediation + notification subsystem with hard rules; risk-gate service composition and routing with anchor injection; ERC-20 calldata simulator; peer-to-peer gossip transport for decision broadcasting.
Test Coverage Documentation tests/README.md	Test overview with spec count, execution commands, file index mapping tests to covered domains, shared patterns (mock injection, pinned hashes, fresh stores, deterministic time), and CI gates.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A warren of docs, so neat and aligned,
Each module a burrow, each flow well-designed,
From hub down to leaflets, the path becomes clear,
Now readers won't hop in the dark—cheers, my dear! 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main change: adding per-folder README files with diagrams, file tables, and cross-links across 12 repository folders.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/per-folder-readmes

---

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

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

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