docs(plugin): add claude_smart package code map

[yyiilluu]

What

Add plugin/src/README.md — a code map for the claude_smart Python package: the hook dispatcher, the six lifecycle event handlers (events/), session buffering/publish flow, the Reflexio adapter, and supporting modules.

Why

The claude_smart package had no code map; an agent navigating plugin/src/ had to read source to understand the hook → buffer → publish → inject flow. The new README documents that flow, the dual-host (Claude Code / Codex) model, and the external state locations (~/.claude-smart/, ~/.reflexio/). It points to the existing user-facing plugin/README.md for install/usage and does not duplicate it.

Scope

Documentation only — no code or behavior changes.

Summary by CodeRabbit

• Documentation
  • Comprehensive package documentation update including full architecture overview and runtime behavior guide. Documents main entry points, event handlers, supporting modules, and key operational constraints such as configuration storage paths, default service ports, performance requirements, and read-only mode support.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d6b57be7-bdb5-498e-880a-88ced534fe21

📥 Commits

Reviewing files that changed from the base of the PR and between 4a04568 and fb15d5f.

📒 Files selected for processing (1)

• plugin/src/README.md

---

📝 Walkthrough

Walkthrough

This PR replaces plugin/src/README.md with a comprehensive package documentation describing the claude_smart Python plugin structure, including entry points, event handler flows, supporting modules, and core runtime constraints and architecture.

Changes

Package Documentation

Layer / File(s)	Summary
Package code map and operational overview plugin/src/README.md	New README documents the claude_smart package structure including entry points (hook.py, cli.py, state.py, publish.py, reflexio_adapter.py), event handlers (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd), supporting modules, and operational constraints (externalized state paths, localhost ports, read-only mode, handler performance).

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

📖 A doc blooms bright in the markdown soil,
Mapping the pathways of claude_smart's toil,
From hook to handler, from start to the end,
A code map to guide every future friend! 🐰✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

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

---

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 and usage tips.}