diff --git a/README.md b/README.md
index bca9a93..fef61e1 100644
--- a/README.md
+++ b/README.md
@@ -76,6 +76,357 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
 - [ ] Some deeper runtime details from the npm source
 - [ ] Cost tracking and budget limits
 
+## 🔎 Detailed Parity Status Against npm `src`
+
+This section tracks what is already implemented in Python and what is still missing compared with the upstream npm runtime in [`/src`](/data/fs201059/aa17626/claude_code_source/src).
+
+This is a functionality-oriented checklist, not a line-by-line source equivalence claim. Large parts of the mirrored Python workspace still act as inventory or scaffolding, while the working Python runtime currently lives mainly in [`src/agent_runtime.py`](/data/fs201059/aa17626/claude_code_source/claw-code/src/agent_runtime.py), [`src/agent_tools.py`](/data/fs201059/aa17626/claude_code_source/claw-code/src/agent_tools.py), [`src/agent_prompting.py`](/data/fs201059/aa17626/claude_code_source/claw-code/src/agent_prompting.py), [`src/agent_context.py`](/data/fs201059/aa17626/claude_code_source/claw-code/src/agent_context.py), [`src/agent_slash_commands.py`](/data/fs201059/aa17626/claude_code_source/claw-code/src/agent_slash_commands.py), and [`src/openai_compat.py`](/data/fs201059/aa17626/claude_code_source/claw-code/src/openai_compat.py).
+
+### 1. Core Agent Runtime
+
+Done:
+
+- [x] One-shot agent loop with iterative tool calling
+- [x] OpenAI-compatible `chat/completions` client
+- [x] Local-model execution against `vLLM`
+- [x] Local-model execution through `Ollama`
+- [x] Local-model execution through `LiteLLM Proxy`
+- [x] Transcript-aware session object for the Python runtime
+- [x] Session save and resume support
+- [x] Configurable max-turn execution
+- [x] Permission-aware tool execution
+
+Missing:
+
+- [ ] Streaming token-by-token assistant output
+- [ ] Partial tool-result streaming
+- [ ] Rich transcript mutation behavior like the npm runtime
+- [ ] Structured output / JSON schema response modes
+- [ ] Reasoning budgets and task budgets
+- [ ] Cost accounting and usage budget enforcement
+- [ ] Multi-agent orchestration parity
+- [ ] File history snapshots and replay flows
+- [ ] Scratchpad integration
+- [ ] Plugin cache integration in the query engine
+- [ ] Session compaction / snipping behavior
+- [ ] Full `QueryEngine.ts` parity
+
+### 2. CLI Entrypoints And Runtime Modes
+
+Done:
+
+- [x] Python CLI entrypoint
+- [x] `agent` command
+- [x] `agent-resume` command
+- [x] `agent-prompt` command
+- [x] `agent-context` command
+- [x] `agent-context-raw` command
+- [x] Inventory/helper commands such as `summary`, `manifest`, `commands`, and `tools`
+
+Missing:
+
+- [ ] Daemon worker mode
+- [ ] Background session mode
+- [ ] Session process listing (`ps`)
+- [ ] Background session logs
+- [ ] Background attach flow
+- [ ] Background kill flow
+- [ ] Remote-control / bridge runtime mode
+- [ ] Browser/native-host runtime mode
+- [ ] Computer-use MCP mode
+- [ ] Template job mode
+- [ ] Environment runner mode
+- [ ] Self-hosted runner mode
+- [ ] tmux fast paths
+- [ ] Worktree fast paths at the CLI entrypoint level
+- [ ] Full `entrypoints/cli.tsx` and `entrypoints/init.ts` parity
+
+### 3. Prompt Assembly
+
+Done:
+
+- [x] Structured Python system prompt builder
+- [x] Intro/system/task/tool/tone/output sections
+- [x] Session-specific prompt guidance
+- [x] Environment-aware prompt sections
+- [x] User context reminder injection
+- [x] Custom system prompt override and append support
+
+Missing:
+
+- [ ] Full parity with `constants/prompts.ts`
+- [ ] Hook instruction sections
+- [ ] MCP instruction sections
+- [ ] Model-family-specific prompt variations
+- [ ] Output-style variants
+- [ ] Language-control sections
+- [ ] Scratchpad prompt instructions
+- [ ] More exact autonomous/proactive behavior sections
+- [ ] Growthbook / feature-gated prompt sections
+- [ ] Cyber / risk sections used upstream
+
+### 4. Context Building And Memory
+
+Done:
+
+- [x] Current working directory snapshot
+- [x] Shell / platform / date capture
+- [x] Git status snapshot
+- [x] `CLAUDE.md` discovery
+- [x] Extra directory injection through `--add-dir`
+- [x] Session context usage report
+- [x] Raw context inspection command
+
+Missing:
+
+- [ ] Tokenizer-accurate context accounting
+- [ ] Full parity with `utils/queryContext.ts`
+- [ ] Rich memory prompt loading
+- [ ] Internal permission-aware memory handling
+- [ ] Resume-aware prompt cache shaping used upstream
+- [ ] More exact context cache invalidation rules
+- [ ] Session context analysis parity
+- [ ] Full memory subsystem parity
+
+### 5. Slash Commands
+
+Done:
+
+- [x] `/help`
+- [x] `/commands`
+- [x] `/context`
+- [x] `/usage`
+- [x] `/context-raw`
+- [x] `/env`
+- [x] `/prompt`
+- [x] `/system-prompt`
+- [x] `/permissions`
+- [x] `/model`
+- [x] `/tools`
+- [x] `/memory`
+- [x] `/status`
+- [x] `/session`
+- [x] `/clear`
+
+Missing:
+
+- [ ] Full npm slash-command surface
+- [ ] Slash commands backed by MCP integration
+- [ ] Slash commands tied to task/plan systems
+- [ ] Slash commands tied to remote/background sessions
+- [ ] Slash commands with richer interactive behavior
+- [ ] Slash commands tied to plugins and bundled skills
+- [ ] Slash commands tied to settings, config, and account state
+
+### 6. Built-in Tools
+
+Done:
+
+- [x] `list_dir`
+- [x] `read_file`
+- [x] `write_file`
+- [x] `edit_file`
+- [x] `glob_search`
+- [x] `grep_search`
+- [x] `bash`
+
+Missing:
+
+- [ ] Agent spawning tool
+- [ ] Skill tool
+- [ ] Notebook edit tool
+- [ ] Web fetch tool
+- [ ] Web search tool
+- [ ] Todo write tool
+- [ ] Ask-user-question tool
+- [ ] LSP tool
+- [ ] MCP resource listing tool
+- [ ] MCP resource read tool
+- [ ] Tool search tool
+- [ ] Config tool
+- [ ] Task create/get/update/list tools
+- [ ] Team create/delete tools
+- [ ] Send-message tool
+- [ ] Terminal capture tool
+- [ ] Browser tool
+- [ ] Workflow tool
+- [ ] Remote trigger tool
+- [ ] Sleep / cron tools
+- [ ] PowerShell tool parity
+- [ ] Worktree enter/exit tools
+- [ ] Full `tools.ts` parity
+
+### 7. Commands And Task Systems
+
+Done:
+
+- [x] Basic local command dispatch for the Python runtime
+- [x] Inventory view of mirrored command names
+
+Missing:
+
+- [ ] Real implementation of the larger upstream command tree
+- [ ] Task orchestration system
+- [ ] Planner / task execution parity
+- [ ] Team / collaboration command flows
+- [ ] Background task management
+- [ ] Command-specific session behaviors
+- [ ] Full `src/commands/*` parity
+- [ ] Full `src/tasks/*` parity
+
+### 8. Permissions, Hooks, And Policy
+
+Done:
+
+- [x] Read-only default mode
+- [x] Write-gated mode
+- [x] Shell-gated mode
+- [x] Unsafe mode for destructive shell actions
+
+Missing:
+
+- [ ] Hooks runtime
+- [ ] Tool-permission workflow parity
+- [ ] Policy limit loading
+- [ ] Managed settings loading
+- [ ] Trust-gated initialization
+- [ ] Safe environment loading parity
+- [ ] More exact denial tracking
+- [ ] Hook-config management
+- [ ] Full hooks and policy parity
+
+### 9. MCP, Plugins, And Skills
+
+Done:
+
+- [x] Placeholder mirrored package layout for plugins, skills, services, and remote subsystems
+
+Missing:
+
+- [ ] Real MCP client support
+- [ ] MCP server integration
+- [ ] MCP resource listing and reading
+- [ ] MCP-backed tools
+- [ ] Plugin discovery and loading
+- [ ] Bundled plugin support
+- [ ] Plugin lifecycle management
+- [ ] Plugin update/cache behavior
+- [ ] Skill discovery and execution parity
+- [ ] Bundled skill support
+- [ ] Full plugin and skill parity
+
+### 10. Interactive UI / REPL / TUI
+
+Done:
+
+- [x] Non-interactive CLI execution
+- [x] Transcript printing for debugging
+
+Missing:
+
+- [ ] Interactive REPL parity
+- [ ] Ink/TUI component parity
+- [ ] Screen system parity
+- [ ] Keyboard interaction parity
+- [ ] Interactive status panes
+- [ ] Approval UI flows
+- [ ] Rich incremental rendering
+- [ ] Full `components`, `screens`, and `ink` parity
+
+### 11. Remote, Background, And Team Features
+
+Done:
+
+- [x] Session save/resume on local disk
+
+Missing:
+
+- [ ] Remote execution modes
+- [ ] Background agent processes
+- [ ] Background attach/log/kill workflows
+- [ ] Team runtime features
+- [ ] Team messaging features
+- [ ] Shared remote state
+- [ ] Upstream proxy runtime integration
+- [ ] Full `remote`, `server`, `bridge`, `upstreamproxy`, and team parity
+
+### 12. Editor, Platform, And Native Integrations
+
+Done:
+
+- [x] Standard shell-based local workflow
+
+Missing:
+
+- [ ] Voice mode parity
+- [ ] VIM mode parity
+- [ ] Keybinding parity
+- [ ] Notification hooks
+- [ ] Native TypeScript / platform helper parity
+- [ ] JetBrains/editor integration parity
+- [ ] Browser/native host integrations
+- [ ] Platform-specific startup/shutdown logic
+
+### 13. Services And Internal Subsystems
+
+Done:
+
+- [x] Minimal internal service layer required by the current Python runtime
+
+Missing:
+
+- [ ] Real service implementations for the mirrored `services` package
+- [ ] Config service parity
+- [ ] Account/auth service parity
+- [ ] Analytics/telemetry service parity
+- [ ] Growthbook/feature-flag parity
+- [ ] GitHub / git helper parity
+- [ ] Sandbox/settings utility parity
+- [ ] Todo/task utility parity
+- [ ] Internal helpers used by the upstream runtime
+
+### 14. Mirrored Workspace Versus Working Runtime
+
+Working Python runtime today:
+
+- [x] `src/main.py`
+- [x] `src/agent_runtime.py`
+- [x] `src/agent_tools.py`
+- [x] `src/agent_prompting.py`
+- [x] `src/agent_context.py`
+- [x] `src/agent_context_usage.py`
+- [x] `src/agent_session.py`
+- [x] `src/agent_slash_commands.py`
+- [x] `src/agent_types.py`
+- [x] `src/openai_compat.py`
+- [x] `src/session_store.py`
+- [x] `src/permissions.py`
+
+Mirrored inventory / scaffold areas that still need real implementation work:
+
+- [ ] `src/commands.py`
+- [ ] `src/tools.py`
+- [ ] `src/query_engine.py`
+- [ ] `src/runtime.py`
+- [ ] `src/services/*`
+- [ ] `src/plugins/*`
+- [ ] `src/remote/*`
+- [ ] `src/voice/*`
+- [ ] `src/vim/*`
+- [ ] Large parts of the rest of the mirrored package tree
+
+### 15. High-Priority Next Steps
+
+- [ ] Expand the real Python tool registry toward upstream `tools.ts`
+- [ ] Replace more snapshot-backed mirrored modules with working runtime code
+- [ ] Implement real MCP support
+- [ ] Implement hooks and policy flows
+- [ ] Build a real interactive REPL / TUI
+- [ ] Add tokenizer-accurate context accounting
+- [ ] Add background and remote session modes
+- [ ] Port more of the command/task system
+- [ ] Close the gap between the mirrored workspace and the working runtime
+
 ---
 
 ## 🏗️ Architecture