diff --git a/README.md b/README.md
index e0d1214..04e59c9 100644
--- a/README.md
+++ b/README.md
@@ -1,30 +1,164 @@
-  # AI Repo Commander
-  
-  A safety-first browser extension that enables AI assistants to securely interact with git repositories through YAML-style commands.
-  
-  ## Features
-  
-  - 🛡️ Safety-first design with master kill switch
-  - 📝 YAML-style command syntax
-  - 🤖 Bot typing protection (5-second debounce)
-  - 🔍 Comprehensive validation
-  - 📊 Clear status feedback
-  - 🔧 Cross-platform support (ChatGPT, Claude, Gemini)
-  
-  ## Quick Start
-  
-  1. Install Violentmonkey or Tampermonkey
-  2. Load `src/ai-repo-commander.user.js`
-  3. Review and enable API in configuration
-  4. Use YAML commands in AI chats
-  
-  ## Command Examples
-  
-  ```yaml
-  ^%$bridge
-  action: update_file
-  repo: my-project
-  path: README.md
-  content: |
-    Updated content
-    with multiple lines
\ No newline at end of file
+AI Repo Commander
+
+A safety-first userscript that lets AI assistants securely interact with your git repos using YAML-style commands — with strong guardrails, persistent de-duplication, and clear feedback.
+
+Highlights
+
+🧱 Execute only inside code blocks — discuss freely in plain text; only fenced blocks run
+
+🛡️ Safety-first: master kill switch, schema validation, per-command debouncing
+
+♻️ Persistent de-duplication (30-day localStorage) — prevents re-runs on reload
+
+⏳ Bot typing protection: 5-second debounce (streams settle before execution)
+
+🧪 Clear status UI: Processing / Success / Error banners in the chat
+
+🔌 Cross-platform: ChatGPT, Claude, Gemini
+
+📋 Robust paste for get_file (DataTransfer → execCommand → ProseMirror → clipboard fallback)
+
+Quick Start
+
+Install Tampermonkey (or Violentmonkey) in your browser.
+
+Add the userscript: src/ai-repo-commander.user.js (or paste into a new script).
+
+(Optional) Open the script and review CONFIG defaults.
+
+In chat, ask the AI to return a code-fenced YAML command (fenced with ``` and containing ^%$bridge).
+
+On first run with API enabled, you’ll be prompted for your bridge key (kept in memory for the session).
+
+ℹ️ By default:
+
+ASSISTANT_ONLY: true — only assistant messages are processed.
+
+PROCESS_EXISTING: false — avoids sweeping old messages on load.
+
+Commands must appear inside a <pre><code> / fenced code block to execute.
+
+Example Commands
+
+Wrap commands in a code block and start with ^%$bridge. The block ends at --- or end-of-code-block.
+
+^%$bridge
+action: update_file
+repo: my-project
+path: README.md
+content: |
+  Updated content
+  with multiple lines
+---
+
+^%$bridge
+action: get_file
+repo: my-project
+path: src/index.js
+---
+
+Supported Actions & Required Fields
+action	required fields	notes
+get_file	action, repo, path	Pastes content into the chat input (or copies to clipboard if paste is blocked)
+list_files	action, repo, path	Lists files under a path
+create_repo	action, repo	Creates a repo (backend must support it)
+create_file	action, repo, path, content	Auto-adds a commit_message if omitted
+update_file	action, repo, path, content	Auto-adds a commit_message if omitted
+delete_file	action, repo, path	Deletes a file
+
+Optional fields: owner (defaults to rob), url (bridge URL), branch, ref, commit_message.
+
+Configuration (excerpt)
+const CONFIG = {
+  ENABLE_API: true,              // master kill switch
+  DEBUG_MODE: true,
+  DEBOUNCE_DELAY: 5000,
+  MAX_RETRIES: 2,
+  VERSION: '1.2.1',
+
+  PROCESS_EXISTING: false,       // skip old messages on load
+  ASSISTANT_ONLY: true,          // process assistant messages by default
+
+  DEDUPE_TTL_MS: 30*24*60*60*1000, // 30d persistent dedupe
+  CLEANUP_AFTER_MS: 30000,
+  CLEANUP_INTERVAL_MS: 60000
+};
+
+
+Runtime helpers
+
+Emergency stop: AI_REPO_STOP()
+
+Clear persistent history: AI_REPO_CLEAR_HISTORY()
+
+Inspect at runtime: window.AI_REPO_COMMANDER (monitor, config, test, history)
+
+How It Works
+
+Detect new assistant messages.
+
+Require a code-fenced block containing ^%$bridge.
+
+Extract & parse YAML; validate required fields and formats.
+
+Debounce for 5s (prevents partial/streaming execution).
+
+Execute against your bridge (with retries & timeouts) or mock if disabled.
+
+Feedback replaces the command with a status banner.
+
+Persist a hash of the executed block for 30 days (prevents re-runs).
+
+Status Messages
+
+[action: Processing…] – making the API request
+
+[action: Success] – operation completed (message from bridge shown when available)
+
+[action: Error] – network/timeout/validation error (details included)
+
+Troubleshooting
+
+Command didn’t run
+
+Ensure it’s inside a code block and begins with ^%$bridge.
+
+With defaults, only assistant messages execute (ASSISTANT_ONLY: true).
+
+It may be deduped (already executed). Clear with AI_REPO_CLEAR_HISTORY() or edit the block.
+
+If the AI streamed and then edited the block, the script waits for the final version before running.
+
+get_file didn’t paste
+
+Some editors block synthetic paste. We fall back to copying to the clipboard and notify you to paste manually.
+
+Re-running on purpose
+
+Edit any part of the code-block (whitespace included) or clear history: AI_REPO_CLEAR_HISTORY().
+
+Emergency stop
+
+Call AI_REPO_STOP() (sets ENABLE_API=false, halts observers).
+
+Security Model
+
+Local use: Bridge key is kept in memory for the session (prompted on first API call).
+
+Command validation: required fields, path traversal guards, action whitelist.
+
+Safe defaults: assistant-only, code-block-only, persistent dedupe.
+
+Changelog
+
+v1.2.1
+
+Execute only inside code blocks
+
+Persistent dedupe (30-day localStorage)
+
+Streaming-safe debounce & re-parse
+
+Robust get_file paste with clipboard fallback
+
+Safer assistant detection; initial delayed scan to catch first render
\ No newline at end of file