screenhand 0.1.0 → 0.1.1

package/README.md

@@ -4,41 +4,43 @@
 
 **Give AI eyes and hands on your desktop.**
 
-An open-source [MCP server](https://modelcontextprotocol.io/) that lets Claude (and any AI agent) see your screen, click buttons, type text, and control any app — on both macOS and Windows.
+ScreenHand is an [MCP server](https://modelcontextprotocol.io/) that lets AI agents see your screen, click buttons, type text, and control any app on macOS and Windows.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
 [![npm: screenhand](https://img.shields.io/npm/v/screenhand)](https://www.npmjs.com/package/screenhand)
 [![Platform: macOS & Windows](https://img.shields.io/badge/Platform-macOS%20%7C%20Windows-green)]()
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple)]()
 
-[Website](https://screenhand.com) | [Quick Start](#quick-start) | [Tools](#tools) | [FAQ](#faq)
+[Website](https://screenhand.com) | [Quick Start](#quick-start) | [Use Cases](#use-cases) | [FAQ](#faq)
 
 </div>
 
 ---
 
-## What is ScreenHand?
+## The Problem
 
-ScreenHand is a **desktop automation bridge for AI**. It connects AI assistants like Claude to your operating system so they can:
+AI assistants are powerful — but they're blind. They can't see what's on your screen, click a button, or type into an app. If you want Claude to help you automate a workflow, debug a UI, or fill out a form, you're stuck copy-pasting screenshots and describing what you see.
+
+**ScreenHand fixes that.** It gives any AI agent direct access to your desktop through native OS APIs — not slow screenshot-and-guess loops.
+
+## How It Works
+
+You connect ScreenHand to your AI client (Claude, Cursor, Codex CLI, etc.) via the [Model Context Protocol](https://modelcontextprotocol.io/). Once connected, your AI can:
 
 - **See** your screen via screenshots and OCR
-- **Read** UI elements via Accessibility APIs (macOS) or UI Automation (Windows)
+- **Read** UI elements directly via native Accessibility APIs
 - **Click** buttons, menus, and links
 - **Type** text into any input field
 - **Control** Chrome tabs via DevTools Protocol
-- **Run** AppleScript commands (macOS)
-
-It works as an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server, meaning any MCP-compatible AI client can use it out of the box.
+- **Automate** cross-app workflows
 
-## Why ScreenHand?
-
-| Problem | ScreenHand Solution |
-|---|---|
-| AI can't see your screen | Screenshots + OCR return all visible text |
-| AI can't click UI elements | Accessibility API finds and clicks elements in ~50ms |
-| AI can't control browsers | Chrome DevTools Protocol gives full page control |
-| AI can't automate workflows | 25+ tools for cross-app automation |
-| Only works on one OS | Native bridges for both macOS and Windows |
+```
+Your AI Client (Claude, Cursor, etc.)
+    |  MCP protocol (stdio)
+ScreenHand
+    |  Native OS APIs
+Your Desktop (any app, any browser)
+```
 
 ## Quick Start
 
@@ -50,9 +52,10 @@ npm run build:native   # macOS — builds Swift bridge
 # npm run build:native:windows   # Windows — builds .NET bridge
 ```
 
-Then connect ScreenHand to your AI client.
+### Connect to Your AI Client
 
-### Claude Desktop
+<details>
+<summary><strong>Claude Desktop</strong></summary>
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 
@@ -61,13 +64,15 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
   "mcpServers": {
     "screenhand": {
       "command": "npx",
-      "args": ["tsx", "/path/to/screenhand/src/mcp-entry.ts"]
+      "args": ["tsx", "/path/to/screenhand/mcp-desktop.ts"]
     }
   }
 }
 ```
+</details>
 
-### Claude Code
+<details>
+<summary><strong>Claude Code</strong></summary>
 
 Add to your project `.mcp.json` or `~/.claude/settings.json`:
 
@@ -76,352 +81,152 @@ Add to your project `.mcp.json` or `~/.claude/settings.json`:
   "mcpServers": {
     "screenhand": {
       "command": "npx",
-      "args": ["tsx", "/path/to/screenhand/src/mcp-entry.ts"]
+      "args": ["tsx", "/path/to/screenhand/mcp-desktop.ts"]
     }
   }
 }
 ```
+</details>
 
-### Cursor
+<details>
+<summary><strong>Cursor</strong></summary>
 
-Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for global):
+Add to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` globally):
 
 ```json
 {
   "mcpServers": {
     "screenhand": {
       "command": "npx",
-      "args": ["tsx", "/path/to/screenhand/src/mcp-entry.ts"]
+      "args": ["tsx", "/path/to/screenhand/mcp-desktop.ts"]
     }
   }
 }
 ```
+</details>
 
-### OpenAI Codex CLI
+<details>
+<summary><strong>OpenAI Codex CLI</strong></summary>
 
 Add to `~/.codex/config.toml`:
 
 ```toml
 [mcp.screenhand]
 command = "npx"
-args = ["tsx", "/path/to/screenhand/src/mcp-entry.ts"]
+args = ["tsx", "/path/to/screenhand/mcp-desktop.ts"]
 transport = "stdio"
 ```
+</details>
 
-### OpenClaw
+<details>
+<summary><strong>Any MCP Client</strong></summary>
 
-Add to your `openclaw.json`:
-
-```json
-{
-  "mcpServers": {
-    "screenhand": {
-      "command": "npx",
-      "args": ["tsx", "/path/to/screenhand/src/mcp-entry.ts"]
-    }
-  }
-}
-```
-
-> **Why?** OpenClaw's built-in desktop control sends a screenshot to an LLM for every click (~3-5s, costs an API call). ScreenHand uses native Accessibility APIs — `press('Send')` runs in ~50ms with zero AI calls. See the full [integration guide](docs/openclaw-integration.md).
-
-### Any MCP Client
-
-ScreenHand is a standard MCP server over stdio. It works with any MCP-compatible client — just point it at `src/mcp-entry.ts`.
+ScreenHand is a standard MCP server over stdio. Point any MCP-compatible client at `mcp-desktop.ts`.
+</details>
 
 Replace `/path/to/screenhand` with the actual path where you cloned the repo.
 
-## Tools
-
-ScreenHand exposes 25+ tools organized by category.
-
-### See the Screen
-
-| Tool | What it does | Speed |
-|------|-------------|-------|
-| `screenshot` | Full screenshot + OCR — returns all visible text | ~600ms |
-| `screenshot_file` | Screenshot saved to file (for viewing the image) | ~400ms |
-| `ocr` | OCR with element positions and bounding boxes | ~600ms |
-
-### Control Any App (Accessibility / UI Automation)
-
-| Tool | What it does | Speed |
-|------|-------------|-------|
-| `apps` | List running apps with bundle IDs and PIDs | ~10ms |
-| `windows` | List visible windows with positions and sizes | ~10ms |
-| `focus` | Bring an app to the front | ~10ms |
-| `launch` | Launch an app by bundle ID or name | ~1s |
-| `ui_tree` | Full UI element tree — instant, no OCR needed | ~50ms |
-| `ui_find` | Find a UI element by text or title | ~50ms |
-| `ui_press` | Click a UI element by its title | ~50ms |
-| `ui_set_value` | Set value of a text field, slider, etc. | ~50ms |
-| `menu_click` | Click a menu bar item by path | ~100ms |
-
-### Keyboard and Mouse
-
-| Tool | What it does |
-|------|-------------|
-| `click` | Click at screen coordinates |
-| `click_text` | Find text via OCR and click it (fallback) |
-| `type_text` | Type text via keyboard |
-| `key` | Key combo (e.g. `cmd+s`, `ctrl+shift+n`) |
-| `drag` | Drag from point A to B |
-| `scroll` | Scroll at a position |
-
-### Chrome Browser (CDP)
-
-| Tool | What it does |
-|------|-------------|
-| `browser_tabs` | List all open Chrome tabs |
-| `browser_open` | Open URL in new tab |
-| `browser_navigate` | Navigate active tab to URL |
-| `browser_js` | Run JavaScript in a tab |
-| `browser_dom` | Query DOM with CSS selectors |
-| `browser_click` | Click element by CSS selector (uses CDP mouse events) |
-| `browser_type` | Type into an input field (uses CDP keyboard events, React-compatible) |
-| `browser_wait` | Wait for a page condition |
-| `browser_page_info` | Get page title, URL, and content |
-
-### Anti-Detection & Stealth (CDP)
-
-Tools for interacting with sites that have bot detection (Instagram, LinkedIn, etc.):
-
-| Tool | What it does |
-|------|-------------|
-| `browser_stealth` | Inject anti-detection patches (hides webdriver flag, fakes plugins/languages) |
-| `browser_fill_form` | Human-like typing with random delays via CDP keyboard events |
-| `browser_human_click` | Realistic mouse event sequence (mouseMoved → mousePressed → mouseReleased) |
-
-> **Tip:** Call `browser_stealth` once after navigating to a protected site. Then use `browser_fill_form` and `browser_human_click` for interactions. The regular `browser_type` and `browser_click` also use CDP Input events now.
-
-### Platform Playbooks (lazy-loaded)
-
-Pre-built automation knowledge for specific platforms — selectors, URLs, flows, and **error solutions**.
-
-| Tool | What it does |
-|------|-------------|
-| `platform_guide` | Get automation guide for a platform (selectors, URLs, flows, errors+solutions) |
-| `export_playbook` | Auto-generate a playbook from your session. Share it to help others. |
-
-```
-platform_guide({ platform: "devpost", section: "errors" })   # Just errors + solutions
-platform_guide({ platform: "devpost", section: "selectors" }) # All CSS selectors
-platform_guide({ platform: "devpost", section: "flows" })     # Step-by-step workflows
-platform_guide({ platform: "devpost" })                       # Full playbook
-```
-
-**Contributing playbooks:** After automating any site, run:
-```
-export_playbook({ platform: "twitter", domain: "twitter.com" })
-```
-This auto-extracts URLs, selectors, errors+solutions from your session and saves a ready-to-share `playbooks/twitter.json`.
-
-Available platforms: `devpost`. Add more by running `export_playbook` or creating JSON files in `playbooks/`.
-
-Zero performance cost — files only read when `platform_guide` is called.
-
-### AppleScript (macOS only)
-
-| Tool | What it does |
-|------|-------------|
-| `applescript` | Run any AppleScript command |
-
-### Memory (Learning) — zero-config, zero-latency
-
-ScreenHand gets smarter every time you use it — **no manual setup needed**.
-
-**What happens automatically:**
-- Every tool call is logged (async, non-blocking — adds ~0ms to response time)
-- After 3+ consecutive successes, the winning sequence is saved as a reusable strategy
-- Known error patterns are tracked with resolutions (e.g. "launch times out → use focus() instead")
-- On every tool call, the response includes **auto-recall hints**:
-  - Error warnings if the tool has failed before
-  - Next-step suggestions if you're mid-way through a known strategy
-
-**Predefined seed strategies:**
-- Ships with 12 common macOS workflows (Photo Booth, Chrome navigation, copy/paste, Finder, export PDF, etc.)
-- Loaded automatically on first boot — the system has knowledge from day one
-- Seeds are searchable via `memory_recall` and provide next-step hints like any learned strategy
-
-**Background web research:**
-- When a tool fails and no resolution exists, ScreenHand searches for a fix in the background (non-blocking)
-- Uses Claude API (haiku, if `ANTHROPIC_API_KEY` is set) or DuckDuckGo instant answers as fallback
-- Resolutions are saved to both error cache and strategy store — zero-latency recall next time
-- Completely silent and fire-and-forget — never blocks tool responses or throws errors
-
-**Fingerprint matching & feedback loop:**
-- Each strategy is fingerprinted by its tool sequence (e.g. `apps→focus→ui_press`)
-- O(1) exact-match lookup when the agent follows a known sequence
-- Success/failure outcomes are tracked per strategy — unreliable strategies are auto-penalized and eventually skipped
-- Keyword-based fuzzy search with reliability scoring for `memory_recall`
-
-**Production-grade under the hood:**
-- All data cached in RAM at startup — lookups are ~0ms, disk is only for persistence
-- Disk writes are async and buffered (100ms debounce) — never block tool calls
-- Sync flush on process exit (SIGINT/SIGTERM) — no lost writes
-- Per-line JSONL parsing — corrupted lines are skipped, not fatal
-- LRU eviction: 500 strategies, 200 error patterns max (oldest evicted automatically)
-- File locking (`.lock` + PID) prevents corruption from concurrent instances
-- Action log auto-rotates at 10 MB
-- Data lives in `.screenhand/memory/` as JSONL (grep-friendly, no database)
-
-| Tool | What it does |
-|------|-------------|
-| `memory_recall` | Explicitly search past strategies by task description |
-| `memory_save` | Manually save the current session (auto-save handles most cases) |
-| `memory_errors` | View all known error patterns and their resolutions |
-| `memory_stats` | Action counts, success rates, top tools, disk usage |
-| `memory_clear` | Clear actions, strategies, errors, or all data |
-
-## How It Works
-
-ScreenHand has three layers:
-
-```
-AI Client (Claude, Cursor, etc.)
-    ↓ MCP protocol (stdio)
-ScreenHand MCP Server (TypeScript)
-    ↓ JSON-RPC (stdio)
-Native Bridge (Swift on macOS / C# on Windows)
-    ↓ Platform APIs
-Operating System (Accessibility, CoreGraphics, UI Automation, SendInput)
-```
-
-1. **Native bridge** — talks directly to OS-level APIs:
-   - **macOS**: Swift binary using Accessibility APIs, CoreGraphics, and Vision framework (OCR)
-   - **Windows**: C# (.NET 8) binary using UI Automation, SendInput, GDI+, and Windows.Media.Ocr
-2. **TypeScript MCP server** — routes tools to the correct bridge, handles Chrome CDP, manages sessions
-3. **MCP protocol** — standard Model Context Protocol so any AI client can connect
-
-The native bridge is auto-selected based on your OS. Both bridges speak the same JSON-RPC protocol, so all tools work identically on both platforms.
-
 ## Use Cases
 
-### App Debugging
-Claude reads UI trees, clicks through flows, and checks element states — faster than clicking around yourself.
+### Automate Repetitive Workflows
+Tell your AI "submit this form on 10 websites" or "export all these reports as PDFs" — and it does it. ScreenHand handles the clicking, typing, and navigating across any app.
 
-### Design Inspection
-Screenshots + OCR to read exactly what's on screen. `ui_tree` shows component structure like React DevTools but for any native app.
+### Debug UIs Faster
+Instead of clicking through your app manually, let Claude inspect the full UI element tree, check states, and walk through flows — all from your terminal.
 
-### Browser Automation
-Fill forms, scrape data, run JavaScript, navigate pages — all through Chrome DevTools Protocol.
+### Browser Automation Without Selenium
+Fill forms, scrape data, run JavaScript, and navigate pages through Chrome DevTools Protocol. Works with sites that block traditional automation.
 
 ### Cross-App Workflows
-Read from one app, paste into another, chain actions across your whole desktop. Example: extract data from a spreadsheet, search it in Chrome, paste results into Notes.
-
-### UI Testing
-Click buttons, verify text appears, catch visual regressions — all driven by AI.
-
-## Requirements
-
-### macOS
+Read data from a spreadsheet, search it in Chrome, paste results into Notes — chain actions across your entire desktop.
 
-- macOS 12+
-- Node.js 18+
-- Accessibility permissions: System Settings > Privacy & Security > Accessibility > enable your terminal
-- Chrome with `--remote-debugging-port=9222` (only for browser tools)
+### AI-Powered UI Testing
+Click buttons, verify text appears, check element states, and catch regressions — all driven by your AI agent.
 
-### Windows
+## What's Included
 
-- Windows 10 (1809+)
-- Node.js 18+
-- [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
-- No special permissions needed — UI Automation works without admin
-- Chrome with `--remote-debugging-port=9222` (only for browser tools)
-- Build: `npm run build:native:windows`
+ScreenHand exposes **70+ tools** organized by what you need to do:
 
-## Skills (Slash Commands)
+| Category | Examples | What For |
+|----------|----------|----------|
+| **Screen** | `screenshot`, `ocr` | See what's on screen, read all visible text |
+| **App Control** | `ui_tree`, `ui_press`, `menu_click` | Read and interact with any native app |
+| **Keyboard & Mouse** | `click`, `type_text`, `key`, `drag` | Direct input control |
+| **Chrome Browser** | `browser_navigate`, `browser_js`, `browser_dom` | Full browser automation via CDP |
+| **Memory** | `memory_recall`, `memory_save` | ScreenHand learns from past sessions |
+| **AppleScript** | `applescript` | Run AppleScript on macOS |
 
-ScreenHand ships with Claude Code slash commands:
+For the full tool reference, see the [tool documentation](DESKTOP_MCP_GUIDE.md).
 
-- `/screenshot` — capture your screen and describe what's visible
-- `/debug-ui` — inspect the UI tree of any app
-- `/automate` — describe a task and Claude does it
-
-**Install globally** so they work in any project:
+## Requirements
 
-```bash
-./install-skills.sh
-```
+| | macOS | Windows |
+|---|---|---|
+| **OS** | macOS 12+ | Windows 10 (1809+) |
+| **Runtime** | Node.js 18+ | Node.js 18+ |
+| **Permissions** | Accessibility (System Settings) | None (no admin needed) |
+| **Browser tools** | Chrome with `--remote-debugging-port=9222` | Same |
+| **Build** | `npm run build:native` | `npm run build:native:windows` |
 
 ## Development
 
 ```bash
-npm run check              # type-check (covers all entry files)
-npm test                   # run test suite (95 tests)
+npm run check              # type-check
+npm test                   # run test suite
 npm run build              # compile TypeScript
-npm run build:native       # build Swift bridge (macOS)
-npm run build:native:windows  # build .NET bridge (Windows)
+npm run build:native       # build native bridge
 ```
 
 ## FAQ
 
-### What is ScreenHand?
-ScreenHand is an open-source MCP server that gives AI assistants like Claude the ability to see and control your desktop. It provides 25+ tools for screenshots, UI inspection, clicking, typing, and browser automation on both macOS and Windows.
-
-### How does ScreenHand differ from Anthropic's Computer Use?
-Anthropic's Computer Use is a cloud-based feature built into Claude. ScreenHand is an open-source, local-first tool that runs entirely on your machine with no cloud dependency. It uses native OS APIs (Accessibility on macOS, UI Automation on Windows) which are faster and more reliable than screenshot-based approaches.
+<details>
+<summary><strong>What is ScreenHand?</strong></summary>
 
-### How does ScreenHand differ from OpenClaw?
-OpenClaw is a general-purpose AI agent that controls your computer by looking at the screen — it takes screenshots, interprets them with an LLM, then simulates mouse/keyboard input. ScreenHand takes a fundamentally different approach:
+An MCP server that gives AI agents the ability to see and control your desktop. It uses native OS APIs (Accessibility on macOS, UI Automation on Windows) for fast, reliable automation — not slow screenshot-based guessing.
+</details>
 
-| | ScreenHand | OpenClaw |
-|---|---|---|
-| **How it sees the UI** | Native Accessibility/UI Automation APIs — reads the actual element tree | Screenshots + LLM vision — interprets pixels |
-| **Speed** | ~50ms per UI action | Seconds per action (screenshot → LLM → click) |
-| **Accuracy** | Exact element targeting by role/title | Coordinate-based — can misclick if layout shifts |
-| **Architecture** | MCP server — works with any MCP client (Claude, Cursor, Codex CLI) | Standalone agent — tied to its own runtime |
-| **Model lock-in** | None — any MCP-compatible AI decides what to do | Supports multiple LLMs but runs its own agent loop |
-| **Learning memory** | Built-in: auto-learns strategies, tracks errors, O(1) fingerprint recall | Skill-based: 5,000+ community skills, but no automatic learning from usage |
-| **Security** | Scoped MCP tools, audit logging, no browser cookie access | Full computer access, uses browser cookies, significant security surface |
-| **Setup** | `npm install` + grant accessibility permission | Requires careful sandboxing, not recommended on personal machines |
-
-**TL;DR**: OpenClaw is a powerful autonomous agent for tinkerers who want maximum flexibility. ScreenHand is a focused, fast, secure automation layer designed to be embedded into any AI workflow via MCP — with native API speed instead of screenshot-based guessing.
+<details>
+<summary><strong>How is this different from Anthropic's Computer Use?</strong></summary>
 
-### Does ScreenHand work on Windows?
-Yes. ScreenHand supports both macOS and Windows. On macOS it uses a Swift native bridge with Accessibility APIs. On Windows it uses a C# (.NET 8) bridge with UI Automation and SendInput.
+Computer Use is cloud-based and built into Claude. ScreenHand is open-source, runs locally on your machine, and uses native OS APIs which are faster and more reliable than screenshot-based approaches. It also works with any MCP-compatible client, not just Claude.
+</details>
 
-### What AI clients work with ScreenHand?
-Any MCP-compatible client: Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Codex CLI, and any other tool that supports the Model Context Protocol.
+<details>
+<summary><strong>Is it safe?</strong></summary>
 
-### Does ScreenHand need admin/root permissions?
-On macOS, you need to grant Accessibility permissions to your terminal app. On Windows, no special permissions are needed — UI Automation works without admin for most applications.
+ScreenHand runs entirely on your machine — no screen data is sent to external servers. All tool calls are audit-logged. See our [Security Policy](SECURITY.md) for details on permissions and boundaries.
+</details>
 
-### Is ScreenHand safe to use?
-ScreenHand runs locally and never sends screen data to external servers. Dangerous tools (AppleScript, browser JS execution) are audit-logged. You control which AI client connects to it via MCP configuration.
+<details>
+<summary><strong>What AI clients work with it?</strong></summary>
 
-### Can ScreenHand control any application?
-On macOS, it can control any app that exposes Accessibility elements (most apps do). On Windows, it works with any app that supports UI Automation. Some apps with custom rendering (games, some Electron apps) may have limited element tree support — use OCR as a fallback.
+Any MCP-compatible client: Claude Desktop, Claude Code, Cursor, Windsurf, OpenAI Codex CLI, and more.
+</details>
 
-### How fast is ScreenHand?
-Accessibility/UI Automation operations take ~50ms. Chrome CDP operations take ~10ms. Screenshots with OCR take ~600ms. Memory lookups add ~0ms (in-memory cache). ScreenHand is significantly faster than screenshot-only approaches because it reads the UI tree directly.
+<details>
+<summary><strong>Can it control any app?</strong></summary>
 
-### Does the learning memory affect performance?
-No. All memory data is loaded into RAM at startup. Lookups are O(1) hash map reads. Disk writes are async and buffered — they never block tool responses. The memory system adds effectively zero latency to any tool call.
-
-### Is the memory data safe from corruption?
-Yes. JSONL files are parsed line-by-line — a single corrupted line is skipped without affecting other entries. File locking prevents concurrent write corruption. Pending writes are flushed synchronously on exit (SIGINT/SIGTERM). Cache sizes are capped with LRU eviction to prevent unbounded growth.
+On macOS, any app that exposes Accessibility elements (most do). On Windows, any app supporting UI Automation. For apps with custom rendering (games, some Electron apps), OCR is available as a fallback.
+</details>
 
 ## Contributing
 
-Contributions are welcome! Please open an issue first to discuss what you'd like to change.
+Contributions welcome! Please open an issue first to discuss what you'd like to change.
 
 ```bash
 git clone https://github.com/manushi4/screenhand.git
 cd screenhand
-npm install
-npm run build:native
-npm test
+npm install && npm run build:native && npm test
 ```
 
 ## License
 
-MIT
+[AGPL-3.0](LICENSE) — Copyright (C) 2025 Clazro Technology Private Limited
 
 ---
 
 <div align="center">
 
-**[screenhand.com](https://screenhand.com)** | Built by [Khushi Singhal](https://github.com/manushi4) | A product of **Clazro Technology Private Limited**
+**[screenhand.com](https://screenhand.com)** | Built by **[Clazro Technology Private Limited](https://github.com/manushi4)**
 
 </div>

package/SECURITY.md

@@ -0,0 +1,44 @@
+# Security Policy
+
+## Overview
+
+ScreenHand is a desktop automation tool with significant system access. We take security seriously.
+
+## What ScreenHand Can Access
+
+- **Screen content** via screenshots and OCR
+- **UI elements** via native Accessibility APIs (macOS) / UI Automation (Windows)
+- **Keyboard and mouse** input simulation
+- **Chrome browser** tabs via DevTools Protocol (requires Chrome launched with debug port)
+- **AppleScript** execution (macOS only)
+
+## What ScreenHand Cannot Do
+
+- ScreenHand does **not** send screen data or any information to external servers
+- It does **not** access browser cookies, passwords, or stored credentials
+- It does **not** run with elevated/admin privileges
+- It does **not** modify system settings or install background services
+- It does **not** communicate with any remote server (all operations are local)
+
+## Permissions Required
+
+### macOS
+- **Accessibility permission**: System Settings > Privacy & Security > Accessibility > enable your terminal app
+- This is a standard macOS requirement for any app that reads UI elements or simulates input
+
+### Windows
+- No special permissions needed — UI Automation works without admin for most applications
+
+## Audit Logging
+
+All tool calls are logged to `.audit-log.jsonl` with timestamps. This file is gitignored by default and stays on your machine.
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please email **security@screenhand.com** instead of opening a public issue.
+
+We will acknowledge receipt within 48 hours and aim to provide a fix within 7 days for critical issues.
+
+## Responsible Use
+
+ScreenHand is designed for legitimate automation, testing, and productivity use cases. Users are responsible for ensuring their use complies with applicable laws and the terms of service of any applications they automate.

package/docs/architecture.md

@@ -0,0 +1,47 @@
+# MVP Architecture
+
+## Design Goals
+- Fast execution by keeping session and context persistent.
+- Predictable completion by hard action budgets.
+- No infinite loops: each tool call returns success or structured failure.
+- LLM plans high-level intent; runtime handles micro-logic.
+
+## Layers
+1. `MCP Server Layer`
+- Accepts tool requests (`session_start`, `navigate`, `press`, `type_into`, `wait_for`, `extract`, `screenshot`).
+- Validates args and forwards to runtime service.
+
+2. `Runtime Service Layer`
+- Orchestrates session manager, executor, adapter, logging, and cache.
+- Converts low-level errors into structured failure payloads.
+
+3. `Executor Layer`
+- Runs bounded state machine for action tools:
+  - locate (cached first, fallback strategy)
+  - act
+  - verify
+  - optional retry
+- Enforces per-step time budgets.
+
+4. `Browser Adapter Layer`
+- Thin contract for browser operations.
+- Current scaffold uses a placeholder adapter; later replace with CDP or Playwright robot-mode adapter.
+
+## Core Runtime Flow
+1. `session_start(profile)` ensures a persistent session ID.
+2. `navigate(url)` completes within timeout and returns url/title.
+3. `press` / `type_into` run bounded loop with max retries.
+4. `wait_for(condition)` waits only for explicit UI conditions.
+5. `extract(target, format)` returns structured data.
+6. On failure, return structured diagnostics + timings.
+
+## Key Data Contracts
+- `ActionBudget`: `locateMs`, `actMs`, `verifyMs`, `maxRetries`.
+- `ActionTelemetry`: per-action timing + retry count + status.
+- `RuntimeError`: error code, attempts, page meta, and cause.
+
+## Next Implementation Phase
+- Harden the current CDP adapter with richer locator heuristics and cleanup hooks.
+- Add locator strategy expansion (role/text/selector priority + fuzzy fallback).
+- Persist locator cache per site/action.
+- Wire transport for actual MCP protocol endpoint.

package/install-skills.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Install ScreenHand skills globally for Claude Code
+# Usage: ./install-skills.sh
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+TARGET="$HOME/.claude/commands"
+
+mkdir -p "$TARGET"
+
+cp "$SCRIPT_DIR/.claude/commands/screenshot.md" "$TARGET/desktop-screenshot.md"
+cp "$SCRIPT_DIR/.claude/commands/debug-ui.md" "$TARGET/desktop-debug-ui.md"
+cp "$SCRIPT_DIR/.claude/commands/automate.md" "$TARGET/desktop-automate.md"
+
+echo "Installed skills to $TARGET:"
+echo "  /desktop-screenshot  — capture and describe your screen"
+echo "  /desktop-debug-ui    — inspect any app's UI tree"
+echo "  /desktop-automate    — automate a multi-step workflow"
+echo ""
+echo "These are now available globally in any Claude Code session."