diff --git a/00_STATE.md b/00_STATE.md
new file mode 100644
index 0000000..1f8c342
--- /dev/null
+++ b/00_STATE.md
@@ -0,0 +1,103 @@
+# 00_STATE.md — AgentMail Toolkit Analysis
+
+## Repository Overview
+
+- **Fork**: `okwn/agentmail-toolkit` (forked from `agentmail-to/agentmail-toolkit`)
+- **Upstream**: `agentmail-to/agentmail-toolkit` — 71 stars, 22 forks, TypeScript, NOT archived
+- **License**: No license set (null) — **⚠️ CONCERN**
+- **Default branch**: main
+
+## Repository Structure
+
+```
+agentmail-toolkit/
+├── README.md                    # Root README (minimal, links to python/ node/)
+├── python/                      # Python package (v0.2.7)
+│   ├── pyproject.toml          # Hatch build, Python >=3.11
+│   ├── README.md
+│   ├── examples/
+│   │   ├── openai_.py
+│   │   ├── langchain_.py
+│   │   └── pyproject.toml
+│   └── src/agentmail_toolkit/
+│       ├── __init__.py         # Generic AgentMailToolkit base
+│       ├── toolkit.py          # Abstract Toolkit[T] base class
+│       ├── tools.py            # 11 Tool definitions (list_inboxes, get_inbox, etc.)
+│       ├── schemas.py          # Pydantic param schemas
+│       ├── functions.py        # Tool implementation functions
+│       ├── openai.py           # OpenAI Agents SDK adapter
+│       ├── langchain.py         # LangChain adapter
+│       ├── livekit.py          # LiveKit Agents adapter
+│       ├── util.py             # safe_func helper
+│       └── py.typed
+└── node/                        # Node.js package (v0.3.1)
+    ├── package.json            # pnpm, MIT license
+    ├── tsconfig.json
+    ├── pnpm-workspace.yaml
+    ├── pnpm-lock.yaml
+    ├── examples/
+    │   └── package.json
+    └── src/
+        ├── index.ts            # Default export (generic)
+        ├── tools.ts            # 18 Tool definitions (11 basic + 7 draft tools)
+        ├── toolkit.ts          # BaseToolkit, ListToolkit, MapToolkit
+        ├── schemas.ts          # Zod schemas
+        ├── functions.ts        # Tool implementations
+        ├── ai-sdk.ts          # Vercel AI SDK adapter
+        ├── mcp.ts             # Model Context Protocol adapter
+        ├── langchain.ts       # LangChain adapter
+        ├── clawdbot.ts        # Clawdbot adapter
+        └── util.ts            # safeFunc, file extraction helpers
+```
+
+## Key Findings
+
+### 1. Node package is more complete than Python
+- **Node**: 18 tools (11 basic + 7 draft tools: create/list/get/update/send/delete_draft)
+- **Python**: 11 tools (missing all draft tools)
+- **Version mismatch**: Node is 0.3.1, Python is 0.2.7
+
+### 2. No CI/CD workflows found
+- No `.github/workflows/` directory
+- No GitHub Actions configured
+- No test suite found
+
+### 3. License issue
+- Repository has `license: null` — **no open source license set**
+- This is a legal concern for contributing
+
+### 4. Open Issues (6)
+| # | Title |
+|---|-------|
+| 24 | chore: add repo description, homepage URL, and topics for GitHub discoverability |
+| 23 | docs: enhance README with framework matrix, comparison table, and quick start examples |
+| 18 | Improve root README — add framework table, quick start, badges |
+| 16 | Console landing page too heavy — particle effects cause lag |
+| 12 | x402 ecosystem partner: Fía Signals crypto intelligence API |
+| 11 | x402 ecosystem partner: Fía Signals crypto intelligence |
+
+### 5. Open Pull Requests (2)
+| # | Title | State |
+|---|-------|-------|
+| 23 | docs: enhance README with framework matrix... | open |
+| 18 | Improve root README — add framework table, quick start, badges | open |
+
+### 6. Upstream branches (9)
+- `main` (6dbb78b — v0.3.1)
+- `addDraftTools` — draft tools feature branch
+- `deletionFix` — MCP undefined result fix
+- `harry/fix-langchain-dts` — merged (fix-langchain-dts)
+- `improve-readme*` (4 variants) — all stale/closed
+- `mcp` — MCP protocol branch
+- `jarvis/improve-readme` — stale
+
+### 7. Quality Issues
+- Python: `get_attachment` in `functions.py` uses incorrect client method: `client.threads.get_attachment()` but should be `client.inboxes.threads.get_attachment()`
+- Both packages have error handling via `safe_func` patterns
+- No test coverage
+- README is very sparse
+
+### 8. Dependencies
+**Python**: agentmail>=0.4.10, openai-agents>=0.6.1, langchain>=1.1.0, livekit-agents>=1.3.5, pydantic>=2.12.5, pymupdf, python-docx, filetype
+
+**Node**: agentmail@^0.4.10, jszip@^3.10.1, unpdf@^1.4.0, zod@^4.1.13 (peerDeps: @modelcontextprotocol/sdk, ai, langchain, clawdbot)
\ No newline at end of file
diff --git a/01_REPO_MAP.md b/01_REPO_MAP.md
new file mode 100644
index 0000000..f512d8a
--- /dev/null
+++ b/01_REPO_MAP.md
@@ -0,0 +1,145 @@
+# 01_REPO_MAP.md — AgentMail Toolkit Repository Map
+
+## File Structure
+
+### Root
+| File | Purpose |
+|------|---------|
+| `README.md` | Minimal root README linking to `python/` and `node/` |
+| `.gitignore` | Ignores `node_modules`, `dist`, `build`, `*.egg-info`, `__pycache__` |
+
+### Python (`python/`)
+| File | Purpose |
+|------|---------|
+| `pyproject.toml` | Package config: v0.2.7, Python >=3.11, hatch build |
+| `README.md` | Python-specific README with pip install + usage example |
+| `uv.lock` | Lock file for uv |
+| `.gitignore` | Standard Python gitignore |
+| `examples/pyproject.toml` | Examples workspace |
+| `examples/openai_.py` | OpenAI agent example |
+| `examples/langchain_.py` | LangChain agent example |
+| `src/agentmail_toolkit/__init__.py` | Exports `AgentMailToolkit`, `Tool` |
+| `src/agentmail_toolkit/toolkit.py` | Abstract `Toolkit[T]` base class |
+| `src/agentmail_toolkit/tools.py` | 11 `Tool` definitions + `tools` list |
+| `src/agentmail_toolkit/schemas.py` | Pydantic parameter schemas |
+| `src/agentmail_toolkit/functions.py` | Tool implementation functions |
+| `src/agentmail_toolkit/openai.py` | OpenAI Agents SDK adapter |
+| `src/agentmail_toolkit/langchain.py` | LangChain adapter |
+| `src/agentmail_toolkit/livekit.py` | LiveKit Agents adapter |
+| `src/agentmail_toolkit/util.py` | `safe_func`, `ToolError` |
+| `src/agentmail_toolkit/py.typed` | PEP 561 typed marker |
+
+### Node (`node/`)
+| File | Purpose |
+|------|---------|
+| `package.json` | Package: v0.3.1, MIT license, pnpm |
+| `tsconfig.json` | TypeScript config |
+| `pnpm-workspace.yaml` | Workspace config |
+| `pnpm-lock.yaml` | Lock file |
+| `examples/package.json` | Examples workspace |
+| `src/index.ts` | Default `AgentMailToolkit` (generic) |
+| `src/tools.ts` | 18 `Tool` definitions (includes 7 drafts) |
+| `src/toolkit.ts` | `BaseToolkit`, `ListToolkit`, `MapToolkit` |
+| `src/schemas.ts` | Zod schemas for all params |
+| `src/functions.ts` | Tool implementations + draft functions |
+| `src/ai-sdk.ts` | Vercel AI SDK adapter (`MapToolkit`) |
+| `src/mcp.ts` | MCP (Model Context Protocol) adapter |
+| `src/langchain.ts` | LangChain adapter |
+| `src/clawdbot.ts` | Clawdbot adapter |
+| `src/util.ts` | `safeFunc`, `detectFileType`, PDF/DOCX extraction |
+
+## Tool Map
+
+### Python Tools (11)
+```
+list_inboxes       → list_inboxes()
+get_inbox          → get_inbox()
+create_inbox       → create_inbox()
+delete_inbox       → delete_inbox()
+list_threads       → list_threads()
+get_thread         → get_thread()
+get_attachment     → get_attachment()  ⚠️ BUG: wrong client path
+send_message       → send_message()
+reply_to_message   → reply_to_message()
+forward_message    → forward_message()
+update_message     → update_message()
+```
+
+### Node Tools (18) — superset of Python
+All Python tools PLUS:
+```
+create_draft       → createDraft()
+list_drafts        → listDrafts()
+get_draft          → getDraft()
+update_draft       → updateDraft()
+send_draft         → sendDraft()
+delete_draft       → deleteDraft()
+```
+
+## Framework Adapters
+
+### Python
+| Framework | File |
+|-----------|------|
+| Generic | `__init__.py` |
+| OpenAI Agents SDK | `openai.py` |
+| LangChain | `langchain.py` |
+| LiveKit | `livekit.py` |
+
+### Node
+| Framework | File | Toolkit Type |
+|-----------|------|--------------|
+| Generic | `index.ts` | `ListToolkit` |
+| Vercel AI SDK | `ai-sdk.ts` | `MapToolkit` |
+| MCP (Model Context Protocol) | `mcp.ts` | `ListToolkit` |
+| LangChain | `langchain.ts` | ? |
+| Clawdbot | `clawdbot.ts` | ? |
+
+## Schema Comparison
+
+| Operation | Python (Pydantic) | Node (Zod) |
+|-----------|-------------------|------------|
+| `inboxId` | `Annotated[str, Field]` | `z.string().describe()` |
+| `limit` | `int, default=10` | `z.number().optional().default(10)` |
+| `before/after` | `datetime` objects | `z.string().pipe(z.coerce.date())` |
+| `attachments` | `List[Attachment]` | `z.array(AttachmentSchema)` |
+| `replyAll` | `bool` | `replyAll: z.boolean()` |
+
+## Key Code Patterns
+
+### Python: Tool definition
+```python
+Tool(name="list_inboxes", description="List inboxes", params_schema=ListItemsParams, func=list_inboxes)
+```
+
+### Python: Toolkit base
+```python
+class Toolkit(Generic[T], ABC):
+    _tools: Dict[str, T] = None
+    def __init__(self, client: Optional[AgentMail] = None):
+        self.client = client or AgentMail()
+        self._tools = {tool.name: self._build_tool(tool) for tool in tools}
+    @abstractmethod
+    def _build_tool(self, tool: Tool) -> T: pass
+```
+
+### Node: Tool definition
+```typescript
+{name: 'list_inboxes', description: 'List inboxes', paramsSchema: ListItemsParams, func: listInboxes, annotations: {readOnlyHint: true, openWorldHint: false}}
+```
+
+### Node: Toolkit types
+```typescript
+// ListToolkit<T> — getTools() returns T[]
+// MapToolkit<T> — getTools() returns Record<string, T>
+```
+
+## Defects Identified
+
+1. **Python `get_attachment()` bug**: Uses `client.threads.get_attachment()` but should be `client.inboxes.threads.get_attachment()`
+2. **Python missing draft tools**: Node has 7 draft tools; Python has none
+3. **Version skew**: Node v0.3.1 vs Python v0.2.7
+4. **No license**: `license: null` in repo metadata
+5. **Sparse README**: Root README is very minimal
+6. **No tests**: No test files found
+7. **No CI**: No GitHub Actions workflows
\ No newline at end of file
diff --git a/05_PR_CANDIDATES.md b/05_PR_CANDIDATES.md
new file mode 100644
index 0000000..ccd93af
--- /dev/null
+++ b/05_PR_CANDIDATES.md
@@ -0,0 +1,67 @@
+# 05_PR_CANDIDATES.md — AgentMail Toolkit PR Candidates
+
+## Open Issues (6) — Potential PR Topics
+
+| # | Title | Labels | Priority | Effort |
+|---|-------|--------|----------|--------|
+| 24 | chore: add repo description, homepage URL, and topics for GitHub discoverability | chore | medium | low |
+| 23 | docs: enhance README with framework matrix, comparison table, and quick start examples | docs | high | medium |
+| 18 | Improve root README — add framework table, quick start, badges | docs | medium | low |
+| 16 | Console landing page too heavy — particle effects cause lag and hurt trust | bug? | low | unknown |
+| 12 | x402 ecosystem partner: Fía Signals crypto intelligence API (42 endpoints, pay-per-call) | partner | low | unknown |
+| 11 | x402 ecosystem partner: Fía Signals crypto intelligence (42 pay-per-call endpoints, USDC on Solana) | partner | low | unknown |
+
+## Open Pull Requests (2)
+
+| # | Title | Status | Reviewable |
+|---|-------|--------|------------|
+| 23 | docs: enhance README with framework matrix, comparison table, and quick start examples | open | yes |
+| 18 | Improve root README — add framework table, quick start, badges | open | yes |
+
+## Code Defects Found (From Code Review)
+
+### Bug: Python `get_attachment()` uses wrong client path
+**File**: `python/src/agentmail_toolkit/functions.py`, line 39
+**Issue**: Uses `client.threads.get_attachment()` but AgentMail SDK requires `client.inboxes.threads.get_attachment()`
+```python
+# CURRENT (buggy):
+attachment = client.threads.get_attachment(
+    thread_id=kwargs["thread_id"], attachment_id=kwargs["attachment_id"]
+)
+# SHOULD BE:
+attachment = client.inboxes.threads.get_attachment(
+    thread_id=kwargs["thread_id"], attachment_id=kwargs["attachment_id"]
+)
+```
+**Severity**: High — tool will crash when called
+
+### Missing Feature: Python lacks draft tools
+**Status**: Node has 7 draft tools (create/list/get/update/send/delete_draft + schedule support), Python has 0
+**Impact**: Feature parity gap between Node and Python SDKs
+**Effort**: Medium — requires adding 7 new tools and updating schemas
+
+## Improvement Opportunities
+
+### 1. Version parity
+- Node: v0.3.1, Python: v0.2.7
+- Recommend aligning Python to 0.3.x with matching toolset
+
+### 2. Test coverage
+- No test files found in repository
+- Could add `pytest` tests and GitHub Actions CI
+
+### 3. CI/CD missing
+- No `.github/workflows/` directory
+- Could add: lint, typecheck, test, build, publish workflows
+
+### 4. License clarification
+- `license: null` — no open source license
+- Should add MIT or Apache 2.0
+
+## Prioritized Candidates for PRs
+
+1. **Fix Python `get_attachment()` bug** — high impact, low effort, clear fix
+2. **Add draft tools to Python** — feature parity with Node, medium effort
+3. **Improve root README** — addresses issues #18, #23, #24
+4. **Add GitHub Actions CI** — quality of life, enables safe contributions
+5. **Align package versions** — v0.3.x for both python and node
\ No newline at end of file
diff --git a/06_SELECTED_5_PR_PLAN.md b/06_SELECTED_5_PR_PLAN.md
new file mode 100644
index 0000000..9f72fb1
--- /dev/null
+++ b/06_SELECTED_5_PR_PLAN.md
@@ -0,0 +1,80 @@
+# 06_SELECTED_5_PR_PLAN.md — 5 Selected PRs for AgentMail Toolkit
+
+## Selected PRs
+
+### PR #1: Fix Python `get_attachment()` client path bug
+**Issue**: Line 39 of `python/src/agentmail_toolkit/functions.py` uses `client.threads.get_attachment()` but should use `client.inboxes.threads.get_attachment()`
+**Severity**: High — tool crashes at runtime
+**Files**:
+- `python/src/agentmail_toolkit/functions.py` (1 line fix)
+**Changes**:
+```python
+# OLD (line 39):
+attachment = client.threads.get_attachment(
+    thread_id=kwargs["thread_id"], attachment_id=kwargs["attachment_id"]
+)
+# NEW:
+attachment = client.inboxes.threads.get_attachment(
+    inbox_id=kwargs["inbox_id"], thread_id=kwargs["thread_id"], attachment_id=kwargs["attachment_id"]
+)
+```
+**Verification**: Build and smoke-test `python/examples/openai_.py`
+
+---
+
+### PR #2: Add draft tools to Python package
+**Issue**: Node has 7 draft tools (create/list/get/update/send/delete_draft + scheduling); Python has 0
+**Files to add/modify**:
+- `python/src/agentmail_toolkit/schemas.py` — add `CreateDraftParams`, `ListDraftsParams`, `GetDraftParams`, `UpdateDraftParams`, `SendDraftParams`, `DeleteDraftParams`
+- `python/src/agentmail_toolkit/functions.py` — add `create_draft`, `list_drafts`, `get_draft`, `update_draft`, `send_draft`, `delete_draft`
+- `python/src/agentmail_toolkit/tools.py` — add 6 new Tool entries for drafts
+- `python/pyproject.toml` — bump version to 0.3.0
+**Verification**: Import and list tools; ensure 17 total tools
+
+---
+
+### PR #3: Improve root README with framework matrix and quick start
+**Issue**: Addresses issues #18, #23, #24 — sparse root README
+**Files**:
+- `README.md` — rewrite with:
+  - Framework compatibility matrix (OpenAI Agents SDK, Vercel AI SDK, LangChain, MCP, LiveKit, Clawdbot)
+  - Badges (PyPI, npm, CI)
+  - Quick start code snippets for each framework
+  - Link to python/ and node/ READMEs
+**Verification**: Review renders correctly on GitHub
+
+---
+
+### PR #4: Add GitHub Actions CI workflow
+**Issue**: No CI/CD — quality risk for contributions
+**Files to add**:
+- `.github/workflows/ci.yml` — for node package:
+  - `pnpm install` → `pnpm lint` → `pnpm build`
+- `.github/workflows/python-ci.yml` — for python package:
+  - `pip install build` → `python -m build` → (no tests yet, but validates build)
+**Note**: Currently no test suite exists; CI at minimum validates lint + build
+
+---
+
+### PR #5: Align Python package version to 0.3.x
+**Issue**: Python v0.2.7 vs Node v0.3.1 — version skew
+**Files**:
+- `python/pyproject.toml` — bump version from 0.2.7 to 0.3.0
+- `python/src/agentmail_toolkit/__init__.py` — update version if hardcoded
+**Changelog**: In `python/README.md` or a new `CHANGELOG.md`, document changes since 0.2.7
+
+---
+
+## Execution Order
+
+1. **PR #1** (Bug fix) — Low risk, high impact, 1 line change
+2. **PR #2** (Draft tools) — New feature, moderate complexity
+3. **PR #5** (Version bump) — Pre-requisite for PR #2, must merge first or together
+4. **PR #3** (README improvement) — Documentation, independent
+5. **PR #4** (CI workflow) — Infrastructure, independent
+
+## Notes
+
+- **Cannot merge without license clarification** — repo has `license: null`. Recommend opening a preliminary issue asking maintainers to add a license before submitting code PRs.
+- **Draft tools PR #2** requires understanding AgentMail SDK's draft API — if SDK doesn't support drafts in Python, this PR would be blocked.
+- **Issues #12, #11** (x402/Fía Signals partner requests) are not actionable by this project — they are feature requests for AgentMail API itself, not the toolkit.
\ No newline at end of file
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..6cb08e4
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,32 @@
+# Contributing to AgentMail Toolkit
+
+Thank you for your interest in contributing to AgentMail Toolkit!
+
+## Getting Started
+
+1. Clone the repository
+2. Explore the `/python` and `/node` packages
+
+## Development
+
+```sh
+# Python package
+cd python
+pip install -e .
+
+# Node package
+cd node
+npm install
+```
+
+## Submitting Changes
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Packages
+
+- `/python` - Python integration for AgentMail API
+- `/node` - Node.js integration for AgentMail API
\ No newline at end of file