"docs: replace README with plain-text v1.4.1 (safe formatting)"

README.md

@@ -1,2 +1,90 @@
-  # My file
-  Everything here is included
+  AI Repo Commander
+
+  A safety-first userscript that lets AI assistants securely interact with git repositories using YAML-style commands. It provides strong guardrails, persistent de-duplication, a draggable debug panel with tools and settings, and robust paste/autosubmit for get_file.
+
+  Highlights:
+  - Code-block only execution (only fenced YAML with the bridge header runs)
+  - Safety-first: STOP switch, strict validation, debounce plus settle
+  - Persistent de-duplication per conversation (30-day TTL)
+  - Streaming-safe: waits for final text before executing
+  - Clear feedback: inline status and desktop notifications
+  - Cross-platform: ChatGPT, Claude, Gemini
+  - Tools & Settings panel: bridge key editor, config JSON, clear history
+  - Robust paste and auto-submit with fallbacks for get_file
+
+  Quick Start:
+  1) Install Tampermonkey or Violentmonkey.
+  2) Create a new userscript and paste src/ai-repo-commander.user.js.
+  3) Ask the assistant to produce a YAML block beginning with the bridge header and ending with the terminator.
+  4) Enter your bridge key when prompted (you can store it in the panel).
+  5) Adjust settings in Tools and Settings as needed.
+
+  Default Configuration (excerpt):
+  ENABLE_API: true
+  DEBUG_MODE: true
+  ASSISTANT_ONLY: true
+  PROCESS_EXISTING: false
+  DEBOUNCE_DELAY: 3000
+  REQUIRE_TERMINATOR: true
+  SETTLE_CHECK_MS: 800
+  SETTLE_POLL_MS: 200
+  API_TIMEOUT_MS: 60000
+  MAX_RETRIES: 2
+  DEDUPE_TTL_MS: 2592000000
+  COLD_START_MS: 2000
+  SHOW_EXECUTED_MARKER: true
+  CLEANUP_AFTER_MS: 30000
+  CLEANUP_INTERVAL_MS: 60000
+  APPEND_TRAILING_NEWLINE: true
+  AUTO_SUBMIT: true
+  POST_PASTE_DELAY_MS: 250
+  SUBMIT_MODE: button_first
+  STUCK_AFTER_MS: 600000
+  SCAN_DEBOUNCE_MS: 250
+  FAST_WARN_MS: 50
+  SLOW_WARN_MS: 60000
+
+  Supported Actions (required fields):
+  get_file: action, repo, path
+  list_files: action, repo, path
+  create_file: action, repo, path, content
+  update_file: action, repo, path, content
+  delete_file: action, repo, path
+  create_branch: action, repo, branch (source_branch defaults to main)
+  create_pr: action, repo, title, head, base
+  merge_pr: action, repo, pr_number
+  close_pr: action, repo, pr_number
+  create_issue: action, repo, title
+  comment_issue: action, repo, issue_number, body
+  close_issue: action, repo, issue_number
+  create_tag: action, repo, tag, target
+  create_release: action, repo, tag_name, name
+  rollback: action, repo, commit_sha
+
+  Operation Summary:
+  1) Monitor assistant messages
+  2) Detect a complete YAML command: header plus terminator
+  3) Debounce and settle, then re-validate
+  4) Execute via the bridge with retries and timeouts
+  5) Show inline status and store dedupe record
+  6) Expose a Run Again button for intentional re-execution
+
+  Runtime Helpers:
+  - AI_REPO_STOP(): emergency stop
+  - AI_REPO_CLEAR_HISTORY(): clear dedupe history
+  - window.AI_REPO_COMMANDER: monitor, config, tests, history
+
+  Security Model:
+  - Bridge key stored locally and masked, never logged
+  - Field validation including path safety and typed values
+  - Assistant-only and code-block-only execution by default
+  - STOP immediately halts scanning and API calls
+
+  Changelog v1.4.1 (summary):
+  - Tools and Settings panel (bridge key editor, clear history, JSON config)
+  - Parser hardening for multiline content and body/message fields
+  - New routes: PRs, Issues, Releases, Tags, Rollback
+  - Per-conversation dedupe with Run Again UI
+  - Streaming settle improvements and debounce
+  - Auto-submit and paste fallback sequence
+  - Configurable timeouts and retry policy