LLM Context Manifest for ccgram

Purpose:
- Provide architecture and design context for AI agents before code changes.

Read this order:
1. docs/ai-agents/README.md
2. docs/ai-agents/architecture-map.md
3. docs/ai-agents/codebase-index.md
4. docs/ai-agents/tooling-and-tests.md
5. docs/ai-agents/extension-and-fix-playbook.md

Core architecture invariants:
- Topic-centric model: one Telegram topic maps to one tmux window.
- Internal identity is tmux window_id (for example @2), not window names.
- Per-window provider model: behavior/capabilities are resolved by window provider.
- Parsing keeps full content; message splitting happens only in Telegram send layer.
- tmux operations remain centralized in src/ccgram/tmux_manager.py.
- Live view auto-refreshes terminal screenshots; content-hash gating prevents unnecessary API calls.

Primary entrypoints:
- src/ccgram/main.py (bootstrap)
- src/ccgram/cli.py (CLI/env precedence)
- src/ccgram/bot.py (handler wiring and routing)
- src/ccgram/session.py (binding/state hub)
- src/ccgram/session_monitor.py (polling + outbound event flow)
- src/ccgram/providers/ (provider contract and implementations)
- src/ccgram/handlers/ (Telegram command/callback surface)
- src/ccgram/command_catalog.py (provider-agnostic command discovery + caching)
- src/ccgram/hook.py (Claude hook install/status/event writes)
- src/ccgram/handlers/live_view.py (terminal live view)
- src/ccgram/handlers/periodic_tasks.py (periodic task orchestration)
- src/ccgram/claude_task_state.py (Claude task tracking)
- src/ccgram/llm/summarizer.py (completion summaries)

State and data files:
- state.json: topic/thread bindings + window metadata
- session_map.json: tmux window -> provider session mappings
- events.jsonl: append-only hook events stream
- monitor_state.json: incremental read offsets
- mailbox/ : inter-agent message inboxes (per-window)

Canonical project references:
- README.md
- docs/guides.md
- CLAUDE.md
- .claude/rules/architecture.md
- .claude/rules/topic-architecture.md
- .claude/rules/message-handling.md
- docs/ai-agents/ (AI agent orientation pack)

Validation gate before done:
- make check (runs fmt + lint + typecheck + test)
- or individually: make fmt && make lint && make typecheck && make test

Provider-specific implementation pointers:
- src/ccgram/providers/base.py
- src/ccgram/providers/__init__.py
- src/ccgram/providers/claude.py
- src/ccgram/providers/codex.py
- src/ccgram/providers/gemini.py
