Upload folder using huggingface_hub

.devcontainer/devcontainer.json

@@ -0,0 +1,15 @@
+{
+  "name": "PinchTab",
+  "image": "mcr.microsoft.com/devcontainers/go:1.23",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+  },
+  "postCreateCommand": "docker compose up -d && go build -o pinchtab ./cmd/pinchtab && echo 'Done! Run: ./pinchtab health'",
+  "forwardPorts": [9867],
+  "portsAttributes": {
+    "9867": {
+      "label": "PinchTab",
+      "onAutoForward": "notify"
+    }
+  }
+}

.dockerignore

@@ -0,0 +1,42 @@
+# Binaries
+pinchtab
+browser-bridge
+
+# Test coverage
+coverage.out
+*.test
+
+# Git
+.git/
+.github/
+
+# Tests (E2E fixtures, scenarios, results)
+tests/
+
+# Local state
+.pinchtab/
+.openclaw/
+
+# macOS
+.DS_Store
+
+# Editor
+.vscode/
+*.swp
+
+# Docs (not needed in image)
+docs/
+
+# Development
+node_modules/
+dashboard/node_modules/
+*.log
+
+# Build caches
+.gocache/
+.gomodcache/
+tmp/
+
+# Markdown (README, RELEASE, etc.)
+*.md
+!dashboard/**/*.md

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+assets/pinchtab-headless.png filter=lfs diff=lfs merge=lfs -text
+docs/media/chart-redesign-preview.png filter=lfs diff=lfs merge=lfs -text
+docs/media/dashboard-instances.jpeg filter=lfs diff=lfs merge=lfs -text
+docs/media/dashboard-settings.jpeg filter=lfs diff=lfs merge=lfs -text

.github/DEFINITION_OF_DONE.md

@@ -0,0 +1,53 @@
+# Definition of Done (PR Checklist)
+
+## Automated ✅ (CI/GitHub enforces these)
+These run automatically via `ci.yml`. If your PR fails them, fix and re-push.
+- [ ] Go formatting & linting passes (gofmt, vet, golangci-lint)
+- [ ] Unit + E2E tests pass (`go test ./...` and `./dev e2e`)
+- [ ] Build succeeds (`go build`)
+- [ ] CodeQL security scan passes
+- [ ] Branch naming follows convention
+
+## Manual — Code Quality (Required)
+- [ ] **Error handling explicit** — All errors wrapped with `%w`, no silent failures
+- [ ] **No regressions** — Verify stealth, token efficiency, session persistence work (test locally if unsure)
+- [ ] **SOLID principles** — Functions do one thing, testable, no unnecessary deps
+- [ ] **No redundant comments** — Comments explain *why* or *context*, not *what* the code does
+  - ❌ Bad: `// Loop through items` above `for _, item := range items`
+  - ❌ Bad: `// Return error` above `return err`
+  - ✅ Good: `// Prioritize chromium-browser on ARM64 (Raspberry Pi default)`
+  - ✅ Good: `// Chrome may not be installed in CI, so empty result is valid`
+
+## Manual — Testing (Required)
+- [ ] **New/changed functionality has tests** — Same-package unit tests preferred
+- [ ] **Docker E2E tests run locally** — If you modified handlers/bridge/tabs, run: `./dev e2e` (Docker curl E2E) and/or `./dev e2e cli` (Docker CLI E2E)
+- [ ] **npm commands work** (if npm wrapper touched):
+  - `npm pack` in `/npm/` produces valid tarball
+  - `npm install -g pinchtab` (or from local tarball) succeeds
+  - `pinchtab --version` + basic commands work after install
+
+## Manual — Documentation (Required)
+- [ ] **README.md updated** — If user-facing changes (CLI, API, env vars, install)
+- [ ] **/docs/ updated** — If API/architecture/perf changed (optional for small fixes)
+
+## Manual — Review (Required)
+- [ ] **PR description explains what + why** — Especially stealth/perf/compatibility impact
+- [ ] **Commits are atomic** — Logical grouping, good messages
+- [ ] **No breaking changes to npm** — Unless explicitly major version bump
+
+## Conditional (Only if applicable)
+- [ ] Headed-mode tested (if dashboard/UI changes)
+- [ ] Breaking changes documented in PR description (if any)
+
+---
+
+## Quick Checklist (Copy/Paste for PRs)
+```markdown
+## Definition of Done
+- [ ] Unit + Docker E2E tests added & passing
+- [ ] Error handling explicit (wrapped with %w)
+- [ ] No regressions in stealth/perf/persistence
+- [ ] No redundant comments (explain why, not what)
+- [ ] README/docs updated (if user-facing)
+- [ ] npm install works (if npm changes)
+```

.github/DOCUMENTATION_REVIEW.md

@@ -0,0 +1,398 @@
+# Documentation Review Guide
+
+## Purpose
+
+Code is the source of truth. This guide helps agents audit, validate, and maintain documentation to ensure it stays in sync with the codebase.
+
+Use this document when asking agents to review documentation for accuracy, completeness, and consistency.
+
+---
+
+## Quick Summary
+
+When asked to review documentation, an agent should:
+
+1. **Verify all examples match current code behavior**
+2. **Check doc structure against actual codebase**
+3. **Update or remove outdated content**
+4. **Report findings and improvements**
+
+---
+
+## Detailed Review Process
+
+### Phase 1: Code-to-Docs Validation
+
+#### 1.1 Check All Examples
+
+For **every code example** in `/docs`:
+
+- [ ] **Run the example** (if it's executable)
+  - Does it produce the expected output?
+  - Does it work with current API/CLI?
+  - Are environment variables correct?
+
+- [ ] **Verify API endpoints**
+  - Do endpoints still exist? (`GET /snapshot`, `POST /action`, etc.)
+  - Do request/response formats match?
+  - Are all parameters documented?
+  - Are deprecated endpoints removed?
+
+- [ ] **Verify CLI commands**
+  - Do commands still exist? (`pinchtab config set`, `pinchtab health`, etc.)
+  - Do they work as documented?
+  - Are flags/options correct?
+  - Are deprecated commands removed?
+
+- [ ] **Verify configuration values**
+  - Do env vars still exist? (`CHROME_EXTENSION_PATHS`, `BRIDGE_PORT`, etc.)
+  - Are default values correct?
+  - Are deprecated config options removed?
+
+#### 1.2 Check Content Accuracy
+
+For **every paragraph, section, and claim** in `/docs`:
+
+- [ ] **API behavior** — Does it accurately describe current behavior?
+- [ ] **Performance notes** — Are benchmarks/timings still valid?
+- [ ] **Stealth/security claims** — Do they match current implementation?
+- [ ] **Feature availability** — Is feature still implemented?
+- [ ] **Limitations** — Are noted limitations still present?
+- [ ] **Requirements** — Are tool versions, Chrome versions, etc. correct?
+
+#### 1.3 Cross-Check Against Code
+
+Use the code as reference:
+
+```
+For each doc section:
+1. Find the corresponding code file(s)
+2. Compare doc description with actual implementation
+3. If different → docs are WRONG
+4. If missing → docs are INCOMPLETE
+5. If outdated → docs are STALE
+```
+
+**Example:**
+- Doc says: "fill action with refs sets the input value"
+- Code says: `FillByNodeID()` exists → docs are CORRECT ✅
+- Code says: no `FillByNodeID()` → docs are WRONG ❌
+
+---
+
+### Phase 2: Structure Review
+
+#### 2.1 Check Documentation Structure
+
+**File structure should match codebase organization:**
+
+```
+docs/
+├── api/
+│   ├── endpoints/
+│   │   ├── navigation.md
+│   │   ├── snapshot.md
+│   │   ├── actions.md
+│   │   ├── find.md
+│   │   ├── evaluate.md
+│   │   └── ...
+│   └── ...
+├── cli/
+│   ├── management.md
+│   ├── config.md
+│   └── ...
+├── architecture/
+│   └── ...
+└── index.json
+```
+
+**Verify:**
+- [ ] All major API endpoints documented?
+- [ ] All CLI commands documented?
+- [ ] Organization makes sense?
+- [ ] Groups reflect actual functionality?
+- [ ] No duplicate content?
+- [ ] No orphaned docs (not linked from index)?
+
+#### 2.2 Check index.json
+
+**Verify index.json structure:**
+
+```json
+{
+  "sections": [
+    {
+      "title": "API",
+      "path": "api/",
+      "items": [
+        {
+          "title": "Endpoints",
+          "path": "api/endpoints/",
+          "items": [
+            { "title": "Navigation", "path": "api/endpoints/navigation.md" },
+            { "title": "Snapshot", "path": "api/endpoints/snapshot.md" },
+            ...
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Checks:**
+- [ ] All sections map to actual directories?
+- [ ] All items map to actual files?
+- [ ] No broken paths?
+- [ ] Nesting depth reasonable (not too deep)?
+- [ ] Titles are accurate and clear?
+- [ ] Order makes sense (API before examples)?
+
+---
+
+### Phase 3: Report Findings
+
+#### If Changes Were Made
+
+**Create a PR with:**
+
+1. **Summary of fixes**
+   ```markdown
+   ## Documentation Fixes
+
+   - Updated /docs/api/endpoints/fill.md to document FillByNodeID support (fixes #114)
+   - Removed deprecated /docs/api/endpoints/old-nav.md (no longer exists in code)
+   - Fixed /docs/cli/config.md examples to use new config set syntax
+   - Updated Chrome requirement from 144 to 145+ for extension support
+   ```
+
+2. **List of possible improvements** (as comments in PR)
+   ```markdown
+   ## Suggested Improvements
+
+   - [ ] /docs/architecture/ could use a "bridge lifecycle" diagram
+   - [ ] /docs/api/endpoints/actions.md could add more examples
+   - [ ] /docs/cli/config.md could show YAML format examples
+   ```
+
+3. **PR description**
+   ```markdown
+   ## Documentation Review — Code Alignment
+
+   Verified all examples, API endpoints, CLI commands, and config values against current code.
+
+   ### Changes Made
+   - X examples updated to match current API
+   - X endpoints documented/updated
+   - X CLI commands verified
+   - X deprecated content removed
+
+   ### No Changes Needed
+   - API behavior accurate
+   - Structure organized
+   - Examples working
+
+   ### Improvements Suggested
+   See comments in PR for enhancement requests.
+   ```
+
+#### If No Changes Needed but Improvements Found
+
+**Create a GitHub issue:**
+
+```markdown
+Title: docs: enhancement - add examples for [feature]
+
+Body:
+## Suggestion
+
+The documentation could be improved by:
+
+1. Adding example for feature X (current docs only show basic usage)
+2. Adding "Common Patterns" section to endpoint Y
+3. Adding troubleshooting section to CLI guide
+
+## Reasoning
+
+Users asking "how do I..." suggests these are common use cases.
+
+## References
+
+- See /docs/api/endpoints/[endpoint].md
+- See /docs/cli/[command].md
+```
+
+---
+
+## Checklist for Agents
+
+When given the task "Review documentation", verify:
+
+### Code Accuracy
+- [ ] All examples are tested and working
+- [ ] All API endpoints documented correctly
+- [ ] All CLI commands documented correctly
+- [ ] All config options documented correctly
+- [ ] No deprecated content remains
+- [ ] All current features documented
+
+### Structure
+- [ ] index.json paths are correct
+- [ ] Directory structure makes sense
+- [ ] No orphaned docs
+- [ ] Grouping still makes sense
+- [ ] Navigation depth reasonable
+
+### Output
+- [ ] If changes: Create PR with summary + improvements list
+- [ ] If no changes but improvements: Create GitHub issue with enhancement request
+- [ ] Always: Note which docs were spot-checked and results
+
+---
+
+## Common Documentation Mistakes to Fix
+
+❌ **Outdated examples:**
+```bash
+# OLD (deprecated)
+pinchtab nav https://pinchtab.com   # ← This command was removed
+
+# NEW (correct)
+curl -X POST http://localhost:9867/navigate \
+  -d '{"url":"https://pinchtab.com"}'
+```
+
+❌ **Wrong API format:**
+```javascript
+// OLD (incorrect)
+response = await fetch('/action', {
+  body: JSON.stringify({action: 'click', ref: 'e5'})
+})
+
+// NEW (correct)
+response = await fetch('/action', {
+  body: JSON.stringify({kind: 'click', ref: 'e5'})
+})
+```
+
+❌ **Missing new features:**
+```markdown
+<!-- Missing in docs -->
+<!-- Code has FillByNodeID support for fills with refs -->
+<!-- Docs should say: "fill supports both selectors and refs" -->
+```
+
+❌ **Incorrect config examples:**
+```bash
+# OLD (deprecated env var name)
+export BRIDGE_NAV_TIMEOUT=30
+
+# NEW (correct)
+export PINCHTAB_NAVIGATE_TIMEOUT=30
+```
+
+---
+
+## Documentation File Locations
+
+**Root docs location:** `/docs`
+
+**Key files to check:**
+
+- `/docs/index.json` — Navigation/structure
+- `/docs/README.md` — Overview
+- `/docs/api/endpoints/*.md` — API documentation
+- `/docs/cli/*.md` — CLI documentation
+- `/docs/configuration.md` — Configuration reference
+- `/docs/architecture/*.md` — Architecture/design docs
+- `/docs/examples/*.md` — Usage examples
+
+---
+
+## When to Ask for Documentation Review
+
+**Ask for review:**
+- After major feature additions (new endpoints, CLI commands)
+- After refactoring (config structure changes, API changes)
+- After bug fixes affecting documented behavior
+- Periodically (every quarter) for general sync-up
+- Before major releases (ensure nothing is stale)
+
+**Example requests:**
+
+> "Review documentation against current code. Check all API examples, CLI commands, and config values. Update docs to match code or remove outdated content. Create a PR with a summary of changes."
+
+> "Audit /docs for accuracy. Update any incorrect examples, remove deprecated features, fix broken index.json paths. Create an issue with improvement suggestions if no changes needed."
+
+---
+
+## Quality Gates
+
+A documentation review is **complete** when:
+
+✅ All examples are tested and working
+✅ All API endpoints match code implementation
+✅ All CLI commands match code implementation
+✅ All config options match code implementation
+✅ No deprecated content remains
+✅ index.json structure is accurate
+✅ Documentation structure reflects codebase
+✅ Either: PR with fixes submitted, OR Issue with improvements created
+
+---
+
+## Example Review Output (PR)
+
+```markdown
+## Documentation Review — Code Alignment
+
+All examples, endpoints, and CLI commands verified against current codebase.
+
+### ✅ Changes Made (3 files)
+
+1. **docs/api/endpoints/actions.md**
+   - Updated fill example to show ref support (new in PR #119)
+   - Added FillByNodeID code path documentation
+
+2. **docs/cli/config.md**
+   - Fixed config set examples (new syntax with PR #120)
+   - Added YAML output format example
+
+3. **docs/api/endpoints/find.md**
+   - Added Find endpoint documentation (new in feat/allocation-strategies)
+
+### ✅ Verified (No Changes Needed)
+
+- All navigate endpoint examples working
+- All snapshot filters documented correctly
+- All action kinds (click, type, press, etc.) verified
+- Config sections (server, chrome, orchestrator) accurate
+- Environment variable names current
+
+### 💡 Suggested Improvements
+
+See comments below for enhancement requests (low priority):
+- [ ] Add "common patterns" section to actions.md
+- [ ] Add troubleshooting FAQ to cli/config.md
+- [ ] Create /docs/examples/multi-step-workflow.md
+
+### Review Stats
+
+- Examples tested: 12/12 ✅
+- Endpoints checked: 8/8 ✅
+- CLI commands checked: 5/5 ✅
+- Config sections checked: 4/4 ✅
+- Deprecated content found: 0 ✅
+- Structure issues found: 0 ✅
+```
+
+---
+
+## Related Documents
+
+- [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) — PR checklist
+- [LABELING_GUIDE.md](./LABELING_GUIDE.md) — Issue labeling guide
+
+---
+
+Last updated: 2026-03-04

.github/GOVERNANCE.md

@@ -0,0 +1,85 @@
+# GitHub Governance Documents
+
+This directory contains pinchtab's governance and workflow documents referenced by developers and automated agents.
+
+## Documents
+
+### [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md)
+**Purpose:** PR checklist for code quality, testing, and documentation before merging.
+
+**For:** All contributors submitting PRs
+**How to use:** Check this list before submitting a PR, or ask agents to verify PRs against it.
+
+**Key sections:**
+- Automated checks (CI enforces)
+- Manual code quality requirements
+- Testing requirements
+- Documentation requirements
+- Quick checklist for copy/paste
+
+---
+
+### [LABELING_GUIDE.md](./LABELING_GUIDE.md)
+**Purpose:** Reference guide for issue and PR labeling to maintain consistent triage.
+
+**For:** Maintainers triaging issues, agents reviewing tickets
+**How to use:** Point agents to this guide when asking them to review and label open issues.
+
+**Key sections:**
+- 3-tier labeling system (Type → Status → Priority)
+- Decision tree for triage
+- Guidelines for agents
+- Examples of well-labeled issues
+- Common mistakes to avoid
+
+---
+
+### [DOCUMENTATION_REVIEW.md](./DOCUMENTATION_REVIEW.md)
+**Purpose:** Guide for auditing documentation to ensure it stays in sync with code (code is source of truth).
+
+**For:** Agents maintaining documentation, quality assurance
+**How to use:** Point agents to this guide when asking them to audit docs for accuracy and consistency.
+
+**Key sections:**
+- Code-to-docs validation (examples, endpoints, commands, config)
+- Structure review (organization, index.json, grouping)
+- Output requirements (PR with fixes or GitHub issue with improvements)
+- Common documentation mistakes to fix
+- Quality gates for completion
+
+---
+
+## Quick Reference
+
+| Document | Audit For | Used By |
+|----------|-----------|---------|
+| DEFINITION_OF_DONE.md | PR quality before merge | Developers, agents, reviewers |
+| LABELING_GUIDE.md | Consistent issue triage | Maintainers, agents |
+| DOCUMENTATION_REVIEW.md | Documentation accuracy vs code | Agents, QA |
+
+---
+
+## How Agents Use These
+
+When asking an agent to help with PRs, issues, or documentation:
+
+**For PR review:**
+> "Review this PR against `.github/DEFINITION_OF_DONE.md` and ensure it meets all requirements."
+
+**For issue triage:**
+> "Review open issues and apply labels according to `.github/LABELING_GUIDE.md`. Ensure Type + Status + Priority are consistent."
+
+**For documentation audit:**
+> "Review documentation against current code using `.github/DOCUMENTATION_REVIEW.md`. Verify all examples match code, update or remove outdated content, report changes in a PR or improvements in a GitHub issue."
+
+---
+
+## Maintenance
+
+- **DEFINITION_OF_DONE.md** — Update when code quality standards change
+- **LABELING_GUIDE.md** — Update when new labels are added or workflow changes
+- This **README.md** — Update when new governance documents are added
+
+---
+
+Last updated: 2026-03-04

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Start Pinchtab with `...`
+2. Send request to `/...` with body `...`
+3. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots/Logs**
+If applicable, add screenshots or console output to help explain your problem.
+
+**Environment (please complete the following information):**
+ - OS: [e.g. macOS, Ubuntu]
+ - Browser Version: [e.g. Chrome 120]
+ - Go Version: [e.g. 1.25.0]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/LABELING_GUIDE.md

@@ -0,0 +1,246 @@
+# Labeling Guide
+
+This document describes the labeling system used for issues and PRs in pinchtab. Use this guide when triaging tickets or asking agents to review open issues.
+
+---
+
+## Quick Reference
+
+Every issue should have:
+1. **Exactly one Type label** (bug, enhancement, documentation, question, etc.)
+2. **One Status label** (ready, in-progress, blocked, fixed-unreleased, needs-investigation)
+3. **One Priority label** (high, medium, low) — optional for documentation or questions
+
+---
+
+## Tier 1: Issue Type (Mandatory)
+
+Choose **exactly one**:
+
+| Label | Color | Usage |
+|-------|-------|-------|
+| `bug` | 🔴 Red | Something isn't working correctly |
+| `enhancement` | 🔵 Cyan | New feature or capability request |
+| `documentation` | 🔵 Blue | Improvements/additions to README, docs, or code comments |
+| `question` | 🟣 Purple | Request for clarification or information |
+| `good first issue` | 🟣 Purple | Good for newcomers (in addition to type label) |
+| `help wanted` | 🟢 Green | Needs extra attention or expertise |
+| `dependencies` | 🔵 Blue | Dependency updates (PR label) |
+| `invalid` | 🟡 Yellow | Doesn't seem right; requires clarification |
+| `duplicate` | ⚪ Gray | Already exists (close and reference original) |
+| `wontfix` | ⚪ White | Deliberate decision not to fix |
+
+### Examples
+
+- **Bug:** "fill action silently no-ops when using refs" → `bug`
+- **Enhancement:** "Add CHROME_EXTENSION_PATHS support" → `enhancement`
+- **Documentation:** "Update README with new CLI commands" → `documentation`
+- **Question:** "How do I configure stealth mode?" → `question`
+
+---
+
+## Tier 2: Status (Recommended)
+
+Choose **one** to show current state:
+
+| Label | Color | Meaning | When to Use |
+|-------|-------|---------|------------|
+| `status: ready` | 🔵 Blue | Ready to start work | Issue is fully understood, no blockers, waiting for someone to pick it up |
+| `status: in-progress` | 🟡 Yellow | Actively being worked on | Someone has claimed the issue and is working on a fix/feature |
+| `status: blocked` | 🔴 Red | Blocked by something | Waiting on external dependency, another issue, or decision |
+| `status: fixed-unreleased` | 🟢 Green | Fix merged, not in release | PR is merged but feature/fix isn't in a released version yet |
+| `status: needs-investigation` | 🔴 Red | Needs debugging/research | Not enough info; requires investigation before work can start |
+
+### Workflow
+
+```
+New Issue
+    ↓
+[Triage] Add Type + Status
+    ↓
+status: needs-investigation (if unclear) or status: ready (if clear)
+    ↓
+Developer picks it up
+    ↓
+status: in-progress
+    ↓
+PR submitted
+    ↓
+PR merged
+    ↓
+status: fixed-unreleased (for bugs) or remove status (for features)
+    ↓
+Release cut
+    ↓
+Remove status label (feature is released)
+```
+
+---
+
+## Tier 3: Priority (Optional, for bugs/enhancements)
+
+Choose **one** to indicate urgency:
+
+| Label | Color | Level | When to Use |
+|-------|-------|-------|------------|
+| `priority: high` | 🔴 Red | Critical; blocks users | Security vulnerability, critical bug, high-demand feature |
+| `priority: medium` | 🟡 Yellow | Normal; important for roadmap | Important bug or feature; should be done soon |
+| `priority: low` | 🟢 Green | Nice to have; can defer | Minor improvement, polish, or edge case |
+
+### Examples
+
+- **High:** "SafePath() fails to block path traversal" (security) → `bug` + `priority: high`
+- **Medium:** "Snapshot doesn't work inside iframes" (affects users) → `bug` + `priority: medium`
+- **Low:** "Consider migrating to PINCHTAB_* env vars" (nice refactor) → `enhancement` + `priority: low`
+
+---
+
+## Special Labels
+
+### `good first issue`
+Add this **in addition to the type label** for issues that are good entry points for new contributors.
+
+**Criteria:**
+- Clear problem statement
+- Solution is straightforward
+- Doesn't require deep knowledge of codebase
+- Estimated effort: <4 hours
+
+**Example:** "documentation: Add /find endpoint example to README" → `documentation` + `good first issue`
+
+### `help wanted`
+Indicates the issue needs expertise or has been stalled.
+
+**When to use:**
+- Needs specific expertise (e.g., "needs Windows testing")
+- Issue has been open >2 weeks without progress
+- Complex problem that benefits from external input
+
+---
+
+## Decision Tree for Triage
+
+```
+New issue arrives
+    ↓
+1. Is it a valid issue?
+   NO  → `invalid` + close
+   YES ↓
+2. What is it?
+   → Bug? `bug` + assess severity → `priority: high|medium|low`
+   → New feature? `enhancement` + assess importance → `priority: high|medium|low`
+   → Docs missing? `documentation` + no priority needed
+   → Unclear? `question` + no priority needed
+   ↓
+3. Can we start work immediately?
+   YES → `status: ready`
+   NO  ↓
+4. Why not?
+   → Need info → `status: needs-investigation`
+   → Waiting on something → `status: blocked`
+   → Already fixed → `status: fixed-unreleased`
+```
+
+---
+
+## Guidelines for Agents
+
+When reviewing open issues, follow this checklist:
+
+- [ ] **Each issue has exactly one Type label** (bug, enhancement, documentation, question)
+- [ ] **Bugs have Priority labels** (high, medium, low)
+- [ ] **Enhancements have Priority labels** (high, medium, low)
+- [ ] **Each issue has a Status label** (ready, in-progress, blocked, fixed-unreleased, needs-investigation)
+- [ ] **No duplicate labels** (e.g., two type labels on one issue)
+- [ ] **Status matches reality** (e.g., `status: in-progress` has an active PR)
+- [ ] **Stale issues reviewed** (e.g., `status: blocked` for >2 weeks should note why)
+
+---
+
+## Current Label Inventory
+
+**Type labels (10):**
+- bug, enhancement, documentation, question, good first issue, help wanted, dependencies, invalid, duplicate, wontfix
+
+**Status labels (5):**
+- status: ready, status: in-progress, status: blocked, status: fixed-unreleased, status: needs-investigation
+
+**Priority labels (3):**
+- priority: high, priority: medium, priority: low
+
+**Code labels (1):**
+- javascript
+
+---
+
+## Examples of Well-Labeled Issues
+
+### Example 1: Security Bug
+```
+Title: SafePath() fails to block path traversal on Windows
+Labels: bug, priority: high, status: ready
+```
+**Why:** Critical security issue, ready to work on, high priority.
+
+### Example 2: Feature Request (Ready)
+```
+Title: feat: Resource Pool with pluggable allocation strategies
+Labels: enhancement, priority: medium, status: ready
+```
+**Why:** Enhancement, medium priority (important for roadmap), ready to start.
+
+### Example 3: Feature (Blocked)
+```
+Title: feat: Semantic Element Selection via NLP (/find endpoint)
+Labels: enhancement, priority: medium, status: blocked
+```
+**Why:** Enhancement, medium priority, but blocked (perhaps waiting on design decision).
+
+### Example 4: Bug (Not Ready)
+```
+Title: click and humanClick fail to trigger Bootstrap dropdown
+Labels: bug, priority: medium, status: needs-investigation
+```
+**Why:** Bug, medium priority, but needs investigation (reproduction steps unclear).
+
+### Example 5: Already Fixed
+```
+Title: Installation issue
+Labels: bug, priority: high, status: fixed-unreleased
+```
+**Why:** Critical bug, but fix is already merged and waiting for release.
+
+---
+
+## Common Mistakes
+
+❌ **Don't do this:**
+
+| Mistake | Why | Fix |
+|---------|-----|-----|
+| Two Type labels on one issue | Ambiguous; what is it really? | Choose one type only |
+| Status label on closed issue | Status should reflect open work | Remove status label when closing |
+| No Priority on bugs | Can't triage effectively | Add priority: high/medium/low to all bugs |
+| `status: in-progress` with no PR | Misleading; is someone actually working on it? | Only use when work is actively underway |
+| Forgetting Status labels | No visibility into progress | Always add a status label during triage |
+
+---
+
+## Related Documents
+
+- [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) — Checklist for PRs before merge
+- [CONTRIBUTING.md](../CONTRIBUTING.md) — Contribution guidelines (if present)
+
+---
+
+## Last Updated
+
+2026-03-04
+
+---
+
+## Summary
+
+**For agents:** Use this guide to understand and apply labels when triaging issues. Ensure every issue has Type + Status + Priority (if applicable).
+
+**For maintainers:** Review labels during triage and ensure consistency. Use the Decision Tree above as a quick reference.

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,30 @@
+## What Changed?
+<!-- Brief description of the change -->
+
+## Why?
+<!-- Motivation, issue being fixed, or feature request -->
+
+## Testing
+<!-- How did you test this? Include command examples if applicable -->
+
+- [ ] Unit and/or Docker E2E tests added or updated
+- [ ] Manual testing completed (describe below)
+
+## Checklist
+See [DEFINITION_OF_DONE.md](./DEFINITION_OF_DONE.md) for the full checklist.
+
+**Automated (CI enforces):**
+- [ ] gofmt + golangci-lint passes
+- [ ] All tests pass
+- [ ] Build succeeds
+
+**Manual:**
+- [ ] Error handling explicit (wrapped with `%w`)
+- [ ] No regressions in stealth/performance/persistence
+- [ ] README/CHANGELOG updated (if user-facing)
+- [ ] npm install works (if npm changes)
+
+## Impact
+<!-- Any performance, compatibility, or breaking changes? -->
+
+---

.github/RELEASING.md

@@ -0,0 +1,44 @@
+# Releasing PinchTab
+
+This is the release checklist for the GitHub tag-driven release pipeline.
+
+## One-time setup
+
+- Create the public tap repository `pinchtab/homebrew-tap`.
+- Add the `HOMEBREW_TAP_GITHUB_TOKEN` Actions secret to `pinchtab/pinchtab`.
+- The token must have write access to `pinchtab/homebrew-tap`.
+
+## What the release workflow does
+
+Pushing a tag like `v0.7.0` triggers [release.yml](/Users/luigi/dev/prj/giago/pt-bosch/.github/workflows/release.yml), which:
+
+1. Builds release binaries and creates the GitHub release via GoReleaser.
+2. Publishes the npm package.
+3. Builds and publishes container images.
+4. Generates a Homebrew formula PR against `pinchtab/homebrew-tap`.
+
+## Release steps
+
+1. Verify the branch you want to release is merged to `main`.
+2. Push the release tag:
+
+```bash
+git tag v0.7.0
+git push origin v0.7.0
+```
+
+3. Watch the `Release` workflow in GitHub Actions.
+4. Confirm GoReleaser opens a PR in `pinchtab/homebrew-tap`.
+5. Merge that PR.
+
+After the tap PR is merged, users can install with:
+
+```bash
+brew install pinchtab/tap/pinchtab
+```
+
+## Notes
+
+- The Homebrew formula is not published until the tap PR is merged.
+- No extra automation is required in `homebrew-tap` unless you want auto-merge.
+- The release workflow can also be run manually with `workflow_dispatch` and a tag input.

.github/workflows/branch-naming.yml

@@ -0,0 +1,50 @@
+name: Branch Naming
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+
+jobs:
+  check-branch-name:
+    name: Branch Name Convention
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    steps:
+      - name: Check branch name
+        run: |
+          BRANCH="${GITHUB_HEAD_REF}"
+          echo "Branch: $BRANCH"
+
+          # Allow long-running branches
+          if [[ "$BRANCH" =~ ^(main|develop|staging)$ ]]; then
+            echo "✅ Long-running branch: $BRANCH"
+            exit 0
+          fi
+
+          # Allow dependabot branches
+          if [[ "$BRANCH" =~ ^dependabot/ ]]; then
+            echo "✅ Dependabot branch: $BRANCH"
+            exit 0
+          fi
+
+          # Enforce prefix/description pattern
+          PATTERN="^(feature|feat|fix|hotfix|docs|chore|refactor|test)/[a-z0-9][a-z0-9-]*$"
+          if [[ ! "$BRANCH" =~ $PATTERN ]]; then
+            echo "❌ Branch name '$BRANCH' doesn't match convention."
+            echo ""
+            echo "Expected format: <prefix>/<description>"
+            echo "  Prefixes: feature, feat, fix, hotfix, docs, chore, refactor, test"
+            echo "  Description: lowercase, hyphens, no special chars"
+            echo ""
+            echo "Examples:"
+            echo "  feature/42-add-search-filter"
+            echo "  fix/chrome-orphan-cleanup"
+            echo "  hotfix/critical-api-fix"
+            echo "  docs/update-docker-guide"
+            exit 1
+          fi
+
+          echo "✅ Branch name '$BRANCH' follows convention."

.github/workflows/dashboard.yml

@@ -0,0 +1,107 @@
+name: Dashboard
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'dashboard/**'
+      - 'internal/api/types/**'
+      - 'scripts/build-dashboard.sh'
+      - '.github/workflows/dashboard.yml'
+  pull_request:
+    paths:
+      - 'dashboard/**'
+      - 'internal/api/types/**'
+      - 'scripts/build-dashboard.sh'
+      - '.github/workflows/dashboard.yml'
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    working-directory: dashboard
+
+jobs:
+  check:
+    name: Lint, Type Check & Test
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install tygo
+        run: go install github.com/gzuidhof/tygo@latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Generate dashboard types
+        run: |
+          $HOME/go/bin/tygo generate
+          npx prettier --write src/generated/types.ts
+          git diff --exit-code -- src/generated/types.ts
+
+      - name: TypeScript check
+        run: bun run typecheck
+
+      - name: ESLint
+        run: bun run lint
+
+      - name: Prettier check
+        run: bun run format:check
+
+      - name: Run tests
+        run: bun run test:run
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: check
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Setup Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install tygo
+        run: go install github.com/gzuidhof/tygo@latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Generate dashboard types
+        run: |
+          $HOME/go/bin/tygo generate
+          npx prettier --write src/generated/types.ts
+
+      - name: Build
+        run: bun run build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dashboard-dist
+          path: dashboard/dist/
+          retention-days: 7

.github/workflows/docs-verify.yml

@@ -0,0 +1,33 @@
+name: Documentation Verification
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-verify.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs-verify.yml'
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+
+jobs:
+  docs-validate:
+    name: Validate Documentation
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Check docs.json references
+        run: |
+          echo "🔍 Validating docs.json..."
+          ./scripts/check-docs-json.sh
+        shell: bash

.github/workflows/e2e-recent.yml

@@ -0,0 +1,317 @@
+name: E2E Recent Tests
+
+permissions:
+  contents: read
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - '.gitignore'
+      - 'skill/**'
+      - 'plugin/**'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - '.gitignore'
+      - 'skill/**'
+      - 'plugin/**'
+  workflow_dispatch:
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+jobs:
+  recent:
+    name: E2E Recent Tests
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Run recent E2E tests
+        id: e2e
+        run: |
+          set +e
+          mkdir -p tests/e2e/results
+
+          ./dev e2e recent 2>&1 | tee e2e-output.log
+          EXIT_CODE=${PIPESTATUS[0]}
+
+          PASSED=$(grep -oP 'Passed:\s*\K\d+' e2e-output.log | tail -1 || true)
+          FAILED=$(grep -oP 'Failed:\s*\K\d+' e2e-output.log | tail -1 || true)
+          FAILURES=$(grep -E '✗.*failed' e2e-output.log | sed 's/.*✗ /- /' | head -10 || true)
+          PASSED=${PASSED:-0}
+          FAILED=${FAILED:-0}
+
+          echo "passed=$PASSED" >> $GITHUB_OUTPUT
+          echo "failed=$FAILED" >> $GITHUB_OUTPUT
+
+          {
+            echo 'failures<<EOF'
+            echo "$FAILURES"
+            echo 'EOF'
+          } >> $GITHUB_OUTPUT
+
+          exit $EXIT_CODE
+        env:
+          DOCKER_BUILDKIT: 1
+          COMPOSE_DOCKER_CLI_BUILD: 1
+
+      - name: Dump pinchtab logs on failure
+        if: failure()
+        run: |
+          echo "==== pinchtab logs ===="
+          docker compose -f tests/e2e/docker-compose.yml logs pinchtab || true
+          echo ""
+          echo "==== filtered Chrome/extension lines ===="
+          docker compose -f tests/e2e/docker-compose.yml logs pinchtab 2>/dev/null | grep -Ei 'chrome|extension|devtools|load-extension|disable-extensions|headless|warning|error' || true
+          echo ""
+          echo "==== instance inventory ===="
+          INSTANCES_JSON=$(curl -sf http://localhost:9999/instances || true)
+          if [ -n "$INSTANCES_JSON" ]; then
+            echo "$INSTANCES_JSON"
+            if command -v jq >/dev/null 2>&1; then
+              echo "$INSTANCES_JSON" | jq -r '.[].id' | while read -r inst_id; do
+                [ -z "$inst_id" ] && continue
+                echo ""
+                echo "==== logs for $inst_id ===="
+                curl -sf "http://localhost:9999/instances/$inst_id/logs" || true
+              done
+            fi
+          else
+            echo "unable to fetch /instances from localhost:9999"
+          fi
+
+      - name: Post summary
+        if: always()
+        run: |
+          PASSED="${{ steps.e2e.outputs.passed }}"
+          FAILED="${{ steps.e2e.outputs.failed }}"
+          PASSED="${PASSED:-0}"
+          FAILED="${FAILED:-0}"
+
+          if [ "${{ steps.e2e.outcome }}" = "success" ]; then
+            echo "## ✅ E2E Recent Tests Passed" >> $GITHUB_STEP_SUMMARY
+            if [ "$PASSED" = "0" ]; then
+              echo "All tests passed" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "**$PASSED** tests passed" >> $GITHUB_STEP_SUMMARY
+            fi
+          else
+            echo "## ❌ E2E Recent Tests Failed" >> $GITHUB_STEP_SUMMARY
+            echo "**Passed:** $PASSED" >> $GITHUB_STEP_SUMMARY
+            echo "**Failed:** $FAILED" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            echo "${{ steps.e2e.outputs.failures }}" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+          fi
+
+      - name: Report check annotation
+        if: always()
+        run: |
+          PASSED="${{ steps.e2e.outputs.passed }}"
+          FAILED="${{ steps.e2e.outputs.failed }}"
+          PASSED="${PASSED:-0}"
+          FAILED="${FAILED:-0}"
+
+          if [ "${{ steps.e2e.outcome }}" = "success" ]; then
+            if [ "$PASSED" = "0" ]; then
+              echo "::notice title=E2E Recent Tests::✅ All tests passed"
+            else
+              echo "::notice title=E2E Recent Tests::✅ ${PASSED} tests passed"
+            fi
+          else
+            echo "::error title=E2E Recent Tests::❌ ${FAILED} failed, ${PASSED} passed"
+          fi
+
+  e2e-curl:
+    name: E2E Curl Tests
+    needs: recent
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Run E2E curl tests
+        id: e2e
+        run: |
+          set +e
+          mkdir -p tests/e2e/results
+          ./dev e2e curl 2>&1 | tee e2e-output.log
+          EXIT_CODE=${PIPESTATUS[0]}
+
+          PASSED=$(grep -oP 'Passed:\s*\K\d+' e2e-output.log | tail -1 || true)
+          FAILED=$(grep -oP 'Failed:\s*\K\d+' e2e-output.log | tail -1 || true)
+          FAILURES=$(grep -E '✗.*failed' e2e-output.log | sed 's/.*✗ /- /' | head -10 || true)
+          PASSED=${PASSED:-0}
+          FAILED=${FAILED:-0}
+
+          echo "passed=$PASSED" >> $GITHUB_OUTPUT
+          echo "failed=$FAILED" >> $GITHUB_OUTPUT
+          {
+            echo 'failures<<EOF'
+            echo "$FAILURES"
+            echo 'EOF'
+          } >> $GITHUB_OUTPUT
+
+          exit $EXIT_CODE
+        env:
+          DOCKER_BUILDKIT: 1
+          COMPOSE_DOCKER_CLI_BUILD: 1
+
+      - name: Post summary
+        if: always()
+        run: |
+          PASSED="${{ steps.e2e.outputs.passed }}"
+          FAILED="${{ steps.e2e.outputs.failed }}"
+          PASSED="${PASSED:-0}"
+          FAILED="${FAILED:-0}"
+
+          if [ "${{ steps.e2e.outcome }}" = "success" ]; then
+            echo "## ✅ E2E Curl Tests Passed" >> $GITHUB_STEP_SUMMARY
+            if [ "$PASSED" = "0" ]; then
+              echo "All tests passed" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "**$PASSED** tests passed" >> $GITHUB_STEP_SUMMARY
+            fi
+          else
+            echo "## ❌ E2E Curl Tests Failed" >> $GITHUB_STEP_SUMMARY
+            echo "**Passed:** $PASSED" >> $GITHUB_STEP_SUMMARY
+            echo "**Failed:** $FAILED" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            echo "${{ steps.e2e.outputs.failures }}" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+          fi
+
+      - name: Report check annotation
+        if: always()
+        run: |
+          PASSED="${{ steps.e2e.outputs.passed }}"
+          FAILED="${{ steps.e2e.outputs.failed }}"
+          PASSED="${PASSED:-0}"
+          FAILED="${FAILED:-0}"
+          if [ "${{ steps.e2e.outcome }}" = "success" ]; then
+            if [ "$PASSED" = "0" ]; then
+              echo "::notice title=E2E Curl Tests::✅ All tests passed"
+            else
+              echo "::notice title=E2E Curl Tests::✅ ${PASSED} tests passed"
+            fi
+          else
+            echo "::error title=E2E Curl Tests::❌ ${FAILED} failed, ${PASSED} passed"
+          fi
+
+  e2e-cli:
+    name: E2E CLI Tests
+    needs: recent
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Run CLI E2E tests
+        id: e2e
+        run: |
+          set +e
+          ./dev e2e cli 2>&1 | tee e2e-output.log
+          EXIT_CODE=${PIPESTATUS[0]}
+
+          PASSED=$(grep -oP 'Passed:\s*\K\d+' e2e-output.log | tail -1 || true)
+          FAILED=$(grep -oP 'Failed:\s*\K\d+' e2e-output.log | tail -1 || true)
+          FAILURES=$(grep -E '✗.*failed' e2e-output.log | sed 's/.*✗ /- /' | head -10 || true)
+          PASSED=${PASSED:-0}
+          FAILED=${FAILED:-0}
+
+          echo "passed=$PASSED" >> $GITHUB_OUTPUT
+          echo "failed=$FAILED" >> $GITHUB_OUTPUT
+          {
+            echo 'failures<<EOF'
+            echo "$FAILURES"
+            echo 'EOF'
+          } >> $GITHUB_OUTPUT
+
+          exit $EXIT_CODE
+        env:
+          DOCKER_BUILDKIT: 1
+          COMPOSE_DOCKER_CLI_BUILD: 1
+
+      - name: Post summary
+        if: always()
+        run: |
+          PASSED="${{ steps.e2e.outputs.passed }}"
+          FAILED="${{ steps.e2e.outputs.failed }}"
+          PASSED="${PASSED:-0}"
+          FAILED="${FAILED:-0}"
+
+          if [ "${{ steps.e2e.outcome }}" = "success" ]; then
+            echo "## ✅ E2E CLI Tests Passed" >> $GITHUB_STEP_SUMMARY
+            if [ "$PASSED" = "0" ]; then
+              echo "All tests passed" >> $GITHUB_STEP_SUMMARY
+            else
+              echo "**$PASSED** tests passed" >> $GITHUB_STEP_SUMMARY
+            fi
+          else
+            echo "## ❌ E2E CLI Tests Failed" >> $GITHUB_STEP_SUMMARY
+            echo "**Passed:** $PASSED" >> $GITHUB_STEP_SUMMARY
+            echo "**Failed:** $FAILED" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+            echo "${{ steps.e2e.outputs.failures }}" >> $GITHUB_STEP_SUMMARY
+            echo '```' >> $GITHUB_STEP_SUMMARY
+          fi
+
+      - name: Report check annotation
+        if: always()
+        run: |
+          PASSED="${{ steps.e2e.outputs.passed }}"
+          FAILED="${{ steps.e2e.outputs.failed }}"
+          PASSED="${PASSED:-0}"
+          FAILED="${FAILED:-0}"
+          if [ "${{ steps.e2e.outcome }}" = "success" ]; then
+            if [ "$PASSED" = "0" ]; then
+              echo "::notice title=E2E CLI Tests::✅ All tests passed"
+            else
+              echo "::notice title=E2E CLI Tests::✅ ${PASSED} tests passed"
+            fi
+          else
+            echo "::error title=E2E CLI Tests::❌ ${FAILED} failed, ${PASSED} passed"
+          fi

.github/workflows/go-verify.yml

@@ -0,0 +1,191 @@
+name: Go Verification
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - '.gitignore'
+      - 'skill/**'
+      - 'plugin/**'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - '.gitignore'
+      - 'skill/**'
+      - 'plugin/**'
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Check which files changed to conditionally run jobs
+  changes:
+    name: Detect Changes
+    runs-on: ubuntu-latest
+    if: github.event.pull_request.draft == false
+    outputs:
+      go: ${{ steps.filter.outputs.go }}
+    steps:
+      - uses: actions/checkout@v5
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            go:
+              - '**.go'
+              - 'go.mod'
+              - 'go.sum'
+              - 'cmd/**'
+              - 'internal/**'
+
+  build:
+    name: Build & Vet
+    needs: changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Go changes
+        id: check
+        run: |
+          if [ "${{ needs.changes.outputs.go }}" = "true" ]; then
+            echo "Go files detected"
+            echo "has_go_changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "⏭️ No Go files changed - docs/workflow-only changes detected"
+            echo "has_go_changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-go@v6
+        if: steps.check.outputs.has_go_changes == 'true'
+        with:
+          go-version: '1.26'
+
+      - name: Download deps
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: go mod download
+
+      - name: Format check
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: |
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "Files not formatted:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - name: Vet
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: go vet ./...
+
+      - name: Build
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: go build -o pinchtab ./cmd/pinchtab
+
+      - name: Test with coverage
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: go test ./... -v -count=1 -coverprofile=coverage.out -covermode=atomic
+
+      - name: Coverage summary
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: |
+          coverage=$(go tool cover -func=coverage.out | tail -1)
+          echo "### Coverage" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "$coverage" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+
+  lint:
+    name: Lint
+    needs: changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Go changes
+        id: check
+        run: |
+          if [ "${{ needs.changes.outputs.go }}" = "true" ]; then
+            echo "has_go_changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "⏭️ No Go files changed, skipping lint"
+            echo "has_go_changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-go@v6
+        if: steps.check.outputs.has_go_changes == 'true'
+        with:
+          go-version: '1.26'
+
+      - uses: oven-sh/setup-bun@v2
+        if: needs.changes.outputs.go == 'true'
+        with:
+          bun-version: latest
+
+      - name: Install tygo
+        if: needs.changes.outputs.go == 'true'
+        run: go install github.com/gzuidhof/tygo@latest
+
+      - name: Build dashboard
+        if: needs.changes.outputs.go == 'true'
+        run: |
+          cd dashboard && bun install --frozen-lockfile && cd ..
+          ./scripts/build-dashboard.sh
+
+      - name: golangci-lint
+        if: steps.check.outputs.has_go_changes == 'true'
+        uses: golangci/golangci-lint-action@v7
+        with:
+          version: v2.9.0
+
+  security:
+    name: Security Scan
+    needs: changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for Go changes
+        id: check
+        run: |
+          if [ "${{ needs.changes.outputs.go }}" = "true" ]; then
+            echo "has_go_changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "⏭️ No Go files changed, skipping security scan"
+            echo "has_go_changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-go@v6
+        if: steps.check.outputs.has_go_changes == 'true'
+        with:
+          go-version: '1.26'
+
+      - name: Install gosec
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: go install github.com/securego/gosec/v2/cmd/gosec@latest
+
+      - name: Run gosec
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: gosec -exclude=G301,G302,G304,G306,G404,G107,G115,G703,G704,G705,G706 -fmt=json -out=gosec-results.json ./... || true
+
+      - name: Check critical findings
+        if: steps.check.outputs.has_go_changes == 'true'
+        run: |
+          # Fail on G112 (Slowloris), G204 (command injection)
+          ISSUES=$(cat gosec-results.json | jq '[.Issues[] | select(.rule_id == "G112" or .rule_id == "G204")] | length')
+          echo "Critical issues: $ISSUES"
+          cat gosec-results.json | jq '.Stats'
+          if [ "$ISSUES" -gt 0 ]; then
+            cat gosec-results.json | jq '.Issues[] | select(.rule_id == "G112" or .rule_id == "G204")'
+            exit 1
+          fi

.github/workflows/npm-verify.yml

@@ -0,0 +1,157 @@
+name: npm Package Verification
+
+on:
+  pull_request:
+    paths:
+      - 'npm/**'
+      - '.github/workflows/npm-verify.yml'
+  push:
+    tags:
+      - 'v*'
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify npm Package
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+
+      - name: Install dependencies
+        working-directory: npm
+        run: npm ci
+
+      - name: Lint (ESLint)
+        working-directory: npm
+        run: npm run lint
+
+      - name: Format Check (Prettier)
+        working-directory: npm
+        run: npm run format:check
+
+      - name: Build TypeScript
+        working-directory: npm
+        run: tsc
+
+      - name: Run tests
+        working-directory: npm
+        run: npm test
+
+      - name: Check for source .ts files in package
+        working-directory: npm
+        run: |
+          # Create the tarball and check its actual contents
+          npm pack > /dev/null 2>&1
+          TARBALL=$(ls -t pinchtab-*.tgz | head -1)
+          SOURCES=$(tar -tzf "$TARBALL" | grep -E "\.ts$" | grep -v "\.d\.ts" || true)
+          if [ -n "$SOURCES" ]; then
+            echo "❌ ERROR: Source .ts files in package:"
+            echo "$SOURCES"
+            exit 1
+          fi
+          echo "✅ No source .ts files in tarball"
+          rm "$TARBALL"
+
+      - name: Check for test files in package
+        working-directory: npm
+        run: |
+          TESTS=$(npm pack --dry-run 2>&1 | grep "dist/tests" || true)
+          if [ -n "$TESTS" ]; then
+            echo "❌ ERROR: Test files in package:"
+            echo "$TESTS"
+            exit 1
+          fi
+          echo "✅ No test files in package"
+
+      - name: Check for source maps in package
+        working-directory: npm
+        run: |
+          MAPS=$(npm pack --dry-run 2>&1 | grep "\.map$" || true)
+          if [ -n "$MAPS" ]; then
+            echo "❌ ERROR: Source maps in package:"
+            echo "$MAPS"
+            exit 1
+          fi
+          echo "✅ No source maps in package"
+
+      - name: Verify required files exist
+        working-directory: npm
+        run: |
+          REQUIRED=(
+            "dist/src/index.js"
+            "dist/src/index.d.ts"
+            "scripts/postinstall.js"
+            "bin/pinchtab"
+            "LICENSE"
+          )
+
+          PACK_OUTPUT=$(npm pack --dry-run 2>&1)
+
+          for file in "${REQUIRED[@]}"; do
+            if echo "$PACK_OUTPUT" | grep -q "$file"; then
+              echo "✅ $file"
+            else
+              echo "❌ Missing: $file"
+              exit 1
+            fi
+          done
+
+      - name: Check postinstall.js syntax
+        working-directory: npm
+        run: |
+          node -c scripts/postinstall.js
+          echo "✅ postinstall.js valid JavaScript"
+
+      - name: Verify package metadata
+        working-directory: npm
+        run: |
+          node -e "
+            const pkg = require('./package.json');
+            const checks = [
+              { name: 'name', value: pkg.name === 'pinchtab' },
+              { name: 'version', value: !!pkg.version },
+              { name: 'files array', value: Array.isArray(pkg.files) && pkg.files.length > 0 },
+              { name: 'postinstall script', value: !!pkg.scripts.postinstall },
+              { name: 'bin.pinchtab', value: !!pkg.bin.pinchtab }
+            ];
+
+            let failed = false;
+            checks.forEach(check => {
+              if (check.value) {
+                console.log('✅', check.name);
+              } else {
+                console.log('❌', check.name, 'missing or invalid');
+                failed = true;
+              }
+            });
+
+            if (failed) process.exit(1);
+          "
+
+      - name: Check package size
+        working-directory: npm
+        run: |
+          SIZE=$(npm pack --dry-run 2>&1 | tail -1 | awk '{print $NF}' | tr -d 'B')
+          echo "📦 Package size: ${SIZE}B"
+          if [ "$SIZE" -gt 100000 ]; then
+            echo "⚠️  Warning: Package is large (>100KB)"
+          fi
+
+      - name: Security audit
+        working-directory: npm
+        run: npm audit --audit-level=moderate || true
+
+      - name: List package contents
+        working-directory: npm
+        run: |
+          echo "📦 Package will contain:"
+          npm pack --dry-run 2>&1 | grep "notice" | awk '{print "  " $3 " (" $2 ")"}'

.github/workflows/publish-skill.yml

@@ -0,0 +1,58 @@
+name: Publish Skill
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+    secrets:
+      CLAWHUB_TOKEN:
+        required: true
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Skill version (e.g. 0.2.0, without v prefix)'
+        required: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Publish to ClawHub
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+
+      - name: Install ClawHub CLI
+        run: npm i -g clawhub
+
+      - name: Authenticate
+        run: clawhub login --token "$CLAWHUB_TOKEN" --no-browser
+        env:
+          CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}
+
+      - name: Publish skill
+        run: |
+          if [ -n "${{ inputs.version }}" ]; then
+            VERSION="${{ inputs.version }}"
+          elif [ -n "${{ github.event.inputs.version }}" ]; then
+            VERSION="${{ github.event.inputs.version }}"
+          else
+            VERSION=${GITHUB_REF_NAME#v}
+          fi
+          VERSION=${VERSION#v}
+          clawhub publish skills/pinchtab \
+            --slug pinchtab \
+            --name "Pinchtab" \
+            --version "$VERSION" \
+            --changelog "Release v$VERSION" \
+            --tags latest

.github/workflows/release.yml

@@ -0,0 +1,238 @@
+name: Release
+
+# Automatic release pipeline triggered on tag push (v0.7.0, etc.)
+#
+# Pipeline:
+#   1. Checkout tag
+#   2. Build Go binary + create GitHub release (goreleaser)
+#   3. Publish npm package (with postinstall binary download support)
+#   4. Build & push Docker images
+# See .github/RELEASING.md for the operational checklist.
+#
+# Secrets required:
+#   - NPM_TOKEN: npm authentication (https://docs.npmjs.com/creating-and-viewing-access-tokens)
+#   - DOCKERHUB_USER / DOCKERHUB_TOKEN: Docker Hub credentials
+#   - GITHUB_TOKEN: Automatic (GitHub Actions)
+#   - HOMEBREW_TAP_GITHUB_TOKEN: PAT with write access to pinchtab/homebrew-tap
+#
+# To create a release:
+#   git tag v0.7.0
+#   git push origin v0.7.0
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to release (e.g. v0.2.0). Leave empty for dry-run from ref.'
+        required: false
+      ref:
+        description: 'Git ref for dry-run testing (branch, tag, or SHA). Defaults to main.'
+        required: false
+        default: 'main'
+      dry_run:
+        description: 'Build release artifacts without publishing them.'
+        required: false
+        type: boolean
+        default: false
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  GORELEASER_VERSION: v2.14.3
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Release Binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Validate workflow inputs
+        if: ${{ github.event_name == 'workflow_dispatch' }}
+        run: |
+          if [ "${{ inputs.dry_run }}" != "true" ] && [ -z "${{ github.event.inputs.tag }}" ]; then
+            echo "tag is required unless dry_run=true" >&2
+            exit 1
+          fi
+
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.tag || github.event.inputs.ref || github.ref }}
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: '1.26'
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dashboard dependencies
+        working-directory: dashboard
+        run: bun install --frozen-lockfile
+
+      - name: Run GoReleaser
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.dry_run }}" = "true" ]; then
+            ARGS="release --clean --snapshot"
+          else
+            ARGS="release --clean"
+          fi
+
+          curl -sfL https://goreleaser.com/static/run | VERSION="$GORELEASER_VERSION" bash -s -- $ARGS
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          HOMEBREW_TAP_GITHUB_TOKEN: ${{ secrets.HOMEBREW_TAP_GITHUB_TOKEN }}
+
+  npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    needs: release
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.inputs.tag || github.event.inputs.ref || github.ref }}
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Extract version
+        id: version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.dry_run }}" = "true" ] && [ -z "${{ github.event.inputs.tag }}" ]; then
+            VERSION=$(jq -r .version npm/package.json)
+          else
+            TAG="${{ github.event.inputs.tag || github.ref_name }}"
+            VERSION=${TAG#v}  # Remove 'v' prefix
+          fi
+          echo "version=${VERSION}" >> "$GITHUB_OUTPUT"
+
+      - name: Update npm package version
+        if: ${{ github.event_name != 'workflow_dispatch' || !inputs.dry_run }}
+        working-directory: npm
+        run: |
+          CURRENT=$(jq -r .version package.json)
+          DESIRED=${{ steps.version.outputs.version }}
+          if [ "$CURRENT" != "$DESIRED" ]; then
+            npm version "$DESIRED" --no-git-tag-version
+          else
+            echo "Version already correct: $CURRENT"
+          fi
+
+      - name: Install dependencies
+        working-directory: npm
+        run: npm ci --ignore-scripts
+
+      - name: Build TypeScript
+        working-directory: npm
+        run: npm run build
+
+      - name: Dry-run npm publish
+        if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run }}
+        working-directory: npm
+        run: npm publish --dry-run
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish to npm
+        if: ${{ github.event_name != 'workflow_dispatch' || !inputs.dry_run }}
+        working-directory: npm
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  docker:
+    name: Docker Image
+    runs-on: ubuntu-latest
+    needs: release
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          ref: ${{ github.event.inputs.tag || github.event.inputs.ref || github.ref }}
+
+      - name: Extract Docker metadata
+        id: meta
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ "${{ inputs.dry_run }}" = "true" ]; then
+            if [ -n "${{ github.event.inputs.tag }}" ]; then
+              TAG="${{ github.event.inputs.tag }}"
+              VERSION="${TAG#v}-dryrun-${GITHUB_SHA::7}"
+            else
+              TAG="dry-run-${GITHUB_SHA::7}"
+              VERSION="$(jq -r .version npm/package.json)-dryrun-${GITHUB_SHA::7}"
+            fi
+            PUSH="false"
+          else
+            TAG="${{ github.event.inputs.tag || github.ref_name }}"
+            VERSION="${TAG#v}"
+            PUSH="true"
+          fi
+
+          {
+            echo "tag=$TAG"
+            echo "version=$VERSION"
+            echo "push=$PUSH"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Docker dry-run note
+        if: ${{ steps.meta.outputs.push != 'true' }}
+        run: |
+          echo "Running a multi-arch Docker build without pushing to GHCR or Docker Hub." >> "$GITHUB_STEP_SUMMARY"
+
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        if: ${{ steps.meta.outputs.push == 'true' }}
+        with:
+          username: ${{ secrets.DOCKERHUB_USER }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - uses: docker/login-action@v3
+        if: ${{ steps.meta.outputs.push == 'true' }}
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: ${{ steps.meta.outputs.push == 'true' }}
+          provenance: false
+          labels: |
+            org.opencontainers.image.source=https://github.com/pinchtab/pinchtab
+            org.opencontainers.image.version=${{ steps.meta.outputs.version }}
+          tags: |
+            ghcr.io/pinchtab/pinchtab:latest
+            ghcr.io/pinchtab/pinchtab:${{ steps.meta.outputs.tag }}
+            ghcr.io/pinchtab/pinchtab:${{ steps.meta.outputs.version }}
+            pinchtab/pinchtab:latest
+            pinchtab/pinchtab:${{ steps.meta.outputs.tag }}
+            pinchtab/pinchtab:${{ steps.meta.outputs.version }}
+
+  skill:
+    name: Publish Skill
+    needs:
+      - npm
+      - docker
+    if: ${{ github.event_name != 'workflow_dispatch' || !inputs.dry_run }}
+    uses: ./.github/workflows/publish-skill.yml
+    with:
+      version: ${{ github.event.inputs.tag || github.ref_name }}
+    secrets:
+      CLAWHUB_TOKEN: ${{ secrets.CLAWHUB_TOKEN }}

.gitignore

@@ -0,0 +1,50 @@
+node_modules/
+.venv/
+plugins/*/.venv/
+__pycache__/
+*.pyc
+browser-bridge
+/pinchtab
+coverage.out
+
+# Build artifacts and test output
+dist/
+*.js
+!scripts/**/*.js
+!dashboard/eslint.config.js
+!dashboard/vite.config.ts
+!npm/bin/pinchtab
+# React dashboard build output (generated by scripts/build-dashboard.sh)
+# Go code serves a built-in fallback when these files are absent.
+internal/dashboard/dashboard/assets/
+internal/dashboard/dashboard/dashboard.html
+
+# npm package
+npm/node_modules/
+# package-lock.json is committed for reproducible installs via npm ci
+
+# OpenClaw workspace files (should never be committed)
+.openclaw/
+SOUL.md
+HEARTBEAT.md
+IDENTITY.md
+USER.md
+BOOTSTRAP.md
+TOOLS.md
+MEMORY.md
+AGENTS.md
+*.test
+memory/
+pinchtab-small
+
+# Local development files
+MY_PROJECT_NOTES.md
+debug.log
+pinchtab.exe
+
+.gomodcache/
+.gocache
+.DS_Store
+# E2E test results
+tests/e2e/results/*
+!tests/e2e/results/.gitkeep

.goreleaser.yml

@@ -0,0 +1,61 @@
+version: 2
+
+before:
+  hooks:
+    - ./scripts/build-dashboard.sh
+
+builds:
+  - main: ./cmd/pinchtab
+    ldflags:
+      - -s -w -X main.version={{.Version}}
+    goos:
+      - linux
+      - darwin
+      - windows
+    goarch:
+      - amd64
+      - arm64
+
+archives:
+  # Output bare binaries directly (no archives)
+  # Note: goreleaser auto-adds .exe for Windows, so don't include it in the template
+  - format: binary
+    name_template: "pinchtab-{{ .Os }}-{{ .Arch }}"
+
+checksum:
+  name_template: checksums.txt
+
+brews:
+  - name: pinchtab
+    repository:
+      owner: pinchtab
+      name: homebrew-tap
+      branch: "brew-{{ .ProjectName }}-{{ .Version }}"
+      token: "{{ .Env.HOMEBREW_TAP_GITHUB_TOKEN }}"
+      pull_request:
+        enabled: true
+        base:
+          owner: pinchtab
+          name: homebrew-tap
+          branch: main
+    directory: Formula
+    homepage: "https://pinchtab.com"
+    description: "High-performance browser automation bridge and multi-instance orchestrator for AI agents"
+    license: "MIT"
+    test: |
+      system "#{bin}/pinchtab version"
+    install: |
+      bin.install Dir["pinchtab*"].first => "pinchtab"
+
+changelog:
+  sort: asc
+  filters:
+    exclude:
+      - '^docs:'
+      - '^ci:'
+      - '^chore:'
+
+release:
+  github:
+    owner: pinchtab
+    name: pinchtab

.hfignore

@@ -0,0 +1,32 @@
+.git/
+.github/
+.devcontainer/
+tests/
+scripts/
+docs/
+npm/
+plugins/
+skills/
+/assets/
+.goreleaser.yml
+.markdownlint.json
+.pre-commit-config.yaml
+CODE_OF_CONDUCT.md
+CONTRIBUTING.md
+DEFINITION_OF_DONE.md
+DEVELOPMENT.md
+RELEASE.md
+SECURITY.md
+TESTING.md
+THIRD_PARTY_LICENSES.md
+dev
+docker-compose.yml
+docker-entrypoint-release.sh
+install.sh
+node_modules/
+.gocache/
+.gomodcache/
+tmp/
+dist/
+dashboard/node_modules/
+dashboard/dist/

.markdownlint.json

@@ -0,0 +1,26 @@
+{
+  "default": true,
+  "line-length": {
+    "line_length": 200,
+    "heading_line_length": 200,
+    "code_block_line_length": 200,
+    "code_blocks": false
+  },
+  "no-hard-tabs": false,
+  "no-bare-urls": false,
+  "no-inline-html": false,
+  "blanks-around-headings": false,
+  "blanks-around-lists": false,
+  "blanks-around-fences": false,
+  "no-emphasis-as-heading": false,
+  "no-multiple-blank-lines": {
+    "maximum": 2
+  },
+  "first-line-heading": false,
+  "heading-start-left": true,
+  "heading-increment": true,
+  "no-duplicate-heading": {
+    "allow_different_nesting": true
+  },
+  "fenced-code-language": false
+}

.pre-commit-config.yaml

@@ -0,0 +1,40 @@
+repos:
+  # General file checks
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-json
+        exclude: 'tsconfig\..+\.json$'
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ['--maxkb=500']
+
+  # Go formatting
+  - repo: https://github.com/golangci/golangci-lint
+    rev: v2.1.6
+    hooks:
+      - id: golangci-lint
+        args: ['--timeout=5m']
+
+  # Markdown linting (relaxed for docs)
+  - repo: https://github.com/igorshubovych/markdownlint-cli
+    rev: v0.37.0
+    hooks:
+      - id: markdownlint
+        args: ['--config', '.markdownlint.json']
+        # Exclude test files, auto-generated docs, repo root, and skill docs
+        exclude: |
+          (?x)^(
+            tests/.*\.md|
+            \.github/.*\.md|
+            skill/.*\.md|
+            docs/references/.*\.json|
+            README\.md|
+            CONTRIBUTING\.md|
+            CODE_OF_CONDUCT\.md|
+            SECURITY\.md|
+            RELEASE\.md
+          )$

Agent.md

@@ -0,0 +1,257 @@
+# Agent.md
+
+## 1. Deployment Configuration
+
+### Target Space
+- **Profile:** `AUXteam`  
+- **Space:** `WitNote`  
+- **Full Identifier:** `AUXteam/WitNote`  
+- **Frontend Port:** `7860` (mandatory for all Hugging Face Spaces)
+
+### Deployment Method
+Choose the correct SDK based on the app type based on the codebase language:
+
+- **Gradio SDK** — for Gradio applications  
+- **Streamlit SDK** — for Streamlit applications  
+- **Docker SDK** — for all other applications (recommended default for flexibility)
+
+### HF Token
+- The environment variable **`HF_TOKEN` will always be provided at execution time**.
+- Never hardcode the token. Always read it from the environment.
+- All monitoring and log‑streaming commands rely on `$HF_TOKEN`.
+
+### Required Files
+- `Dockerfile` (or `app.py` for Gradio/Streamlit SDKs)
+- `README.md` with Hugging Face YAML frontmatter:
+  ```yaml
+  ---
+  title: <APP NAME>
+  sdk: docker | gradio | streamlit
+  app_port: 7860
+  ---
+  ```
+- `.hfignore` to exclude unnecessary files
+- This `Agent.md` file (must be committed before deployment)
+
+---
+
+## 2. API Exposure and Documentation
+
+### Mandatory Endpoints
+Every deployment **must** expose:
+
+- **`/health`**  
+  - Returns HTTP 200 when the app is ready.  
+  - Required for Hugging Face to transition the Space from *starting* → *running*.
+
+- **`/api-docs`**  
+  - Documents **all** available API endpoints.  
+  - Must be reachable at:  
+    `https://HF_PROFILE-WitNote.hf.space/api-docs`
+
+### Functional Endpoints
+
+### /navigate
+- Method: POST
+- Purpose: Navigate the current tab to a specified URL.
+- Request Example:
+  ```json
+  {
+    "url": "https://example.com"
+  }
+  ```
+- Response Example:
+  ```json
+  {
+    "status": "ok",
+    "url": "https://example.com"
+  }
+  ```
+
+### /text
+- Method: GET
+- Purpose: Extract structured text from the current page.
+- Request Example: `?maxChars=1000&format=markdown`
+- Response Example:
+  ```json
+  {
+    "text": "Extracted text content..."
+  }
+  ```
+
+### /action
+- Method: POST
+- Purpose: Perform a single action on the page (e.g., click, type).
+- Request Example:
+  ```json
+  {
+    "action": "click",
+    "selector": "#submit-btn"
+  }
+  ```
+- Response Example:
+  ```json
+  {
+    "status": "ok"
+  }
+  ```
+
+### /snapshot
+- Method: GET
+- Purpose: Get an accessibility snapshot of the current page.
+- Request Example: (no body)
+- Response Example:
+  ```json
+  {
+    "snapshot": [ ... ]
+  }
+  ```
+
+### /evaluate
+- Method: POST
+- Purpose: Run JavaScript in the current tab.
+- Request Example:
+  ```json
+  {
+    "expression": "document.title"
+  }
+  ```
+- Response Example:
+  ```json
+  {
+    "result": "Example Domain"
+  }
+  ```
+
+### /macro
+- Method: POST
+- Purpose: Execute a macro action pipeline.
+- Request Example:
+  ```json
+  {
+    "actions": [
+      {"action": "click", "selector": "#btn"}
+    ]
+  }
+  ```
+- Response Example:
+  ```json
+  {
+    "status": "ok"
+  }
+  ```
+
+All endpoints listed here **must** appear in `/api-docs`.
+
+---
+
+## 3. Deployment Workflow
+
+### Standard Deployment Command
+After any code change, run:
+
+```bash
+hf upload AUXteam/WitNote --repo-type=space
+```
+
+This command must be executed **after updating and committing Agent.md**.
+
+### Deployment Steps
+1. Ensure all code changes are committed.  
+2. Ensure `Agent.md` is updated and committed.  
+3. Run the upload command.  
+4. Wait for the Space to build.  
+5. Monitor logs (see next section).  
+6. When the Space is running, execute all test cases.
+
+### Continuous Deployment Rule
+After **every** relevant edit (logic, dependencies, API changes):
+
+- Update `Agent.md`
+- Redeploy using the upload command
+- Re-run all test cases
+- Confirm `/health` and `/api-docs` are functional
+
+This applies even for long-running projects.
+
+---
+
+## 4. Monitoring and Logs
+
+### Build Logs (SSE)
+```bash
+curl -N \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  "https://huggingface.co/api/spaces/AUXteam/WitNote/logs/build"
+```
+
+### Run Logs (SSE)
+```bash
+curl -N \
+  -H "Authorization: Bearer $HF_TOKEN" \
+  "https://huggingface.co/api/spaces/AUXteam/WitNote/logs/run"
+```
+
+### Notes
+- If the Space stays in *starting* for too long, `/health` is usually failing.  
+- If the Space times out after ~30 minutes, check logs immediately.  
+- Fix issues, commit changes, redeploy.
+
+---
+
+## 5. Test Run Cases (Mandatory After Every Deployment)
+
+These tests ensure the agentic system can verify the deployment automatically.
+
+### 1. Health Check
+```
+GET https://HF_PROFILE-WitNote.hf.space/health
+Expected: HTTP 200, body: {"status": "ok"} or similar
+```
+
+### 2. API Docs Check
+```
+GET https://HF_PROFILE-WitNote.hf.space/api-docs
+Expected: HTTP 200, valid documentation UI or JSON spec
+```
+
+### 3. Functional Endpoint Tests
+For each endpoint documented above, define:
+
+- Example request
+- Expected response structure
+- Validation criteria (e.g., non-empty output, valid JSON)
+
+Example:
+
+```
+POST https://HF_PROFILE-WitNote.hf.space/predict
+Payload:
+{
+  "text": "test"
+}
+Expected:
+- HTTP 200
+- JSON with key "prediction"
+- No error fields
+```
+
+### 4. End-to-End Behaviour
+- Confirm the UI loads (if applicable)
+- Confirm API endpoints respond within reasonable time
+- Confirm no errors appear in run logs
+
+---
+
+## 6. Maintenance Rules
+
+- `Agent.md` must always reflect the **current** deployment configuration, API surface, and test cases.
+- Any change to:
+  - API routes  
+  - Dockerfile  
+  - Dependencies  
+  - App logic  
+  - Deployment method  
+  requires updating this file.
+- This file must be committed **before** every deployment.
+- This file is the operational contract for autonomous agents interacting with the project.

CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at admin@pinchtab.com. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing to PinchTab
+
+This repository keeps one detailed contributor guide:
+
+- [docs/guides/contributing.md](docs/guides/contributing.md)
+
+Use that guide for setup, build commands, tests, hooks, and the day-to-day development workflow.
+
+## Quick Start
+
+```bash
+git clone https://github.com/pinchtab/pinchtab.git
+cd pinchtab
+./dev doctor
+./dev check
+./dev test unit
+```
+
+## Pull Requests
+
+Please keep GitHub's "Allow edits from maintainers" option enabled on your PRs. It makes small fixes, rebases, and merge-conflict resolution much faster.

DEFINITION_OF_DONE.md

@@ -0,0 +1,5 @@
+# Definition of Done
+
+Canonical file: [`.github/DEFINITION_OF_DONE.md`](./.github/DEFINITION_OF_DONE.md)
+
+Use the `.github` copy as the source of truth for PR review, templates, and agent instructions.

DEVELOPMENT.md

@@ -0,0 +1,7 @@
+# Development Setup
+
+This document has been consolidated into the main contributor guide:
+
+- [docs/guides/contributing.md](docs/guides/contributing.md)
+
+Use that page as the source of truth for environment setup, building, testing, hooks, and contributor workflow.

Dockerfile

@@ -0,0 +1,70 @@
+# Stage 1: Build the React dashboard with Bun.
+# The compiled assets are copied into the Go embed directory in stage 2.
+FROM oven/bun:1 AS dashboard
+WORKDIR /build
+COPY dashboard/package.json dashboard/bun.lock ./
+RUN bun install --frozen-lockfile
+COPY dashboard/ .
+RUN bun run build
+
+# Stage 2: Compile the Go binary.
+# Dashboard dist is embedded via Go's embed package.
+# Vite always outputs index.html; rename to dashboard.html so it doesn't
+# collide with http.FileServer's automatic index.html handling at /dashboard/.
+FROM golang:1.26-alpine AS builder
+RUN apk add --no-cache git
+WORKDIR /build
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+COPY --from=dashboard /build/dist/ internal/dashboard/dashboard/
+RUN mv internal/dashboard/dashboard/index.html internal/dashboard/dashboard/dashboard.html
+RUN go build -ldflags="-s -w" -o pinchtab ./cmd/pinchtab
+
+# Stage 3: Minimal runtime image with Chromium.
+# Only the compiled binary and entrypoint script are copied in.
+#
+# Security model:
+# - Chrome runs with --no-sandbox (set by entrypoint) because containers don't
+#   have user namespaces for sandboxing
+# - Container provides isolation via cgroups, seccomp, dropped capabilities,
+#   read-only filesystem, and non-root user
+# - This matches best practices for headless Chrome in containerized environments
+FROM alpine:3.21
+
+LABEL org.opencontainers.image.source="https://github.com/pinchtab/pinchtab"
+LABEL org.opencontainers.image.description="High-performance browser automation bridge"
+
+# Chromium and its runtime dependencies for headless operation
+RUN apk add --no-cache \
+    chromium \
+    nss \
+    freetype \
+    harfbuzz \
+    ca-certificates \
+    ttf-freefont \
+    dumb-init
+
+# Non-root user; /data is the persistent volume mount point
+RUN adduser -D -h /data -g '' pinchtab && \
+    mkdir -p /data && \
+    chown pinchtab:pinchtab /data
+
+COPY --from=builder /build/pinchtab /usr/local/bin/pinchtab
+COPY --chmod=0755 docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
+
+USER pinchtab
+WORKDIR /data
+
+# HOME and XDG_CONFIG_HOME point into the persistent volume so config
+# and Chrome profiles survive container restarts.
+ENV HOME=/data \
+    XDG_CONFIG_HOME=/data/.config
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -q -O /dev/null http://localhost:7860/health || exit 1
+
+ENTRYPOINT ["/usr/bin/dumb-init", "--"]
+CMD ["/usr/local/bin/docker-entrypoint.sh", "pinchtab"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luigi Agosti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,374 @@
 ---
-title: WitNote
-emoji: 👁
-colorFrom: green
-colorTo: purple
-sdk: gradio
-sdk_version: 6.9.0
-app_file: app.py
-pinned: false
+title: PinchTab
+sdk: docker
+app_port: 7860
 ---
+<p align="center">
+  <img src="assets/pinchtab-headless.png" alt="PinchTab" width="200"/>
+</p>
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<p align="center">
+  <strong>PinchTab</strong><br/>
+  <strong>Browser control for AI agents</strong><br/>
+  12MB Go binary • HTTP API • Token-efficient
+</p>
+
+
+<table align="center">
+  <tr>
+    <td align="center" valign="middle">
+      <a href="https://pinchtab.com/docs"><img src="assets/docs-no-background-256.png" alt="Full Documentation" width="92"/></a>
+    </td>
+    <td align="left" valign="middle">
+      <a href="https://github.com/pinchtab/pinchtab/releases/latest"><img src="https://img.shields.io/github/v/release/pinchtab/pinchtab?style=flat-square&color=FFD700" alt="Release"/></a><br/>
+      <a href="https://github.com/pinchtab/pinchtab/actions/workflows/go-verify.yml"><img src="https://img.shields.io/github/actions/workflow/status/pinchtab/pinchtab/go-verify.yml?branch=main&style=flat-square&label=Build" alt="Build"/></a><br/>
+      <img src="https://img.shields.io/badge/Go-1.25+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go 1.25+"/><br/>
+      <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue?style=flat-square" alt="License"/></a>
+    </td>
+  </tr>
+</table>
+
+---
+
+## What is PinchTab?
+
+PinchTab is a **standalone HTTP server** that gives AI agents direct control over Chrome.
+
+For day-to-day local use, the server is typically installed as a user-level daemon, allowing agent tools to reuse the same browser control plane running in the background.
+
+```bash
+curl -fsSL https://pinchtab.com/install.sh | bash
+# or
+pinchtab daemon install
+```
+
+This installs the control-plane server and starts a default headless Chrome instance, ready to accept requests from agents or manual API calls.
+
+
+If you prefer not to run a daemon, or if you're on Windows, you can instead run:
+
+`pinchtab server` — runs the control-plane server directly
+`pinchtab bridge` — runs a single browser instance as a lightweight runtime
+
+PinchTab also provides a CLI with an interactive entry point for local setup and common tasks:
+
+`pinchtab`
+
+## Security
+
+PinchTab defaults to a **local-first security posture**:
+
+- `server.bind = 127.0.0.1`
+- sensitive endpoint families are disabled by default
+- `attach` is disabled by default
+- IDPI is enabled with a **local-only website allowlist**
+
+> [!CAUTION]
+> By default, IDPI restricts browsing to **locally hosted websites only**.
+> This prevents agents from navigating the public internet until you explicitly allow it.
+> The restriction exists to make the security implications of browser automation clear before enabling wider access.
+
+See the full guide: [docs/guides/security.md](docs/guides/security.md)
+
+## What can you use it for
+
+### Headless navigation
+
+With the daemon installed and an agent skill configured, an agent can execute tasks like:
+
+```
+"What are the main news about aliens on news.com?"
+```
+
+PinchTab exposes browser tools that allow agents to navigate pages, extract structured content, and interact with the DOM without wasting tokens on raw HTML or images.
+
+### Headed navigation
+
+In addition to headless automation, PinchTab supports headed Chrome profiles.
+
+You can create profiles configured with authentication, cookies, extensions, or specific environments. Each profile can have a name and description.
+
+For example, an agent request like:
+
+```
+"Log into my work profile and download the weekly report"
+```
+
+can automatically select the appropriate profile and perform the action.
+
+### Local container isolation
+
+If you prefer stronger isolation, PinchTab can run inside Docker.
+
+This allows agents to control browsers in a sandboxed environment, reducing risk when running automation tasks locally.
+
+### Distributed automation
+
+PinchTab can manage multiple Chrome instances (headless or headed) across containers or remote machines.
+
+Typical use cases include:
+
+- QA automation
+- testing environments
+- distributed browsing tasks
+- development tooling
+
+You can connect to multiple PinchTab servers, or attach to Chrome instances running in remote debug mode.
+
+## Process Model
+
+PinchTab is server-first:
+1. install the daemon or run `pinchtab server` for the full control plane
+2. let the server manage profiles and instances
+3. let each managed instance run behind a lightweight `pinchtab bridge` runtime
+
+In practice:
+- Server — the main product entry point and control plane
+- Bridge — the runtime that manages a single browser instance
+- Attach — an advanced mode for registering externally managed Chrome instances
+
+### Primary Usage
+
+The primary user journey is:
+
+1. install Pinchtab
+2. install and start the daemon with `pinchtab daemon install`
+3. point your agent or tool at `http://localhost:9867`
+4. let PinchTab act as your local browser service
+
+That is the default “replace the browser runtime” scenario.
+Most users should not need to think about `pinchtab bridge` directly, and only need `pinchtab` when they want the local interactive menu.
+
+### Key Features
+
+- **CLI or Curl** — Control via command-line or HTTP API
+- **Token-efficient** — 800 tokens/page with text extraction (5-13x cheaper than screenshots)
+- **Headless or Headed** — Run without a window or with visible Chrome
+- **Multi-instance** — Run multiple parallel Chrome processes with isolated profiles
+- **Self-contained** — ~15MB binary, no external dependencies
+- **Accessibility-first** — Stable element refs instead of fragile coordinates
+- **ARM64-optimized** — First-class Raspberry Pi support with automatic Chromium detection
+
+---
+
+## Quick Start
+
+### Installation
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://pinchtab.com/install.sh | bash
+```
+
+**Homebrew (macOS / Linux):**
+```bash
+brew install pinchtab/tap/pinchtab
+```
+
+**npm:**
+```bash
+npm install -g pinchtab
+```
+
+### Shell Completion
+
+Generate and install shell completions after `pinchtab` is on your `PATH`:
+
+```bash
+# Generate and install zsh completions
+pinchtab completion zsh > "${fpath[1]}/_pinchtab"
+
+# Generate bash completions
+pinchtab completion bash > /etc/bash_completion.d/pinchtab
+
+# Generate fish completions
+pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
+```
+
+**Docker:**
+```bash
+docker run -d \
+  --name pinchtab \
+  -p 127.0.0.1:9867:9867 \
+  -v pinchtab-data:/data \
+  --shm-size=2g \
+  pinchtab/pinchtab
+```
+
+The bundled container persists its managed config at `/data/.config/pinchtab/config.json`.
+If you want to supply your own config file instead, mount it and point `PINCHTAB_CONFIG` at it:
+
+```bash
+docker run -d \
+  --name pinchtab \
+  -p 127.0.0.1:9867:9867 \
+  -e PINCHTAB_CONFIG=/config/config.json \
+  -v "$PWD/config.json:/config/config.json:ro" \
+  -v pinchtab-data:/data \
+  --shm-size=2g \
+  pinchtab/pinchtab
+```
+
+### Use It
+
+**Terminal 1 — Start the server:**
+```bash
+pinchtab server
+```
+
+**Recommended for daily local use — install the daemon once:**
+```bash
+pinchtab daemon install
+pinchtab daemon
+```
+
+That keeps PinchTab running in the background so your agent tools can reuse it without an open terminal.
+
+**Terminal 2 — Control the browser:**
+```bash
+# Navigate
+pinchtab nav https://pinchtab.com
+
+# Get page structure
+pinchtab snap -i -c
+
+# Click an element
+pinchtab click e5
+
+# Extract text
+pinchtab text
+```
+
+Or use the HTTP API directly:
+```bash
+# Create an instance (returns instance id)
+INST=$(curl -s -X POST http://localhost:9867/instances/launch \
+  -H "Content-Type: application/json" \
+  -d '{"name":"work","mode":"headless"}' | jq -r '.id')
+
+# Open a tab in that instance
+TAB=$(curl -s -X POST http://localhost:9867/instances/$INST/tabs/open \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://pinchtab.com"}' | jq -r '.tabId')
+
+# Get snapshot
+curl "http://localhost:9867/tabs/$TAB/snapshot?filter=interactive"
+
+# Click element
+curl -X POST "http://localhost:9867/tabs/$TAB/action" \
+  -H "Content-Type: application/json" \
+  -d '{"kind":"click","ref":"e5"}'
+```
+
+---
+
+## Core Concepts
+
+**Server** — The main PinchTab process. It manages profiles, instances, routing, and the dashboard.
+
+**Instance** — A running Chrome process. Each instance can have one profile.
+
+**Profile** — Browser state (cookies, history, local storage). Log in once, stay logged in across restarts.
+
+**Tab** — A single webpage. Each instance can have multiple tabs.
+
+**Bridge** — The single-instance runtime behind a managed instance. Usually spawned by the server, not started manually.
+
+Read more in the [Core Concepts](https://pinchtab.com/docs/core-concepts) guide.
+
+---
+
+## Why PinchTab?
+
+| Aspect | PinchTab |
+|--------|----------|
+| **Tokens performance** | ✅ |
+| **Headless and Headed** | ✅ |
+| **Profile** | ✅ |
+| **Advanced CDP control** | ✅ |
+| **Persistent sessions** | ✅ |
+| **Binary size** | ✅ |
+| **Multi-instance** | ✅ |
+| **External Chrome attach** | ✅ |
+
+---
+
+## Privacy
+
+PinchTab is a fully open-source, local-only tool. No telemetry, no analytics, no outbound connections. The binary binds to `127.0.0.1` by default. Persistent profiles store browser sessions locally on your machine — similar to how a human reuses their browser. The single Go binary (~16 MB) is fully verifiable: build from source at [github.com/pinchtab/pinchtab](https://github.com/pinchtab/pinchtab).
+
+---
+
+## Documentation
+
+Full docs at **[pinchtab.com/docs](https://pinchtab.com/docs)**
+
+### MCP (SMCP) integration
+
+An **SMCP plugin** in this repo lets AI agents control PinchTab via the [Model Context Protocol](https://github.com/sanctumos/smcp) (SMCP). One plugin exposes 15 tools (e.g. `pinchtab__navigate`, `pinchtab__snapshot`, `pinchtab__action`). No extra runtime deps (stdlib only). See **[plugins/README.md](plugins/README.md)** for setup (env vars and paths).
+
+---
+
+## Examples
+
+### AI Agent Automation
+
+```bash
+# Your AI agent can:
+pinchtab nav https://pinchtab.com
+pinchtab snap -i  # Get clickable elements
+pinchtab click e5 # Click by ref
+pinchtab fill e3 "user@pinchtab.com"  # Fill input
+pinchtab press e7 Enter              # Submit form
+```
+
+### Data Extraction
+
+```bash
+# Extract text (token-efficient)
+pinchtab nav https://pinchtab.com/article
+pinchtab text  # ~800 tokens instead of 10,000
+```
+
+### Multi-Instance Workflows
+
+```bash
+# Run multiple instances in parallel
+curl -s -X POST http://localhost:9867/instances/start \
+  -H "Content-Type: application/json" \
+  -d '{"profileId":"alice","mode":"headless"}'
+
+curl -s -X POST http://localhost:9867/instances/start \
+  -H "Content-Type: application/json" \
+  -d '{"profileId":"bob","mode":"headless"}'
+
+# Each instance is isolated
+curl http://localhost:9867/instances
+```
+
+See [chrome-files.md](chrome-files.md) for technical details on how PinchTab manages Chrome user data directories and ensures isolation between parallel instances.
+
+---
+
+## Development
+
+Want to contribute? Start with [CONTRIBUTING.md](CONTRIBUTING.md).
+The full setup and workflow guide lives at [docs/guides/contributing.md](docs/guides/contributing.md).
+
+**Quick start:**
+```bash
+git clone https://github.com/pinchtab/pinchtab.git
+cd pinchtab
+./dev doctor                # Verifies environment, offers hooks/deps setup
+go build ./cmd/pinchtab     # Build pinchtab binary
+```
+
+---
+
+## License
+
+MIT — Free and open source.
+
+---
+
+**Get started:** [pinchtab.com/docs](https://pinchtab.com/docs)

RELEASE.md

@@ -0,0 +1,224 @@
+# Release Process
+
+**⚠️ CRITICAL:** The npm package depends on Go binaries being in the GitHub release. The release pipeline will fail hard if goreleaser doesn't upload binaries — npm users won't get a working binary.
+
+Pinchtab uses an automated CI/CD pipeline triggered by Git tags. When you push a tag like `v0.7.0`, GitHub Actions:
+
+1. **Builds Go binaries** — darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64
+2. **Creates GitHub release** — with checksums.txt for integrity verification
+3. **Publishes to npm** — TypeScript SDK with auto-download postinstall script
+4. **Builds Docker images** — linux/amd64, linux/arm64
+
+## Prerequisites
+
+### Secrets (configure once in GitHub)
+
+Go to **Settings → Secrets and variables → Actions** and add:
+
+- **NPM_TOKEN** — npm authentication token
+  - Create at https://npmjs.com/settings/~/tokens
+  - Scope: `automation` (publish + read)
+
+- **DOCKERHUB_USER** — Docker Hub username (if using Docker Hub)
+- **DOCKERHUB_TOKEN** — Docker Hub personal access token
+
+### Local setup
+
+```bash
+# 1. Ensure main branch is up to date
+git checkout main && git pull origin main
+
+# 2. Merge feature branches
+# (all features should be on main before tagging)
+
+# 3. Verify version consistency
+cat package.json | jq .version     # npm package
+cat go.mod | grep "module"         # Go module
+git describe --tags                # latest tag
+```
+
+## Pre-Release Checklist
+
+Goreleaser is already configured correctly. Verify before tagging:
+
+```bash
+# 1. Check builds section (compiles for all platforms)
+grep -A 8 "^builds:" .goreleaser.yml
+# Should output: linux/darwin/windows + amd64/arm64
+
+# 2. Check archives use binary format (required for npm)
+grep -A 5 "^archives:" .goreleaser.yml
+# Should show: format: binary (not tar/zip)
+
+# 3. Verify checksums enabled
+grep "checksum:" .goreleaser.yml
+# Should output: name_template: checksums.txt
+
+# 4. Check release config
+grep -A 2 "^release:" .goreleaser.yml
+# Should output: GitHub owner/repo
+```
+
+**Configuration status:**
+- ✅ `builds:` section compiles all platforms (darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-amd64, windows-arm64)
+- ✅ `archives:` outputs binaries directly: `pinchtab-darwin-arm64`, `pinchtab-linux-x64`, etc.
+- ✅ `checksum:` generates `checksums.txt` (used by npm postinstall verification)
+- ✅ `release:` points to GitHub (uploads everything automatically)
+
+**Ready to release.** Just tag and push.
+
+## Releasing
+
+### For patch/minor versions (recommended)
+
+```bash
+# 1. Bump version in all places
+npm version patch   # or minor, major
+git push origin main
+
+# 2. Create tag
+git tag v0.7.1
+git push origin v0.7.1
+```
+
+### For manual releases
+
+```bash
+# 1. Tag directly
+git tag -a v0.7.1 -m "Release v0.7.1"
+git push origin v0.7.1
+
+# 2. Or via GitHub UI: Releases → Create from tag
+#    (workflow will auto-create if not present)
+```
+
+### Using workflow_dispatch (manual trigger)
+
+If you need to re-release an existing tag:
+
+1. Go to **Actions → Release**
+2. **Run workflow**
+3. Enter tag (e.g. `v0.7.1`)
+
+For a no-side-effects dry run from `main` or any other ref:
+
+1. Go to **Actions → Release**
+2. **Run workflow**
+3. Leave `tag` empty
+4. Set `ref` to the branch, tag, or commit you want to test
+5. Set `dry_run` to `true`
+
+Dry-run behavior:
+- GoReleaser runs in snapshot mode, so artifacts are built but not published
+- npm runs `npm publish --dry-run`
+- Docker runs a multi-arch `buildx` build with `push=false`
+- ClawHub skill publishing is not part of this workflow and is therefore skipped
+
+## Pipeline details
+
+### 1. Goreleaser (Go binary) — CRITICAL for npm
+
+Triggered on `v*` tag push. Builds binaries and creates GitHub release.
+
+**What it does:**
+- ✅ Compiles for all platforms (darwin-arm64, darwin-x64, linux-x64, linux-arm64, windows-x64)
+- ✅ Generates `checksums.txt` (SHA256)
+- ✅ **Uploads binaries to GitHub Releases** ← Required by npm postinstall!
+- Also: Docker images, changelog, etc.
+
+**⚠️ CRITICAL:** npm postinstall script downloads binaries from GitHub Releases. If the release doesn't have the binaries (e.g., only Docker images), `npm install pinchtab` will fail silently and the binary won't be available.
+
+**Configured in:** `.goreleaser.yml`
+
+**Verify release has binaries:**
+```bash
+curl -s https://api.github.com/repos/pinchtab/pinchtab/releases/v0.7.0 | jq '.assets[].name'
+# Should output: pinchtab-darwin-arm64, pinchtab-darwin-x64, etc.
+```
+
+### 2. npm publish
+
+Depends on: `release` job (waits for goreleaser to finish)
+
+**What it does:**
+- Syncs version from tag (v0.7.0 → 0.7.0)
+- Builds TypeScript (`npm run build`)
+- Publishes to npm registry
+- Users get postinstall script that downloads binaries from GitHub Releases
+
+**User flow on `npm install pinchtab`:**
+```
+1. npm downloads @pinchtab/cli package
+2. Runs postinstall script
+3. Script detects OS/arch (darwin-arm64, linux-x64, etc.)
+4. Downloads binary from GitHub release
+5. Verifies SHA256 checksum
+6. Stores in ~/.pinchtab/bin/0.7.0/pinchtab-<os>-<arch>
+7. Makes executable
+8. If ANY STEP fails → npm install fails (exit 1)
+```
+
+**⚠️ REQUIRES:** Goreleaser must have successfully uploaded binaries to GitHub release. The npm postinstall will verify this and fail hard if binaries are missing.
+
+### 3. Docker
+
+GitHub Actions builds the release image directly from the tagged source with `docker buildx`.
+The workflow pushes the same multi-arch build to both GHCR and Docker Hub, so Docker no longer depends on GoReleaser's temporary build context.
+
+### 4. ClawHub skill
+
+The main `Release` workflow publishes the Pinchtab skill to ClawHub only after both npm and Docker complete successfully.
+The standalone `Publish Skill` workflow is manual-only and is intended for retries or one-off recovery publishes.
+
+## Troubleshooting
+
+### npm publish fails (403)
+
+- Check **NPM_TOKEN** is set in secrets
+- Verify token has `automation` scope
+- Check you're not already published (can't overwrite existing version)
+
+### Binary checksum mismatch
+
+- goreleaser must generate `checksums.txt`
+- Verify `.goreleaser.yml` has `checksum:` section
+- Check GitHub release includes `checksums.txt`
+
+### Docker push fails
+
+- Verify DOCKERHUB_USER and DOCKERHUB_TOKEN
+- Check token has permission to push
+
+## Rolling back
+
+If something goes wrong:
+
+```bash
+# Delete the tag locally and on GitHub
+git tag -d v0.7.1
+git push origin :refs/tags/v0.7.1
+
+# Delete npm version (requires owner permission)
+npm unpublish pinchtab@0.7.1
+
+# Revert any commits
+git revert <commit>
+git push origin main
+
+# Retag when ready
+git tag v0.7.1
+git push origin v0.7.1
+```
+
+## Version strategy
+
+- Use **semantic versioning**: v0.7.0 (major.minor.patch)
+- Tag on main branch only
+- One tag = one release (all artifacts)
+- npm version must match Go binary tag
+
+## See also
+
+- `.github/workflows/release.yml` — GitHub Actions workflow
+- `.goreleaser.yml` — Go binary release config
+- `npm/package.json` — npm package metadata

SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy
+
+## Supported Versions
+
+We currently support the following versions of Pinchtab with security updates:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| v0.7.x  | :white_check_mark: |
+| v0.6.x  | :white_check_mark: |
+| < v0.6  | :x:                |
+
+## Reporting a Vulnerability
+
+We take the security of our browser automation bridge seriously. If you believe you have found a security vulnerability, please do not report it via a public GitHub issue.
+
+Instead, please report vulnerabilities privately by:
+
+1.  Opening a **Private Vulnerability Report** on GitHub (if available for this repo).
+2.  Or emailing the maintainer directly at [INSERT EMAIL ADDRESS].
+
+Please include:
+- A description of the vulnerability.
+- Steps to reproduce (proof of concept).
+- Potential impact.
+
+We will acknowledge receipt of your report within 48 hours and provide a timeline for a fix if necessary.

TESTING.md

@@ -0,0 +1,176 @@
+# Testing
+
+## Quick Start with dev
+
+The `dev` developer toolkit is the easiest way to run checks and tests:
+
+```bash
+./dev                    # Interactive picker
+./dev test               # All tests (unit + E2E)
+./dev test unit          # Unit tests only
+./dev e2e                # E2E tests (both curl and CLI)
+./dev e2e orchestrator   # Orchestrator-heavy E2E tests only
+./dev e2e curl           # E2E curl tests only
+./dev e2e cli            # E2E CLI tests only
+./dev check              # All checks (format, vet, build, lint)
+./dev check go           # Go checks only
+./dev check security     # Gosec security scan
+./dev format dashboard   # Run Prettier on dashboard sources
+./dev doctor             # Setup dev environment
+```
+
+## Unit Tests
+
+```bash
+go test ./...
+# or
+./dev test unit
+```
+
+Unit tests are standard Go tests that validate individual packages and functions without launching a full server.
+
+## E2E Tests
+
+End-to-end tests launch a real pinchtab server with Chrome and run e2e-level tests against it.
+
+### Curl Tests (HTTP API)
+
+```bash
+./dev e2e curl
+```
+
+Runs 183 HTTP-level tests using curl against the server. Tests the REST API, navigation, snapshots, and other HTTP endpoints.
+
+### CLI Tests
+
+```bash
+./dev e2e cli
+```
+
+Runs CLI e2e tests. Tests the command-line interface directly.
+
+### Both E2E Test Suites
+
+```bash
+./dev e2e
+```
+
+Runs all E2E tests (curl + CLI, 224 tests total).
+
+### Orchestrator E2E Suite
+
+```bash
+./dev e2e orchestrator
+```
+
+Runs the orchestration-focused curl scenarios, including multi-instance flows and remote bridge attachment against the dedicated `pinchtab-bridge` Compose service.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `CI` | _(unset)_ | Set to `true` for longer health check timeouts (60s vs 30s) |
+
+### Temp Directory Layout
+
+Each E2E test run creates a single temp directory under `/tmp/pinchtab-test-*/`:
+
+```
+/tmp/pinchtab-test-123456789/
+├── pinchtab          # Compiled test binary
+├── state/            # Dashboard state (profiles, instances)
+└── profiles/         # Chrome user-data directories
+```
+
+Everything is cleaned up automatically when tests finish.
+
+## Test File Structure
+
+E2E tests are organized in two directories:
+
+- **`tests/e2e/scenarios/*.sh`** — HTTP curl-based tests (183 tests)
+  - Test the REST API directly
+  - Use Docker Compose: `tests/e2e/docker-compose.yml`
+
+- **`tests/e2e/scenarios-orchestrator/*.sh`** — orchestration-heavy curl tests
+  - Test multi-instance flows and remote bridge attachment
+  - Use Docker Compose: `tests/e2e/docker-compose-orchestrator.yml`
+
+- **`tests/e2e/scenarios-cli/*.sh`** — CLI e2e tests (41 tests)
+  - Test the command-line interface
+  - Use Docker Compose: `tests/e2e/docker-compose.cli.yml`
+
+Each test is a standalone bash script that:
+1. Starts the test server (or uses existing)
+2. Runs curl or CLI commands
+3. Asserts expected output or exit codes
+4. Cleans up
+
+## Writing New E2E Tests
+
+Create a new bash script in `tests/e2e/scenarios/` (for curl tests) or `tests/e2e/scenarios-cli/` (for CLI tests):
+
+### Example: Simple Curl Test
+
+```bash
+#!/bin/bash
+
+# tests/e2e/scenarios/test-my-feature.sh
+
+set -e  # Exit on error
+
+# Source helpers
+. "$(dirname "$0")/../helpers.sh"
+
+# Test setup
+SERVER_URL="http://localhost:9867"
+
+# Start server if needed
+start_test_server
+
+# Run test
+echo "Testing my feature..."
+RESPONSE=$(curl -s "$SERVER_URL/health")
+
+if [ "$(echo "$RESPONSE" | jq -r '.status')" != "ok" ]; then
+    echo "❌ Health check failed"
+    exit 1
+fi
+
+echo "✅ Test passed"
+```
+
+### Example: CLI Test
+
+```bash
+#!/bin/bash
+
+# tests/e2e/scenarios-cli/test-my-cli.sh
+
+set -e
+
+# Source helpers
+. "$(dirname "$0")/../helpers.sh"
+
+# Test the CLI
+echo "Testing pinchtab CLI..."
+OUTPUT=$($PINCHTAB_BIN --version)
+
+if [[ ! "$OUTPUT" =~ pinchtab ]]; then
+    echo "❌ Version output incorrect"
+    exit 1
+fi
+
+echo "✅ CLI test passed"
+```
+
+## Coverage
+
+Generate coverage for unit tests:
+
+```bash
+go test ./... -coverprofile=coverage.out
+go tool cover -html=coverage.out
+```
+
+Note: E2E tests are black-box tests and don't contribute to code coverage metrics directly.

THIRD_PARTY_LICENSES.md

@@ -0,0 +1,98 @@
+# Third-Party Licenses
+
+Pinchtab depends on the following open-source packages. All are compatible with MIT licensing.
+
+## Direct Dependencies
+
+### chromedp/chromedp
+- **License:** MIT
+- **Copyright:** (c) 2016-2025 Kenneth Shaw
+- **URL:** https://github.com/chromedp/chromedp
+- **Purpose:** Chrome DevTools Protocol driver — launches and controls Chrome
+
+### chromedp/cdproto
+- **License:** MIT
+- **Copyright:** (c) 2016-2025 Kenneth Shaw
+- **URL:** https://github.com/chromedp/cdproto
+- **Purpose:** Generated Go types for the Chrome DevTools Protocol
+
+## Transitive Dependencies
+
+### chromedp/sysutil
+- **License:** MIT
+- **Copyright:** (c) 2016-2017 Kenneth Shaw
+- **URL:** https://github.com/chromedp/sysutil
+- **Purpose:** System utilities for chromedp (finding Chrome binary)
+
+### go-json-experiment/json
+- **License:** BSD 3-Clause
+- **Copyright:** (c) 2020 The Go Authors
+- **URL:** https://github.com/go-json-experiment/json
+- **Purpose:** Experimental JSON library used by cdproto
+
+### gobwas/ws
+- **License:** MIT
+- **Copyright:** (c) 2017-2021 Sergey Kamardin
+- **URL:** https://github.com/gobwas/ws
+- **Purpose:** WebSocket implementation for CDP communication
+
+### gobwas/httphead
+- **License:** MIT
+- **Copyright:** (c) 2017 Sergey Kamardin
+- **URL:** https://github.com/gobwas/httphead
+- **Purpose:** HTTP header parsing (ws dependency)
+
+### gobwas/pool
+- **License:** MIT
+- **Copyright:** (c) 2017-2019 Sergey Kamardin
+- **URL:** https://github.com/gobwas/pool
+- **Purpose:** Pool utilities (ws dependency)
+
+### golang.org/x/sys
+- **License:** BSD 3-Clause
+- **Copyright:** (c) 2009 The Go Authors
+- **URL:** https://github.com/golang/sys
+- **Purpose:** Go system call wrappers
+
+### github.com/ledongthuc/pdf
+- **License:** BSD 3-Clause
+- **Copyright:** (c) 2009 The Go Authors
+- **URL:** https://github.com/ledongthuc/pdf
+- **Purpose:** Transitive dependency in module graph (test tooling chain)
+
+### github.com/orisano/pixelmatch
+- **License:** MIT
+- **Copyright:** (c) 2022 orisano
+- **URL:** https://github.com/orisano/pixelmatch
+- **Purpose:** Transitive dependency in module graph (test tooling chain)
+
+### gopkg.in/check.v1
+- **License:** BSD-style
+- **Copyright:** (c) 2010-2013 Gustavo Niemeyer
+- **URL:** https://gopkg.in/check.v1
+- **Purpose:** Transitive dependency in module graph (test tooling chain)
+
+### gopkg.in/yaml.v3
+- **License:** Apache 2.0 / MIT
+- **Copyright:** (c) 2006-2011 Kirill Simonov, (c) 2011-2019 Canonical Ltd
+- **URL:** https://github.com/go-yaml/yaml
+- **Purpose:** YAML output format for snapshots
+
+## Summary
+
+| Package | License | Compatible |
+|---------|---------|------------|
+| chromedp/chromedp | MIT | ✅ |
+| chromedp/cdproto | MIT | ✅ |
+| chromedp/sysutil | MIT | ✅ |
+| go-json-experiment/json | BSD 3-Clause | ✅ |
+| gobwas/ws | MIT | ✅ |
+| gobwas/httphead | MIT | ✅ |
+| gobwas/pool | MIT | ✅ |
+| golang.org/x/sys | BSD 3-Clause | ✅ |
+| github.com/ledongthuc/pdf | BSD 3-Clause | ✅ |
+| github.com/orisano/pixelmatch | MIT | ✅ |
+| gopkg.in/check.v1 | BSD-style | ✅ |
+| gopkg.in/yaml.v3 | Apache 2.0 / MIT | ✅ |
+
+All dependencies are MIT, BSD-style, or Apache 2.0 licensed, compatible with Pinchtab's MIT license.

cmd/pinchtab/build_test.go

@@ -0,0 +1,111 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"gopkg.in/yaml.v3"
+)
+
+// GoReleaserConfig represents the minimal goreleaser config we care about
+type GoReleaserConfig struct {
+	Builds []struct {
+		GOOS   []string `yaml:"goos"`
+		GOARCH []string `yaml:"goarch"`
+	} `yaml:"builds"`
+}
+
+// TestBinaryPermutations verifies all expected binary permutations are configured in goreleaser
+func TestBinaryPermutations(t *testing.T) {
+	// Find .goreleaser.yml in repo root (2 levels up from cmd/pinchtab/)
+	repoRoot := filepath.Join("..", "..", ".goreleaser.yml")
+	data, err := os.ReadFile(repoRoot)
+	if err != nil {
+		t.Fatalf("failed to read .goreleaser.yml at %s: %v", repoRoot, err)
+	}
+
+	var cfg GoReleaserConfig
+	if err := yaml.Unmarshal(data, &cfg); err != nil {
+		t.Fatalf("failed to parse .goreleaser.yml: %v", err)
+	}
+
+	if len(cfg.Builds) == 0 {
+		t.Fatal("no builds configured in .goreleaser.yml")
+	}
+
+	build := cfg.Builds[0]
+
+	// Expected OS/arch combinations
+	expectedOS := map[string]bool{
+		"linux":   true,
+		"darwin":  true,
+		"windows": true,
+	}
+
+	expectedArch := map[string]bool{
+		"amd64": true,
+		"arm64": true,
+	}
+
+	// Verify all expected OS are configured
+	for os := range expectedOS {
+		found := false
+		for _, configOS := range build.GOOS {
+			if configOS == os {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("OS %q not found in goreleaser config", os)
+		}
+	}
+
+	// Verify all expected architectures are configured
+	for arch := range expectedArch {
+		found := false
+		for _, configArch := range build.GOARCH {
+			if configArch == arch {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Architecture %q not found in goreleaser config", arch)
+		}
+	}
+
+	// Calculate expected binary count
+	totalExpected := len(expectedOS) * len(expectedArch)
+	totalConfigured := len(build.GOOS) * len(build.GOARCH)
+
+	if totalConfigured != totalExpected {
+		t.Errorf("expected %d binaries (3 OS × 2 arch), but config produces %d",
+			totalExpected, totalConfigured)
+	}
+
+	t.Logf("✓ Binary matrix verified: %d OS × %d arch = %d total binaries",
+		len(build.GOOS), len(build.GOARCH), totalConfigured)
+}
+
+// TestExpectedBinaryNames verifies correct naming for all permutations
+func TestExpectedBinaryNames(t *testing.T) {
+	expectedBinaries := []string{
+		"pinchtab-linux-amd64",
+		"pinchtab-linux-arm64",
+		"pinchtab-darwin-amd64",
+		"pinchtab-darwin-arm64",
+		"pinchtab-windows-amd64.exe",
+		"pinchtab-windows-arm64.exe",
+	}
+
+	if len(expectedBinaries) != 6 {
+		t.Errorf("expected 6 binaries, got %d", len(expectedBinaries))
+	}
+
+	t.Logf("Expected binary names (%d total):", len(expectedBinaries))
+	for _, bin := range expectedBinaries {
+		t.Logf("  ✓ %s", bin)
+	}
+}

cmd/pinchtab/cmd_bridge.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/pinchtab/pinchtab/internal/config"
+	"github.com/pinchtab/pinchtab/internal/server"
+	"github.com/spf13/cobra"
+)
+
+var bridgeEngine string
+
+var bridgeCmd = &cobra.Command{
+	Use:   "bridge",
+	Short: "Start single-instance bridge-only server",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg := config.Load()
+		engineMode, err := resolveBridgeEngine(bridgeEngine, cfg.Engine)
+		if err != nil {
+			return err
+		}
+		cfg.Engine = engineMode
+		server.RunBridgeServer(cfg)
+		return nil
+	},
+}
+
+func resolveBridgeEngine(flagValue, configValue string) (string, error) {
+	engineMode := strings.ToLower(strings.TrimSpace(configValue))
+	if strings.TrimSpace(flagValue) != "" {
+		engineMode = strings.ToLower(strings.TrimSpace(flagValue))
+	}
+	if engineMode == "" {
+		engineMode = "chrome"
+	}
+	if engineMode != "chrome" && engineMode != "lite" && engineMode != "auto" {
+		return "", fmt.Errorf("invalid --engine %q (expected chrome, lite, or auto)", engineMode)
+	}
+	return engineMode, nil
+}
+
+func init() {
+	bridgeCmd.GroupID = "primary"
+	bridgeCmd.Flags().StringVar(&bridgeEngine, "engine", "", "Bridge engine: chrome, lite, or auto (overrides config)")
+	rootCmd.AddCommand(bridgeCmd)
+}

cmd/pinchtab/cmd_bridge_test.go

@@ -0,0 +1,36 @@
+package main
+
+import "testing"
+
+func TestResolveBridgeEngine(t *testing.T) {
+	tests := []struct {
+		name      string
+		flagValue string
+		cfgValue  string
+		want      string
+		wantErr   bool
+	}{
+		{name: "config default", cfgValue: "lite", want: "lite"},
+		{name: "flag overrides config", flagValue: "auto", cfgValue: "chrome", want: "auto"},
+		{name: "empty falls back to chrome", want: "chrome"},
+		{name: "invalid", flagValue: "bogus", wantErr: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := resolveBridgeEngine(tt.flagValue, tt.cfgValue)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatal("expected error")
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got != tt.want {
+				t.Fatalf("got %q want %q", got, tt.want)
+			}
+		})
+	}
+}

cmd/pinchtab/cmd_cli.go

@@ -0,0 +1,593 @@
+package main
+
+import (
+	"fmt"
+	"net/http"
+	"os"
+	"strings"
+	"time"
+
+	browseractions "github.com/pinchtab/pinchtab/internal/cli/actions"
+	"github.com/pinchtab/pinchtab/internal/config"
+	"github.com/pinchtab/pinchtab/internal/urlutil"
+	"github.com/spf13/cobra"
+)
+
+var quickCmd = &cobra.Command{
+	Use:   "quick <url>",
+	Short: "Navigate + analyze page",
+	Args:  cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		args[0] = urlutil.Normalize(args[0])
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Quick(client, base, token, args)
+		})
+	},
+}
+
+var navCmd = &cobra.Command{
+	Use:     "nav <url>",
+	Aliases: []string{"goto", "navigate", "open"},
+	Short:   "Navigate to URL",
+	Args:    cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		url := urlutil.Normalize(args[0])
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Navigate(client, base, token, url, cmd)
+		})
+	},
+}
+
+var backCmd = &cobra.Command{
+	Use:   "back",
+	Short: "Go back in browser history",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Back(client, base, token, cmd)
+		})
+	},
+}
+
+var forwardCmd = &cobra.Command{
+	Use:   "forward",
+	Short: "Go forward in browser history",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Forward(client, base, token, cmd)
+		})
+	},
+}
+
+var reloadCmd = &cobra.Command{
+	Use:   "reload",
+	Short: "Reload current page",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Reload(client, base, token, cmd)
+		})
+	},
+}
+
+var snapCmd = &cobra.Command{
+	Use:   "snap",
+	Short: "Snapshot accessibility tree",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Snapshot(client, base, token, cmd)
+		})
+	},
+}
+
+var clickCmd = &cobra.Command{
+	Use:   "click <ref>",
+	Short: "Click element",
+	Args:  cobra.MaximumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		ref := ""
+		if len(args) > 0 {
+			ref = args[0]
+		}
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Action(client, base, token, "click", ref, cmd)
+		})
+	},
+}
+
+var dblclickCmd = &cobra.Command{
+	Use:   "dblclick <ref>",
+	Short: "Double-click element",
+	Args:  cobra.MaximumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		ref := ""
+		if len(args) > 0 {
+			ref = args[0]
+		}
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Action(client, base, token, "dblclick", ref, cmd)
+		})
+	},
+}
+
+var typeCmd = &cobra.Command{
+	Use:   "type <ref> <text>",
+	Short: "Type into element",
+	Args:  cobra.MinimumNArgs(2),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.ActionSimple(client, base, token, "type", args, cmd)
+		})
+	},
+}
+
+var screenshotCmd = &cobra.Command{
+	Use:   "screenshot",
+	Short: "Take a screenshot",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Screenshot(client, base, token, cmd)
+		})
+	},
+}
+
+var tabsCmd = &cobra.Command{
+	Use:     "tab [id]",
+	Aliases: []string{"tabs"},
+	Short:   "List tabs, or focus a tab by ID",
+	Args:    cobra.MaximumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			if len(args) == 0 {
+				browseractions.TabList(client, base, token)
+			} else {
+				browseractions.TabFocus(client, base, token, args[0])
+			}
+		})
+	},
+}
+
+var instancesCmd = &cobra.Command{
+	Use:   "instances",
+	Short: "List or manage instances",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Instances(client, base, token)
+		})
+	},
+}
+
+var healthCmd = &cobra.Command{
+	Use:   "health",
+	Short: "Check server health",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Health(client, base, token)
+		})
+	},
+}
+
+var pressCmd = &cobra.Command{
+	Use:   "press <key>",
+	Short: "Press key (Enter, Tab, Escape...)",
+	Args:  cobra.MinimumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.ActionSimple(client, base, token, "press", args, cmd)
+		})
+	},
+}
+
+var fillCmd = &cobra.Command{
+	Use:   "fill <ref|selector> <text>",
+	Short: "Fill input directly",
+	Args:  cobra.MinimumNArgs(2),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.ActionSimple(client, base, token, "fill", args, cmd)
+		})
+	},
+}
+
+var hoverCmd = &cobra.Command{
+	Use:   "hover <ref>",
+	Short: "Hover element",
+	Args:  cobra.MaximumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		ref := ""
+		if len(args) > 0 {
+			ref = args[0]
+		}
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Action(client, base, token, "hover", ref, cmd)
+		})
+	},
+}
+
+var scrollCmd = &cobra.Command{
+	Use:   "scroll <ref|pixels>",
+	Short: "Scroll to element or by pixels",
+	Args:  cobra.MinimumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.ActionSimple(client, base, token, "scroll", args, cmd)
+		})
+	},
+}
+
+var evalCmd = &cobra.Command{
+	Use:   "eval <expression>",
+	Short: "Evaluate JavaScript",
+	Args:  cobra.MinimumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Evaluate(client, base, token, args, cmd)
+		})
+	},
+}
+
+var pdfCmd = &cobra.Command{
+	Use:   "pdf",
+	Short: "Export the current page as PDF",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.PDF(client, base, token, cmd)
+		})
+	},
+}
+
+var textCmd = &cobra.Command{
+	Use:   "text",
+	Short: "Extract page text",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Text(client, base, token, cmd)
+		})
+	},
+}
+
+var downloadCmd = &cobra.Command{
+	Use:   "download <url>",
+	Short: "Download a file via browser session",
+	Args:  cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		args[0] = urlutil.Normalize(args[0])
+		output, _ := cmd.Flags().GetString("output")
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Download(client, base, token, args, output)
+		})
+	},
+}
+
+var uploadCmd = &cobra.Command{
+	Use:   "upload <file-path>",
+	Short: "Upload a file to a file input element",
+	Args:  cobra.MinimumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		selector, _ := cmd.Flags().GetString("selector")
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Upload(client, base, token, args, selector)
+		})
+	},
+}
+
+var profilesCmd = &cobra.Command{
+	Use:   "profiles",
+	Short: "List browser profiles",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Profiles(client, base, token)
+		})
+	},
+}
+
+var instanceCmd = &cobra.Command{
+	Use:   "instance",
+	Short: "Manage browser instances",
+}
+
+var findCmd = &cobra.Command{
+	Use:   "find <query>",
+	Short: "Find elements by natural language query",
+	Args:  cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Find(client, base, token, args[0], cmd)
+		})
+	},
+}
+
+var selectCmd = &cobra.Command{
+	Use:   "select <ref> <value>",
+	Short: "Select option in dropdown",
+	Args:  cobra.MinimumNArgs(2),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.ActionSimple(client, base, token, "select", args, cmd)
+		})
+	},
+}
+
+var checkCmd = &cobra.Command{
+	Use:   "check <selector>",
+	Short: "Check a checkbox or radio",
+	Args:  cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Action(client, base, token, "check", args[0], cmd)
+		})
+	},
+}
+
+var uncheckCmd = &cobra.Command{
+	Use:   "uncheck <selector>",
+	Short: "Uncheck a checkbox or radio",
+	Args:  cobra.ExactArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runCLIWith(cfg, func(client *http.Client, base, token string) {
+			browseractions.Action(client, base, token, "uncheck", args[0], cmd)
+		})
+	},
+}
+
+func init() {
+	quickCmd.GroupID = "browser"
+	navCmd.GroupID = "browser"
+	backCmd.GroupID = "browser"
+	forwardCmd.GroupID = "browser"
+	reloadCmd.GroupID = "browser"
+	snapCmd.GroupID = "browser"
+	clickCmd.GroupID = "browser"
+	typeCmd.GroupID = "browser"
+	screenshotCmd.GroupID = "browser"
+	tabsCmd.GroupID = "browser"
+	instancesCmd.GroupID = "management"
+	healthCmd.GroupID = "management"
+	pressCmd.GroupID = "browser"
+	fillCmd.GroupID = "browser"
+	hoverCmd.GroupID = "browser"
+	scrollCmd.GroupID = "browser"
+	evalCmd.GroupID = "browser"
+	pdfCmd.GroupID = "browser"
+	textCmd.GroupID = "browser"
+	profilesCmd.GroupID = "management"
+	downloadCmd.GroupID = "browser"
+	uploadCmd.GroupID = "browser"
+	findCmd.GroupID = "browser"
+	selectCmd.GroupID = "browser"
+	checkCmd.GroupID = "browser"
+	uncheckCmd.GroupID = "browser"
+
+	tabsCmd.AddCommand(&cobra.Command{
+		Use:   "new [url]",
+		Short: "Open a new tab",
+		Args:  cobra.MaximumNArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			cfg := config.Load()
+			runCLIWith(cfg, func(client *http.Client, base, token string) {
+				body := map[string]any{"action": "new"}
+				if len(args) > 0 {
+					body["url"] = urlutil.Normalize(args[0])
+				}
+				browseractions.TabNew(client, base, token, body)
+			})
+		},
+	})
+	tabsCmd.AddCommand(&cobra.Command{
+		Use:   "close <id>",
+		Short: "Close a tab by ID",
+		Args:  cobra.ExactArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			cfg := config.Load()
+			runCLIWith(cfg, func(client *http.Client, base, token string) {
+				browseractions.TabClose(client, base, token, args[0])
+			})
+		},
+	})
+
+	uploadCmd.Flags().StringP("selector", "s", "", "CSS selector for file input")
+	downloadCmd.Flags().StringP("output", "o", "", "Save downloaded file to path")
+
+	clickCmd.Flags().String("css", "", "CSS selector instead of ref")
+	clickCmd.Flags().Float64("x", 0, "X coordinate for click")
+	clickCmd.Flags().Float64("y", 0, "Y coordinate for click")
+	clickCmd.Flags().Bool("wait-nav", false, "Wait for navigation after click")
+	dblclickCmd.Flags().String("css", "", "CSS selector instead of ref")
+	dblclickCmd.Flags().Float64("x", 0, "X coordinate for dblclick")
+	dblclickCmd.Flags().Float64("y", 0, "Y coordinate for dblclick")
+	hoverCmd.Flags().String("css", "", "CSS selector instead of ref")
+	hoverCmd.Flags().Float64("x", 0, "X coordinate for hover")
+	hoverCmd.Flags().Float64("y", 0, "Y coordinate for hover")
+
+	snapCmd.Flags().BoolP("interactive", "i", false, "Filter interactive elements only")
+	snapCmd.Flags().BoolP("compact", "c", false, "Compact output format")
+	snapCmd.Flags().Bool("text", false, "Text output format")
+	snapCmd.Flags().BoolP("diff", "d", false, "Show diff from previous snapshot")
+	snapCmd.Flags().StringP("selector", "s", "", "CSS selector to scope snapshot")
+	snapCmd.Flags().String("max-tokens", "", "Maximum token budget")
+	snapCmd.Flags().String("depth", "", "Tree depth limit")
+	snapCmd.Flags().String("tab", "", "Tab ID")
+
+	screenshotCmd.Flags().StringP("output", "o", "", "Save screenshot to file path")
+	screenshotCmd.Flags().StringP("quality", "q", "", "JPEG quality (0-100)")
+	screenshotCmd.Flags().String("tab", "", "Tab ID")
+
+	pdfCmd.Flags().StringP("output", "o", "", "Save PDF to file path")
+	pdfCmd.Flags().String("tab", "", "Tab ID")
+	pdfCmd.Flags().Bool("landscape", false, "Landscape orientation")
+	pdfCmd.Flags().String("scale", "", "Page scale (e.g. 0.5)")
+	pdfCmd.Flags().String("paper-width", "", "Paper width (inches)")
+	pdfCmd.Flags().String("paper-height", "", "Paper height (inches)")
+	pdfCmd.Flags().String("margin-top", "", "Top margin")
+	pdfCmd.Flags().String("margin-bottom", "", "Bottom margin")
+	pdfCmd.Flags().String("margin-left", "", "Left margin")
+	pdfCmd.Flags().String("margin-right", "", "Right margin")
+	pdfCmd.Flags().String("page-ranges", "", "Page ranges (e.g. 1-3)")
+	pdfCmd.Flags().Bool("prefer-css-page-size", false, "Use CSS page size")
+	pdfCmd.Flags().Bool("display-header-footer", false, "Show header/footer")
+	pdfCmd.Flags().String("header-template", "", "Header HTML template")
+	pdfCmd.Flags().String("footer-template", "", "Footer HTML template")
+	pdfCmd.Flags().Bool("generate-tagged-pdf", false, "Generate tagged PDF")
+	pdfCmd.Flags().Bool("generate-document-outline", false, "Generate document outline")
+	pdfCmd.Flags().Bool("file-output", false, "Use server-side file output")
+	pdfCmd.Flags().String("path", "", "Server-side output path")
+
+	findCmd.Flags().String("tab", "", "Tab ID")
+	findCmd.Flags().String("threshold", "", "Minimum similarity score (0-1)")
+	findCmd.Flags().Bool("explain", false, "Show score breakdown")
+	findCmd.Flags().Bool("ref-only", false, "Output just the element ref")
+
+	textCmd.Flags().Bool("raw", false, "Raw extraction mode")
+	textCmd.Flags().String("tab", "", "Tab ID")
+
+	navCmd.Flags().Bool("new-tab", false, "Open in new tab")
+	navCmd.Flags().Bool("block-images", false, "Block image loading")
+	navCmd.Flags().Bool("block-ads", false, "Block ads")
+	navCmd.Flags().String("tab", "", "Tab ID")
+	backCmd.Flags().String("tab", "", "Tab ID")
+	forwardCmd.Flags().String("tab", "", "Tab ID")
+	reloadCmd.Flags().String("tab", "", "Tab ID")
+
+	clickCmd.Flags().String("tab", "", "Tab ID")
+	dblclickCmd.Flags().String("tab", "", "Tab ID")
+	hoverCmd.Flags().String("tab", "", "Tab ID")
+	typeCmd.Flags().String("tab", "", "Tab ID")
+	pressCmd.Flags().String("tab", "", "Tab ID")
+	fillCmd.Flags().String("tab", "", "Tab ID")
+	scrollCmd.Flags().String("tab", "", "Tab ID")
+	selectCmd.Flags().String("tab", "", "Tab ID")
+	evalCmd.Flags().String("tab", "", "Tab ID")
+	checkCmd.Flags().String("tab", "", "Tab ID")
+	uncheckCmd.Flags().String("tab", "", "Tab ID")
+
+	rootCmd.AddCommand(quickCmd)
+	rootCmd.AddCommand(navCmd)
+	rootCmd.AddCommand(backCmd)
+	rootCmd.AddCommand(forwardCmd)
+	rootCmd.AddCommand(reloadCmd)
+	rootCmd.AddCommand(snapCmd)
+	rootCmd.AddCommand(clickCmd)
+	rootCmd.AddCommand(dblclickCmd)
+	rootCmd.AddCommand(typeCmd)
+	rootCmd.AddCommand(screenshotCmd)
+	rootCmd.AddCommand(tabsCmd)
+	rootCmd.AddCommand(instancesCmd)
+	rootCmd.AddCommand(healthCmd)
+	rootCmd.AddCommand(pressCmd)
+	rootCmd.AddCommand(fillCmd)
+	rootCmd.AddCommand(hoverCmd)
+	rootCmd.AddCommand(scrollCmd)
+	rootCmd.AddCommand(evalCmd)
+	rootCmd.AddCommand(pdfCmd)
+	rootCmd.AddCommand(textCmd)
+	rootCmd.AddCommand(profilesCmd)
+	rootCmd.AddCommand(downloadCmd)
+	rootCmd.AddCommand(uploadCmd)
+	rootCmd.AddCommand(findCmd)
+	rootCmd.AddCommand(selectCmd)
+	rootCmd.AddCommand(checkCmd)
+	rootCmd.AddCommand(uncheckCmd)
+
+	instanceCmd.GroupID = "management"
+
+	startInstanceCmd := &cobra.Command{
+		Use:   "start",
+		Short: "Start a browser instance",
+		Run: func(cmd *cobra.Command, args []string) {
+			cfg := config.Load()
+			runCLIWith(cfg, func(client *http.Client, base, token string) {
+				browseractions.InstanceStart(client, base, token, cmd)
+			})
+		},
+	}
+	startInstanceCmd.Flags().String("profile", "", "Profile to use")
+	startInstanceCmd.Flags().String("mode", "", "Instance mode")
+	startInstanceCmd.Flags().String("port", "", "Port number")
+	startInstanceCmd.Flags().StringArray("extension", nil, "Load browser extension (repeatable)")
+	instanceCmd.AddCommand(startInstanceCmd)
+
+	instanceCmd.AddCommand(&cobra.Command{
+		Use:   "navigate <id> <url>",
+		Short: "Navigate an instance to a URL",
+		Args:  cobra.ExactArgs(2),
+		Run: func(cmd *cobra.Command, args []string) {
+			args[1] = urlutil.Normalize(args[1])
+			cfg := config.Load()
+			runCLIWith(cfg, func(client *http.Client, base, token string) {
+				browseractions.InstanceNavigate(client, base, token, args)
+			})
+		},
+	})
+	instanceCmd.AddCommand(&cobra.Command{
+		Use:   "stop <id>",
+		Short: "Stop a browser instance",
+		Args:  cobra.ExactArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			cfg := config.Load()
+			runCLIWith(cfg, func(client *http.Client, base, token string) {
+				browseractions.InstanceStop(client, base, token, args)
+			})
+		},
+	})
+	instanceCmd.AddCommand(&cobra.Command{
+		Use:   "logs <id>",
+		Short: "Get instance logs",
+		Args:  cobra.ExactArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			cfg := config.Load()
+			runCLIWith(cfg, func(client *http.Client, base, token string) {
+				browseractions.InstanceLogs(client, base, token, args)
+			})
+		},
+	})
+	rootCmd.AddCommand(instanceCmd)
+}
+
+func runCLIWith(cfg *config.RuntimeConfig, fn func(client *http.Client, base, token string)) {
+	client := &http.Client{Timeout: 60 * time.Second}
+
+	// Default: http://127.0.0.1:{port}
+	port := cfg.Port
+	if port == "" {
+		port = "9867"
+	}
+	base := fmt.Sprintf("http://127.0.0.1:%s", port)
+
+	// --server flag overrides
+	if serverURL != "" {
+		base = strings.TrimRight(serverURL, "/")
+	}
+
+	// Token from config, env var overrides
+	token := cfg.Token
+	if envToken := os.Getenv("PINCHTAB_TOKEN"); envToken != "" {
+		token = envToken
+	}
+
+	fn(client, base, token)
+}

cmd/pinchtab/cmd_completion.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+var completionCmd = &cobra.Command{
+	Use:   "completion [bash|zsh|fish|powershell]",
+	Short: "Generate shell completion script",
+	Long: `Generate a shell completion script for pinchtab.
+
+To load completions:
+
+Bash:
+  $ source <(pinchtab completion bash)
+
+  # To load completions for each session, execute once:
+  # Linux:
+  $ pinchtab completion bash > /etc/bash_completion.d/pinchtab
+  # macOS:
+  $ pinchtab completion bash > $(brew --prefix)/etc/bash_completion.d/pinchtab
+
+Zsh:
+  # If shell completion is not already enabled in your environment,
+  # you will need to enable it. You can execute the following once:
+  $ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+  # To load completions for each session, execute once:
+  $ pinchtab completion zsh > "${fpath[1]}/_pinchtab"
+
+  # You will need to start a new shell for this setup to take effect.
+
+Fish:
+  $ pinchtab completion fish | source
+
+  # To load completions for each session, execute once:
+  $ pinchtab completion fish > ~/.config/fish/completions/pinchtab.fish
+
+PowerShell:
+  PS> pinchtab completion powershell | Out-String | Invoke-Expression
+
+  # To load completions for every new session, add the output to your profile:
+  PS> pinchtab completion powershell > pinchtab.ps1
+  # and source this file from your PowerShell profile.
+`,
+	DisableFlagsInUseLine: true,
+	ValidArgs:             []string{"bash", "zsh", "fish", "powershell"},
+	Args:                  cobra.MatchAll(cobra.ExactArgs(1), cobra.OnlyValidArgs),
+	RunE: func(cmd *cobra.Command, args []string) error {
+		switch args[0] {
+		case "bash":
+			return rootCmd.GenBashCompletion(os.Stdout)
+		case "zsh":
+			return rootCmd.GenZshCompletion(os.Stdout)
+		case "fish":
+			return rootCmd.GenFishCompletion(os.Stdout, true)
+		case "powershell":
+			return rootCmd.GenPowerShellCompletionWithDesc(os.Stdout)
+		}
+		return nil
+	},
+}
+
+func init() {
+	completionCmd.GroupID = "config"
+	rootCmd.AddCommand(completionCmd)
+}

cmd/pinchtab/cmd_config.go

@@ -0,0 +1,437 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/pinchtab/pinchtab/internal/cli"
+	"github.com/pinchtab/pinchtab/internal/config"
+	"github.com/pinchtab/pinchtab/internal/server"
+	"github.com/spf13/cobra"
+)
+
+var clipboardExecCommand = exec.Command
+
+var configCmd = &cobra.Command{
+	Use:   "config",
+	Short: "Manage configuration",
+	Run: func(cmd *cobra.Command, args []string) {
+		handleConfigOverview(loadConfig())
+	},
+}
+
+func init() {
+	configCmd.GroupID = "config"
+	configCmd.AddCommand(&cobra.Command{
+		Use:   "show",
+		Short: "Display current configuration",
+		Run: func(cmd *cobra.Command, args []string) {
+			cfg := config.Load()
+			cli.HandleConfigShow(cfg)
+		},
+	})
+	configCmd.AddCommand(&cobra.Command{
+		Use:   "init",
+		Short: "Initialize a new config file",
+		Run: func(cmd *cobra.Command, args []string) {
+			handleConfigInit()
+		},
+	})
+	configCmd.AddCommand(&cobra.Command{
+		Use:   "path",
+		Short: "Show config file path",
+		Run: func(cmd *cobra.Command, args []string) {
+			handleConfigPath()
+		},
+	})
+	configCmd.AddCommand(&cobra.Command{
+		Use:   "validate",
+		Short: "Validate config file",
+		Run: func(cmd *cobra.Command, args []string) {
+			handleConfigValidate()
+		},
+	})
+	configCmd.AddCommand(&cobra.Command{
+		Use:   "get <path>",
+		Short: "Get a config value (e.g., server.port)",
+		Args:  cobra.ExactArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			handleConfigGet(args[0])
+		},
+	})
+	configCmd.AddCommand(&cobra.Command{
+		Use:   "set <path> <val>",
+		Short: "Set a config value (e.g., server.port 8080)",
+		Args:  cobra.ExactArgs(2),
+		Run: func(cmd *cobra.Command, args []string) {
+			handleConfigSet(args[0], args[1])
+		},
+	})
+	configCmd.AddCommand(&cobra.Command{
+		Use:   "patch <json>",
+		Short: "Merge JSON into config",
+		Args:  cobra.ExactArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			handleConfigPatch(args[0])
+		},
+	})
+
+	rootCmd.AddCommand(configCmd)
+}
+
+func handleConfigOverview(cfg *config.RuntimeConfig) {
+	_, configPath, err := config.LoadFileConfig()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, fmt.Sprintf("Error loading config path: %v", err)))
+		os.Exit(1)
+	}
+
+	dashPort := cfg.Port
+	if dashPort == "" {
+		dashPort = "9870"
+	}
+	dashboardURL := fmt.Sprintf("http://localhost:%s", dashPort)
+	running := server.CheckPinchTabRunning(dashPort, cfg.Token)
+
+	for {
+		fmt.Print(renderConfigOverview(cfg, configPath, dashboardURL, running))
+
+		if !isInteractiveTerminal() {
+			return
+		}
+
+		nextCfg, changed, done, err := promptConfigEdit(cfg)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, err.Error()))
+			fmt.Println()
+			continue
+		}
+		if done {
+			return
+		}
+		if !changed {
+			fmt.Println()
+			continue
+		}
+
+		cfg = nextCfg
+		dashPort = cfg.Port
+		if dashPort == "" {
+			dashPort = "9870"
+		}
+		dashboardURL = fmt.Sprintf("http://localhost:%s", dashPort)
+		running = server.CheckPinchTabRunning(dashPort, cfg.Token)
+		fmt.Println()
+	}
+}
+
+func renderConfigOverview(cfg *config.RuntimeConfig, configPath, dashboardURL string, running bool) string {
+	out := ""
+	out += cli.StyleStdout(cli.HeadingStyle, "Config") + "\n\n"
+	out += fmt.Sprintf("  1. %-18s %s\n", "Strategy", cli.StyleStdout(cli.ValueStyle, cfg.Strategy))
+	out += fmt.Sprintf("  2. %-18s %s\n", "Allocation policy", cli.StyleStdout(cli.ValueStyle, cfg.AllocationPolicy))
+	out += fmt.Sprintf("  3. %-18s %s\n", "Stealth level", cli.StyleStdout(cli.ValueStyle, cfg.StealthLevel))
+	out += fmt.Sprintf("  4. %-18s %s\n", "Tab eviction", cli.StyleStdout(cli.ValueStyle, cfg.TabEvictionPolicy))
+	out += fmt.Sprintf("  5. %-18s %s\n", "Copy token", cli.StyleStdout(cli.MutedStyle, "clipboard"))
+	out += "\n"
+	out += cli.StyleStdout(cli.HeadingStyle, "More") + "\n\n"
+	out += fmt.Sprintf("  %s %s\n", cli.StyleStdout(cli.MutedStyle, "File:"), cli.StyleStdout(cli.ValueStyle, configPath))
+	out += fmt.Sprintf("  %s %s\n", cli.StyleStdout(cli.MutedStyle, "Token:"), cli.StyleStdout(cli.ValueStyle, config.MaskToken(cfg.Token)))
+	if running {
+		out += fmt.Sprintf("  %s %s\n", cli.StyleStdout(cli.MutedStyle, "Dashboard:"), cli.StyleStdout(cli.ValueStyle, dashboardURL))
+	} else {
+		out += fmt.Sprintf("  %s %s\n", cli.StyleStdout(cli.MutedStyle, "Dashboard:"), cli.StyleStdout(cli.MutedStyle, "not running"))
+	}
+	if isInteractiveTerminal() {
+		out += "\n"
+		out += cli.StyleStdout(cli.MutedStyle, "Edit item (1-5, blank to exit):") + " "
+	}
+	out += "\n"
+	return out
+}
+
+func promptConfigEdit(cfg *config.RuntimeConfig) (*config.RuntimeConfig, bool, bool, error) {
+	choice, err := promptInput("", "")
+	if err != nil {
+		return nil, false, false, err
+	}
+	choice = strings.TrimSpace(choice)
+	if choice == "" {
+		return nil, false, true, nil
+	}
+
+	switch choice {
+	case "1":
+		nextCfg, changed, err := editConfigSelection("Instance strategy", "multiInstance.strategy", cfg.Strategy, config.ValidStrategies())
+		return nextCfg, changed, false, err
+	case "2":
+		nextCfg, changed, err := editConfigSelection("Allocation policy", "multiInstance.allocationPolicy", cfg.AllocationPolicy, config.ValidAllocationPolicies())
+		return nextCfg, changed, false, err
+	case "3":
+		nextCfg, changed, err := editConfigSelection("Default stealth level", "instanceDefaults.stealthLevel", cfg.StealthLevel, config.ValidStealthLevels())
+		return nextCfg, changed, false, err
+	case "4":
+		nextCfg, changed, err := editConfigSelection("Default tab eviction", "instanceDefaults.tabEvictionPolicy", cfg.TabEvictionPolicy, config.ValidEvictionPolicies())
+		return nextCfg, changed, false, err
+	case "5":
+		if err := copyConfigToken(cfg.Token); err != nil {
+			return nil, false, false, err
+		}
+		return nil, false, false, nil
+	default:
+		return nil, false, false, fmt.Errorf("invalid selection %q", choice)
+	}
+}
+
+func editConfigSelection(title, path, current string, values []string) (*config.RuntimeConfig, bool, error) {
+	options := make([]menuOption, 0, len(values)+1)
+	for _, value := range values {
+		label := value
+		if value == current {
+			label += " (current)"
+		}
+		options = append(options, menuOption{label: label, value: value})
+	}
+	options = append(options, menuOption{label: "Cancel", value: "cancel"})
+
+	picked, err := promptSelect(title, options)
+	if err != nil {
+		return nil, false, err
+	}
+	if picked == "" || picked == "cancel" {
+		return nil, false, nil
+	}
+
+	nextCfg, changed, err := updateConfigValue(path, picked)
+	if err != nil {
+		return nil, false, err
+	}
+	if changed {
+		fmt.Println(cli.StyleStdout(cli.SuccessStyle, fmt.Sprintf("Updated %s to %s", path, picked)))
+		fmt.Println(cli.StyleStdout(cli.MutedStyle, "Restart PinchTab to apply file-based changes."))
+	}
+	return nextCfg, changed, nil
+}
+
+func copyConfigToken(token string) error {
+	if strings.TrimSpace(token) == "" {
+		return fmt.Errorf("server token is empty")
+	}
+
+	if err := copyToClipboard(token); err == nil {
+		fmt.Println(cli.StyleStdout(cli.SuccessStyle, "Token copied to clipboard."))
+		return nil
+	}
+
+	fmt.Println(cli.StyleStdout(cli.WarningStyle, "Clipboard unavailable; copy the token manually:"))
+	fmt.Println(cli.StyleStdout(cli.ValueStyle, token))
+	return nil
+}
+
+func copyToClipboard(text string) error {
+	candidates := clipboardCommands()
+	var lastErr error
+
+	for _, candidate := range candidates {
+		if _, err := exec.LookPath(candidate.name); err != nil {
+			lastErr = err
+			continue
+		}
+		cmd := clipboardExecCommand(candidate.name, candidate.args...)
+		cmd.Stdin = strings.NewReader(text)
+		if output, err := cmd.CombinedOutput(); err != nil {
+			if len(strings.TrimSpace(string(output))) > 0 {
+				lastErr = fmt.Errorf("%s: %s", err, strings.TrimSpace(string(output)))
+			} else {
+				lastErr = err
+			}
+			continue
+		}
+		return nil
+	}
+
+	if lastErr == nil {
+		return fmt.Errorf("no clipboard command available")
+	}
+	return lastErr
+}
+
+type clipboardCommand struct {
+	name string
+	args []string
+}
+
+func clipboardCommands() []clipboardCommand {
+	switch runtime.GOOS {
+	case "darwin":
+		return []clipboardCommand{{name: "pbcopy"}}
+	case "windows":
+		return []clipboardCommand{{name: "clip"}}
+	default:
+		return []clipboardCommand{
+			{name: "wl-copy"},
+			{name: "xclip", args: []string{"-selection", "clipboard"}},
+			{name: "xsel", args: []string{"--clipboard", "--input"}},
+		}
+	}
+}
+
+func handleConfigInit() {
+	configPath := os.Getenv("PINCHTAB_CONFIG")
+	if configPath == "" {
+		configPath = config.DefaultConfigPath()
+	}
+
+	if _, err := os.Stat(configPath); err == nil {
+		fmt.Printf("Config file already exists at %s\n", configPath)
+		fmt.Print("Overwrite? (y/N): ")
+		var response string
+		_, _ = fmt.Scanln(&response)
+		if response != "y" && response != "Y" {
+			return
+		}
+	}
+
+	if err := os.MkdirAll(filepath.Dir(configPath), 0o755); err != nil {
+		fmt.Printf("Error creating directory: %v\n", err)
+		os.Exit(1)
+	}
+
+	fc := config.DefaultFileConfig()
+	token, err := config.GenerateAuthToken()
+	if err != nil {
+		fmt.Printf("Error generating auth token: %v\n", err)
+		os.Exit(1)
+	}
+	fc.Server.Token = token
+
+	if err := config.SaveFileConfig(&fc, configPath); err != nil {
+		fmt.Printf("Error writing config: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("Config file created at %s\n", configPath)
+}
+
+func handleConfigPath() {
+	configPath := os.Getenv("PINCHTAB_CONFIG")
+	if configPath == "" {
+		configPath = config.DefaultConfigPath()
+	}
+	fmt.Println(configPath)
+}
+
+func handleConfigGet(path string) {
+	fc, _, err := config.LoadFileConfig()
+	if err != nil {
+		fmt.Printf("Error loading config: %v\n", err)
+		os.Exit(1)
+	}
+
+	value, err := config.GetConfigValue(fc, path)
+	if err != nil {
+		fmt.Printf("Error: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Println(value)
+}
+
+func handleConfigSet(path, value string) {
+	fc, configPath, err := config.LoadFileConfig()
+	if err != nil {
+		fmt.Printf("Error loading config: %v\n", err)
+		os.Exit(1)
+	}
+
+	if err := config.SetConfigValue(fc, path, value); err != nil {
+		fmt.Printf("Error: %v\n", err)
+		os.Exit(1)
+	}
+
+	if errs := config.ValidateFileConfig(fc); len(errs) > 0 {
+		fmt.Printf("Warning: new value causes validation error(s):\n")
+		for _, err := range errs {
+			fmt.Printf("  - %v\n", err)
+		}
+		fmt.Print("Save anyway? (y/N): ")
+		var response string
+		_, _ = fmt.Scanln(&response)
+		if response != "y" && response != "Y" {
+			return
+		}
+	}
+
+	if err := config.SaveFileConfig(fc, configPath); err != nil {
+		fmt.Printf("Error saving config: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Printf("Set %s = %s\n", path, value)
+}
+
+func handleConfigPatch(jsonPatch string) {
+	fc, configPath, err := config.LoadFileConfig()
+	if err != nil {
+		fmt.Printf("Error loading config: %v\n", err)
+		os.Exit(1)
+	}
+
+	if err := config.PatchConfigJSON(fc, jsonPatch); err != nil {
+		fmt.Printf("Error: %v\n", err)
+		os.Exit(1)
+	}
+
+	if errs := config.ValidateFileConfig(fc); len(errs) > 0 {
+		fmt.Printf("Warning: patch causes validation error(s):\n")
+		for _, err := range errs {
+			fmt.Printf("  - %v\n", err)
+		}
+		fmt.Print("Save anyway? (y/N): ")
+		var response string
+		_, _ = fmt.Scanln(&response)
+		if response != "y" && response != "Y" {
+			return
+		}
+	}
+
+	if err := config.SaveFileConfig(fc, configPath); err != nil {
+		fmt.Printf("Error saving config: %v\n", err)
+		os.Exit(1)
+	}
+
+	fmt.Println("Config patched successfully")
+}
+
+func handleConfigValidate() {
+	configPath := os.Getenv("PINCHTAB_CONFIG")
+	if configPath == "" {
+		configPath = config.DefaultConfigPath()
+	}
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		fmt.Printf("Error reading config file: %v\n", err)
+		os.Exit(1)
+	}
+
+	fc := &config.FileConfig{}
+	if err := json.Unmarshal(data, fc); err != nil {
+		fmt.Printf("Error parsing config: %v\n", err)
+		os.Exit(1)
+	}
+
+	if errs := config.ValidateFileConfig(fc); len(errs) > 0 {
+		fmt.Printf("Config file has %d error(s):\n", len(errs))
+		for _, err := range errs {
+			fmt.Printf("  - %v\n", err)
+		}
+		os.Exit(1)
+	}
+
+	fmt.Printf("Config file is valid: %s\n", configPath)
+}

cmd/pinchtab/cmd_config_test.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/pinchtab/pinchtab/internal/config"
+)
+
+func TestRenderConfigOverview(t *testing.T) {
+	cfg := &config.RuntimeConfig{
+		Port:              "9867",
+		Strategy:          "simple",
+		AllocationPolicy:  "fcfs",
+		StealthLevel:      "light",
+		TabEvictionPolicy: "close_lru",
+		Token:             "very-long-token-secret",
+	}
+	output := renderConfigOverview(cfg, "/tmp/pinchtab/config.json", "http://localhost:9867", false)
+
+	required := []string{
+		"Config",
+		"Strategy",
+		"Allocation policy",
+		"Stealth level",
+		"Tab eviction",
+		"Copy token",
+		"More",
+		"/tmp/pinchtab/config.json",
+		"very...cret",
+		"Dashboard:",
+	}
+	for _, needle := range required {
+		if !strings.Contains(output, needle) {
+			t.Fatalf("expected config overview to contain %q\n%s", needle, output)
+		}
+	}
+}
+
+func TestClipboardCommands(t *testing.T) {
+	commands := clipboardCommands()
+	if len(commands) == 0 {
+		t.Fatal("expected clipboard commands")
+	}
+	for _, command := range commands {
+		if command.name == "" {
+			t.Fatalf("clipboard command missing name: %+v", command)
+		}
+	}
+}

cmd/pinchtab/cmd_daemon.go

@@ -0,0 +1,700 @@
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"os/user"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/pinchtab/pinchtab/internal/cli"
+	"github.com/pinchtab/pinchtab/internal/config"
+	"github.com/spf13/cobra"
+)
+
+const (
+	pinchtabDaemonUnitName = "pinchtab.service"
+	pinchtabLaunchdLabel   = "com.pinchtab.pinchtab"
+)
+
+var daemonCmd = &cobra.Command{
+	Use:   "daemon [action]",
+	Short: "Manage the background service",
+	Long:  "Start, stop, install, or check the status of the PinchTab background service.",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		sub := ""
+		if len(args) > 0 {
+			sub = args[0]
+		}
+		handleDaemonCommand(cfg, sub)
+	},
+}
+
+func init() {
+	daemonCmd.GroupID = "primary"
+	rootCmd.AddCommand(daemonCmd)
+}
+
+func handleDaemonCommand(_ *config.RuntimeConfig, subcommand string) {
+	if subcommand == "" || subcommand == "help" || subcommand == "--help" || subcommand == "-h" {
+		printDaemonStatusSummary()
+
+		if subcommand == "" && isInteractiveTerminal() {
+			picked, err := promptSelect("Daemon Actions", daemonMenuOptions(cli.IsDaemonInstalled(), cli.IsDaemonRunning()))
+			if err != nil || picked == "exit" || picked == "" {
+				os.Exit(0)
+			}
+			subcommand = picked
+		} else {
+			daemonUsage()
+			if subcommand == "" {
+				os.Exit(0)
+			}
+			return
+		}
+	}
+
+	manager, err := currentDaemonManager()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, err.Error()))
+		os.Exit(1)
+	}
+
+	switch subcommand {
+	case "install":
+		configPath, fileCfg, _, err := ensureDaemonConfig(false)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, fmt.Sprintf("daemon install failed: %v", err)))
+			os.Exit(1)
+		}
+		// Run wizard if needed (first install or version upgrade)
+		if config.NeedsWizard(fileCfg) {
+			isNew := config.IsFirstRun(fileCfg)
+			runSecurityWizard(fileCfg, configPath, isNew)
+		}
+		if err := manager.Preflight(); err != nil {
+			fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, fmt.Sprintf("daemon install unavailable: %v", err)))
+			os.Exit(1)
+		}
+		message, err := manager.Install(managerEnvironment(manager).execPath, configPath)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, fmt.Sprintf("daemon install failed: %v", err)))
+			fmt.Println()
+			fmt.Println(manager.ManualInstructions())
+			os.Exit(1)
+		}
+		fmt.Println(cli.StyleStdout(cli.SuccessStyle, "  [ok] ") + message)
+		printDaemonFollowUp()
+	case "start":
+		printDaemonManagerResult(manager.Start())
+	case "restart":
+		printDaemonManagerResult(manager.Restart())
+	case "stop":
+		printDaemonManagerResult(manager.Stop())
+	case "uninstall":
+		message, err := manager.Uninstall()
+		if err != nil {
+			fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, err.Error()))
+			fmt.Println()
+			fmt.Println(manager.ManualInstructions())
+			os.Exit(1)
+		}
+		fmt.Println(cli.StyleStdout(cli.SuccessStyle, "  [ok] ") + message)
+	default:
+		fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, fmt.Sprintf("unknown daemon command: %s", subcommand)))
+		daemonUsage()
+		os.Exit(2)
+	}
+}
+
+func daemonUsage() {
+	fmt.Println(cli.StyleStdout(cli.HeadingStyle, "Usage:") + " " + cli.StyleStdout(cli.CommandStyle, "pinchtab daemon <install|start|restart|stop|uninstall>"))
+	fmt.Println()
+	fmt.Println(cli.StyleStdout(cli.MutedStyle, "Manage the PinchTab user-level background service."))
+	fmt.Println()
+}
+
+func daemonMenuOptions(installed, running bool) []menuOption {
+	options := make([]menuOption, 0, 4)
+	switch {
+	case !installed:
+		options = append(options, menuOption{label: "Install service", value: "install"})
+	case running:
+		options = append(options,
+			menuOption{label: "Stop service", value: "stop"},
+			menuOption{label: "Restart service", value: "restart"},
+			menuOption{label: "Uninstall service", value: "uninstall"},
+		)
+	default:
+		options = append(options,
+			menuOption{label: "Start service", value: "start"},
+			menuOption{label: "Uninstall service", value: "uninstall"},
+		)
+	}
+	options = append(options, menuOption{label: "Exit", value: "exit"})
+	return options
+}
+
+func printDaemonStatusSummary() {
+	manager, err := currentDaemonManager()
+	if err != nil {
+		fmt.Println(cli.StyleStdout(cli.ErrorStyle, "  Error: ") + err.Error())
+		return
+	}
+
+	installed := cli.IsDaemonInstalled()
+	running := cli.IsDaemonRunning()
+
+	fmt.Println(cli.StyleStdout(cli.HeadingStyle, "Daemon status:"))
+
+	status := cli.StyleStdout(cli.WarningStyle, "not installed")
+	if installed {
+		status = cli.StyleStdout(cli.SuccessStyle, "installed")
+	}
+	fmt.Printf("  %-12s %s\n", cli.StyleStdout(cli.MutedStyle, "Service:"), status)
+
+	state := cli.StyleStdout(cli.MutedStyle, "stopped")
+	if running {
+		state = cli.StyleStdout(cli.SuccessStyle, "active (running)")
+	}
+	fmt.Printf("  %-12s %s\n", cli.StyleStdout(cli.MutedStyle, "State:"), state)
+
+	if running {
+		pid, _ := manager.Pid()
+		if pid != "" {
+			fmt.Printf("  %-12s %s\n", cli.StyleStdout(cli.MutedStyle, "PID:"), cli.StyleStdout(cli.ValueStyle, pid))
+		}
+	}
+
+	if installed {
+		fmt.Printf("  %-12s %s\n", cli.StyleStdout(cli.MutedStyle, "Path:"), cli.StyleStdout(cli.ValueStyle, manager.ServicePath()))
+	}
+	if err := manager.Preflight(); err != nil {
+		fmt.Printf("  %-12s %s\n", cli.StyleStdout(cli.MutedStyle, "Environment:"), cli.StyleStdout(cli.WarningStyle, err.Error()))
+	}
+
+	if installed {
+		logs, err := manager.Logs(5)
+		if err == nil && strings.TrimSpace(logs) != "" {
+			fmt.Println()
+			fmt.Println(cli.StyleStdout(cli.HeadingStyle, "Recent logs:"))
+			lines := strings.Split(logs, "\n")
+			for _, line := range lines {
+				if strings.TrimSpace(line) != "" {
+					fmt.Printf("  %s\n", cli.StyleStdout(cli.MutedStyle, line))
+				}
+			}
+		}
+	}
+	fmt.Println()
+}
+
+func printDaemonManagerResult(message string, err error) {
+	if err != nil {
+		fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, err.Error()))
+		os.Exit(1)
+	}
+	if strings.HasPrefix(message, "Installed") || strings.HasPrefix(message, "Pinchtab daemon") {
+		fmt.Println(cli.StyleStdout(cli.SuccessStyle, "  [ok] ") + message)
+	} else {
+		// For status, it might be a block of text
+		fmt.Println(message)
+	}
+}
+
+func ensureDaemonConfig(force bool) (string, *config.FileConfig, configBootstrapStatus, error) {
+	_, configPath, err := config.LoadFileConfig()
+	if err != nil {
+		return "", nil, "", err
+	}
+
+	exists := fileExists(configPath)
+	if !exists || force {
+		defaults := config.DefaultFileConfig()
+		defaults.ConfigVersion = "" // Leave empty so wizard triggers on first install
+		token, err := config.GenerateAuthToken()
+		if err != nil {
+			return "", nil, "", err
+		}
+		defaults.Server.Token = token
+		if err := config.SaveFileConfig(&defaults, configPath); err != nil {
+			return "", nil, "", err
+		}
+		status := configCreated
+		if exists {
+			status = configRecovered
+		}
+		return configPath, &defaults, status, nil
+	}
+
+	// File exists — load it as-is, don't overwrite security settings.
+	// Security recovery is now handled by the wizard or `pinchtab security up`.
+	fileCfg, _, _ := config.LoadFileConfig()
+	if fileCfg == nil {
+		return configPath, nil, "", fmt.Errorf("failed to load existing config at %s", configPath)
+	}
+
+	// Only generate a token if one is missing (security essential)
+	if strings.TrimSpace(fileCfg.Server.Token) == "" {
+		token, err := config.GenerateAuthToken()
+		if err == nil {
+			fileCfg.Server.Token = token
+			_ = config.SaveFileConfig(fileCfg, configPath)
+			return configPath, fileCfg, configRecovered, nil
+		}
+	}
+
+	return configPath, fileCfg, configVerified, nil
+}
+
+type configBootstrapStatus string
+
+const (
+	configCreated   configBootstrapStatus = "created"
+	configRecovered configBootstrapStatus = "recovered"
+	configVerified  configBootstrapStatus = "verified"
+)
+
+type commandRunner interface {
+	CombinedOutput(name string, arg ...string) ([]byte, error)
+}
+
+type osCommandRunner struct{}
+
+func (r osCommandRunner) CombinedOutput(name string, arg ...string) ([]byte, error) {
+	return exec.Command(name, arg...).CombinedOutput() // #nosec G204 -- args are daemon manager controlled, not user input
+}
+
+type daemonEnvironment struct {
+	execPath      string
+	homeDir       string
+	osName        string
+	userID        string
+	xdgConfigHome string
+}
+
+type daemonManager interface {
+	Preflight() error
+	Install(execPath, configPath string) (string, error)
+	ServicePath() string
+	Start() (string, error)
+	Restart() (string, error)
+	Status() (string, error)
+	Stop() (string, error)
+	Uninstall() (string, error)
+	ManualInstructions() string
+	Pid() (string, error)
+	Logs(n int) (string, error)
+}
+
+type systemdUserManager struct {
+	env    daemonEnvironment
+	runner commandRunner
+}
+
+type launchdManager struct {
+	env    daemonEnvironment
+	runner commandRunner
+}
+
+func printDaemonFollowUp() {
+	fmt.Println()
+	fmt.Println(cli.StyleStdout(cli.HeadingStyle, "Follow-up commands:"))
+	fmt.Printf("  %s %s\n", cli.StyleStdout(cli.CommandStyle, "pinchtab daemon"), cli.StyleStdout(cli.MutedStyle, "# Check service health and logs"))
+	fmt.Printf("  %s %s\n", cli.StyleStdout(cli.CommandStyle, "pinchtab daemon restart"), cli.StyleStdout(cli.MutedStyle, "# Apply config changes"))
+	fmt.Printf("  %s %s\n", cli.StyleStdout(cli.CommandStyle, "pinchtab daemon stop"), cli.StyleStdout(cli.MutedStyle, "# Stop background service"))
+	fmt.Printf("  %s %s\n", cli.StyleStdout(cli.CommandStyle, "pinchtab daemon uninstall"), cli.StyleStdout(cli.MutedStyle, "# Remove service file"))
+}
+
+func currentDaemonManager() (daemonManager, error) {
+	env, err := currentDaemonEnvironment()
+	if err != nil {
+		return nil, err
+	}
+	return newDaemonManager(env, osCommandRunner{})
+}
+
+func currentDaemonEnvironment() (daemonEnvironment, error) {
+	execPath, err := os.Executable()
+	if err != nil {
+		return daemonEnvironment{}, fmt.Errorf("resolve executable path: %w", err)
+	}
+	homeDir, err := os.UserHomeDir()
+	if err != nil {
+		return daemonEnvironment{}, fmt.Errorf("resolve home directory: %w", err)
+	}
+	currentUser, err := user.Current()
+	if err != nil {
+		return daemonEnvironment{}, fmt.Errorf("resolve current user: %w", err)
+	}
+
+	return daemonEnvironment{
+		execPath:      execPath,
+		homeDir:       homeDir,
+		osName:        runtime.GOOS,
+		userID:        currentUser.Uid,
+		xdgConfigHome: os.Getenv("XDG_CONFIG_HOME"),
+	}, nil
+}
+
+func newDaemonManager(env daemonEnvironment, runner commandRunner) (daemonManager, error) {
+	switch env.osName {
+	case "linux":
+		return &systemdUserManager{env: env, runner: runner}, nil
+	case "darwin":
+		return &launchdManager{env: env, runner: runner}, nil
+	default:
+		return nil, fmt.Errorf("pinchtab daemon is supported on macOS and Linux; current OS is %s", env.osName)
+	}
+}
+
+func managerEnvironment(manager daemonManager) daemonEnvironment {
+	switch m := manager.(type) {
+	case *systemdUserManager:
+		return m.env
+	case *launchdManager:
+		return m.env
+	default:
+		return daemonEnvironment{}
+	}
+}
+
+func (m *systemdUserManager) ServicePath() string {
+	return filepath.Join(systemdUserConfigHome(m.env), "systemd", "user", pinchtabDaemonUnitName)
+}
+
+func (m *systemdUserManager) Preflight() error {
+	if _, err := runCommand(m.runner, "systemctl", "--user", "show-environment"); err != nil {
+		return fmt.Errorf("linux daemon install requires a working user systemd session (`systemctl --user`): %w", err)
+	}
+	return nil
+}
+
+func (m *systemdUserManager) Install(execPath, configPath string) (string, error) {
+	if err := os.MkdirAll(filepath.Dir(m.ServicePath()), 0755); err != nil {
+		return "", fmt.Errorf("create systemd user directory: %w", err)
+	}
+	if err := os.WriteFile(m.ServicePath(), []byte(renderSystemdUnit(execPath, configPath)), 0644); err != nil {
+		return "", fmt.Errorf("write systemd unit: %w", err)
+	}
+	if _, err := runCommand(m.runner, "systemctl", "--user", "daemon-reload"); err != nil {
+		return "", err
+	}
+	if _, err := runCommand(m.runner, "systemctl", "--user", "enable", "--now", pinchtabDaemonUnitName); err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("Installed systemd user service at %s", m.ServicePath()), nil
+}
+
+func (m *systemdUserManager) Start() (string, error) {
+	if _, err := runCommand(m.runner, "systemctl", "--user", "start", pinchtabDaemonUnitName); err != nil {
+		return "", err
+	}
+	return "Pinchtab daemon started.", nil
+}
+
+func (m *systemdUserManager) Restart() (string, error) {
+	if _, err := runCommand(m.runner, "systemctl", "--user", "restart", pinchtabDaemonUnitName); err != nil {
+		return "", err
+	}
+	return "Pinchtab daemon restarted.", nil
+}
+
+func (m *systemdUserManager) Stop() (string, error) {
+	if _, err := runCommand(m.runner, "systemctl", "--user", "stop", pinchtabDaemonUnitName); err != nil {
+		return "", err
+	}
+	return "Pinchtab daemon stopped.", nil
+}
+
+func (m *systemdUserManager) Status() (string, error) {
+	output, err := runCommand(m.runner, "systemctl", "--user", "status", pinchtabDaemonUnitName, "--no-pager")
+	if err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(output) == "" {
+		return "Pinchtab daemon status returned no output.", nil
+	}
+	return output, nil
+}
+
+func (m *systemdUserManager) Uninstall() (string, error) {
+	var errs []error
+	if _, err := runCommand(m.runner, "systemctl", "--user", "disable", "--now", pinchtabDaemonUnitName); err != nil {
+		errs = append(errs, err)
+	}
+	if err := os.Remove(m.ServicePath()); err != nil && !errors.Is(err, os.ErrNotExist) {
+		errs = append(errs, fmt.Errorf("remove unit file: %w", err))
+	}
+	if _, err := runCommand(m.runner, "systemctl", "--user", "daemon-reload"); err != nil {
+		errs = append(errs, err)
+	}
+	if len(errs) > 0 {
+		return "", errors.Join(errs...)
+	}
+	return "Pinchtab daemon uninstalled.", nil
+}
+
+func (m *systemdUserManager) Pid() (string, error) {
+	output, err := runCommand(m.runner, "systemctl", "--user", "show", pinchtabDaemonUnitName, "--property", "MainPID")
+	if err != nil {
+		return "", err
+	}
+	// Output is typically MainPID=1234
+	if parts := strings.Split(output, "="); len(parts) == 2 {
+		pid := strings.TrimSpace(parts[1])
+		if pid == "0" {
+			return "", nil // Not running
+		}
+		return pid, nil
+	}
+	return "", nil
+}
+
+func (m *systemdUserManager) Logs(n int) (string, error) {
+	return runCommand(m.runner, "journalctl", "--user", "-u", pinchtabDaemonUnitName, "-n", fmt.Sprintf("%d", n), "--no-pager")
+}
+
+func (m *systemdUserManager) ManualInstructions() string {
+	path := m.ServicePath()
+	var b strings.Builder
+	fmt.Fprintln(&b, cli.StyleStdout(cli.HeadingStyle, "Manual instructions (Linux/systemd):"))
+	fmt.Fprintln(&b, cli.StyleStdout(cli.MutedStyle, "To install manually:"))
+	fmt.Fprintf(&b, "  1. Create %s\n", cli.StyleStdout(cli.ValueStyle, path))
+	fmt.Fprintln(&b, "  2. Run: "+cli.StyleStdout(cli.CommandStyle, "systemctl --user daemon-reload"))
+	fmt.Fprintln(&b, "  3. Run: "+cli.StyleStdout(cli.CommandStyle, "systemctl --user enable --now pinchtab.service"))
+	fmt.Fprintln(&b)
+	fmt.Fprintln(&b, cli.StyleStdout(cli.MutedStyle, "To uninstall manually:"))
+	fmt.Fprintln(&b, "  1. Run: "+cli.StyleStdout(cli.CommandStyle, "systemctl --user disable --now pinchtab.service"))
+	fmt.Fprintf(&b, "  2. Remove: %s\n", cli.StyleStdout(cli.ValueStyle, path))
+	fmt.Fprintln(&b, "  3. Run: "+cli.StyleStdout(cli.CommandStyle, "systemctl --user daemon-reload"))
+	return b.String()
+}
+
+func renderSystemdUnit(execPath, configPath string) string {
+	return fmt.Sprintf(`[Unit]
+Description=Pinchtab Browser Service
+After=network.target
+
+[Service]
+Type=simple
+ExecStart="%s" server
+Environment="PINCHTAB_CONFIG=%s"
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`, execPath, configPath)
+}
+
+func (m *launchdManager) ServicePath() string {
+	return filepath.Join(m.env.homeDir, "Library", "LaunchAgents", pinchtabLaunchdLabel+".plist")
+}
+
+func (m *launchdManager) Preflight() error {
+	if strings.TrimSpace(m.env.userID) == "" {
+		return fmt.Errorf("macOS daemon install requires a logged-in user session with a launchd GUI domain")
+	}
+	if _, err := runCommand(m.runner, "launchctl", "print", launchdDomainTarget(m.env)); err != nil {
+		return fmt.Errorf("macOS daemon install requires an active launchd GUI session: %w", err)
+	}
+	return nil
+}
+
+func (m *launchdManager) Install(execPath, configPath string) (string, error) {
+	if err := os.MkdirAll(filepath.Dir(m.ServicePath()), 0755); err != nil {
+		return "", fmt.Errorf("create LaunchAgents directory: %w", err)
+	}
+	if err := os.WriteFile(m.ServicePath(), []byte(renderLaunchdPlist(execPath, configPath)), 0644); err != nil {
+		return "", fmt.Errorf("write launchd plist: %w", err)
+	}
+	_, _ = runCommand(m.runner, "launchctl", "bootout", launchdDomainTarget(m.env), m.ServicePath())
+	if _, err := runCommand(m.runner, "launchctl", "bootstrap", launchdDomainTarget(m.env), m.ServicePath()); err != nil {
+		return "", err
+	}
+	if _, err := runCommand(m.runner, "launchctl", "kickstart", "-k", launchdDomainTarget(m.env)+"/"+pinchtabLaunchdLabel); err != nil {
+		return "", err
+	}
+	return fmt.Sprintf("Installed launchd agent at %s", m.ServicePath()), nil
+}
+
+func (m *launchdManager) Start() (string, error) {
+	if _, err := runCommand(m.runner, "launchctl", "bootstrap", launchdDomainTarget(m.env), m.ServicePath()); err != nil && !strings.Contains(err.Error(), "already bootstrapped") {
+		return "", err
+	}
+	if _, err := runCommand(m.runner, "launchctl", "kickstart", launchdDomainTarget(m.env)+"/"+pinchtabLaunchdLabel); err != nil {
+		return "", err
+	}
+	return "Pinchtab daemon started.", nil
+}
+
+func (m *launchdManager) Restart() (string, error) {
+	if _, err := runCommand(m.runner, "launchctl", "kickstart", "-k", launchdDomainTarget(m.env)+"/"+pinchtabLaunchdLabel); err != nil {
+		return "", err
+	}
+	return "Pinchtab daemon restarted.", nil
+}
+
+func (m *launchdManager) Stop() (string, error) {
+	_, err := runCommand(m.runner, "launchctl", "bootout", launchdDomainTarget(m.env), m.ServicePath())
+	if err != nil && !isLaunchdIgnorableError(err) {
+		return "", err
+	}
+	return "Pinchtab daemon stopped.", nil
+}
+
+func (m *launchdManager) Status() (string, error) {
+	output, err := runCommand(m.runner, "launchctl", "print", launchdDomainTarget(m.env)+"/"+pinchtabLaunchdLabel)
+	if err != nil {
+		return "", err
+	}
+	if strings.TrimSpace(output) == "" {
+		return "Pinchtab daemon status returned no output.", nil
+	}
+	return output, nil
+}
+
+func (m *launchdManager) Uninstall() (string, error) {
+	var errs []error
+	_, err := runCommand(m.runner, "launchctl", "bootout", launchdDomainTarget(m.env), m.ServicePath())
+	if err != nil && !isLaunchdIgnorableError(err) {
+		errs = append(errs, err)
+	}
+	if err := os.Remove(m.ServicePath()); err != nil && !errors.Is(err, os.ErrNotExist) {
+		errs = append(errs, fmt.Errorf("remove launchd plist: %w", err))
+	}
+	if len(errs) > 0 {
+		return "", errors.Join(errs...)
+	}
+	return "Pinchtab daemon uninstalled.", nil
+}
+
+func (m *launchdManager) Pid() (string, error) {
+	output, err := runCommand(m.runner, "launchctl", "print", launchdDomainTarget(m.env)+"/"+pinchtabLaunchdLabel)
+	if err != nil {
+		return "", err
+	}
+	// Try to find pid = 1234
+	lines := strings.Split(output, "\n")
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "pid = ") {
+			return strings.TrimPrefix(trimmed, "pid = "), nil
+		}
+	}
+	return "", nil
+}
+
+func (m *launchdManager) Logs(n int) (string, error) {
+	// macOS log paths we added to plist
+	logPath := "/tmp/pinchtab.err.log"
+	if _, err := os.Stat(logPath); err != nil {
+		return "No logs found at " + logPath, nil
+	}
+	return runCommand(m.runner, "tail", "-n", fmt.Sprintf("%d", n), logPath)
+}
+
+func (m *launchdManager) ManualInstructions() string {
+	path := m.ServicePath()
+	target := launchdDomainTarget(m.env)
+	var b strings.Builder
+	fmt.Fprintln(&b, cli.StyleStdout(cli.HeadingStyle, "Manual instructions (macOS/launchd):"))
+	fmt.Fprintln(&b, cli.StyleStdout(cli.MutedStyle, "To install manually:"))
+	fmt.Fprintf(&b, "  1. Create %s\n", cli.StyleStdout(cli.ValueStyle, path))
+	fmt.Fprintln(&b, "  2. Run: "+cli.StyleStdout(cli.CommandStyle, fmt.Sprintf("launchctl bootstrap %s %s", target, path)))
+	fmt.Fprintln(&b)
+	fmt.Fprintln(&b, cli.StyleStdout(cli.MutedStyle, "To uninstall manually:"))
+	fmt.Fprintln(&b, "  1. Run: "+cli.StyleStdout(cli.CommandStyle, fmt.Sprintf("launchctl bootout %s %s", target, path)))
+	fmt.Fprintf(&b, "  2. Remove: %s\n", cli.StyleStdout(cli.ValueStyle, path))
+	return b.String()
+}
+
+func isLaunchdIgnorableError(err error) bool {
+	if err == nil {
+		return true
+	}
+	msg := err.Error()
+	// Exit status 5 often means already booted out or path not found in domain
+	// "No such process" (status 3) or "No such file or directory" (status 2) or "Operation not permitted" (sometimes)
+	return strings.Contains(msg, "exit status 5") ||
+		strings.Contains(msg, "No such process") ||
+		strings.Contains(msg, "not found") ||
+		strings.Contains(msg, "already bootstrapped")
+}
+
+func renderLaunchdPlist(execPath, configPath string) string {
+	return fmt.Sprintf(`<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>%s</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>%s</string>
+    <string>server</string>
+  </array>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <true/>
+  <key>ExitTimeOut</key>
+  <integer>10</integer>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PINCHTAB_CONFIG</key>
+    <string>%s</string>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/tmp/pinchtab.out.log</string>
+  <key>StandardErrorPath</key>
+  <string>/tmp/pinchtab.err.log</string>
+</dict>
+</plist>
+`, pinchtabLaunchdLabel, execPath, configPath)
+}
+
+func runCommand(runner commandRunner, name string, args ...string) (string, error) {
+	output, err := runner.CombinedOutput(name, args...)
+	trimmed := strings.TrimSpace(string(output))
+	if err == nil {
+		return trimmed, nil
+	}
+	if trimmed == "" {
+		return "", fmt.Errorf("%s %s: %w", name, strings.Join(args, " "), err)
+	}
+	return "", fmt.Errorf("%s %s: %w: %s", name, strings.Join(args, " "), err, trimmed)
+}
+
+func launchdDomainTarget(env daemonEnvironment) string {
+	return "gui/" + env.userID
+}
+
+func systemdUserConfigHome(env daemonEnvironment) string {
+	if strings.TrimSpace(env.xdgConfigHome) != "" {
+		return env.xdgConfigHome
+	}
+	return filepath.Join(env.homeDir, ".config")
+}
+
+func fileExists(path string) bool {
+	_, err := os.Stat(path)
+	return err == nil
+}
+
+func isInteractiveTerminal() bool {
+	in, err := os.Stdin.Stat()
+	if err != nil || (in.Mode()&os.ModeCharDevice) == 0 {
+		return false
+	}
+	out, err := os.Stdout.Stat()
+	if err != nil || (out.Mode()&os.ModeCharDevice) == 0 {
+		return false
+	}
+	return true
+}

cmd/pinchtab/cmd_daemon_test.go

@@ -0,0 +1,288 @@
+package main
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+type fakeCommandRunner struct {
+	calls   []string
+	outputs map[string]string
+	errors  map[string]error
+}
+
+func (f *fakeCommandRunner) CombinedOutput(name string, args ...string) ([]byte, error) {
+	call := name + " " + strings.Join(args, " ")
+	f.calls = append(f.calls, call)
+	if out, ok := f.outputs[call]; ok {
+		return []byte(out), f.errors[call]
+	}
+	return nil, f.errors[call]
+}
+
+func TestEnsureOnboardConfigCreatesDefaultConfig(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "pinchtab", "config.json")
+	t.Setenv("PINCHTAB_CONFIG", configPath)
+	t.Setenv("PINCHTAB_TOKEN", "")
+	t.Setenv("PINCHTAB_BIND", "")
+
+	gotPath, cfg, status, err := ensureDaemonConfig(false)
+	if err != nil {
+		t.Fatalf("ensureDaemonConfig returned error: %v", err)
+	}
+	if status != configCreated {
+		t.Fatalf("status = %q, want %q", status, configCreated)
+	}
+	if gotPath != configPath {
+		t.Fatalf("config path = %q, want %q", gotPath, configPath)
+	}
+	if cfg.Server.Bind != "127.0.0.1" {
+		t.Fatalf("bind = %q, want 127.0.0.1", cfg.Server.Bind)
+	}
+	if strings.TrimSpace(cfg.Server.Token) == "" {
+		t.Fatal("expected generated token to be set")
+	}
+	data, err := os.ReadFile(configPath)
+	if err != nil {
+		t.Fatalf("reading config file: %v", err)
+	}
+	content := string(data)
+	if !strings.Contains(content, `"bind": "127.0.0.1"`) {
+		t.Fatalf("expected config file to include bind, got %s", content)
+	}
+	if !strings.Contains(content, `"token": "`) {
+		t.Fatalf("expected config file to include token, got %s", content)
+	}
+}
+
+func TestEnsureOnboardConfigRecoversExistingSecuritySettings(t *testing.T) {
+	configPath := filepath.Join(t.TempDir(), "pinchtab", "config.json")
+	t.Setenv("PINCHTAB_CONFIG", configPath)
+	input := `{
+  "server": {
+    "bind": "0.0.0.0",
+    "port": "9999",
+    "token": ""
+  },
+  "browser": {
+    "binary": "/custom/chrome"
+  },
+  "security": {
+    "allowEvaluate": true
+  }
+}
+`
+	if err := os.MkdirAll(filepath.Dir(configPath), 0755); err != nil {
+		t.Fatalf("creating config dir: %v", err)
+	}
+	if err := os.WriteFile(configPath, []byte(input), 0644); err != nil {
+		t.Fatalf("writing config file: %v", err)
+	}
+
+	_, cfg, status, err := ensureDaemonConfig(false)
+	if err != nil {
+		t.Fatalf("ensureDaemonConfig returned error: %v", err)
+	}
+	// Only token recovery happens now — security settings are preserved for wizard
+	if status != configRecovered {
+		t.Fatalf("status = %q, want %q", status, configRecovered)
+	}
+	// Bind is preserved as-is (wizard handles security changes, not daemon config)
+	if cfg.Server.Bind != "0.0.0.0" {
+		t.Fatalf("bind = %q, want 0.0.0.0 (preserved)", cfg.Server.Bind)
+	}
+	if cfg.Server.Port != "9999" {
+		t.Fatalf("port = %q, want 9999", cfg.Server.Port)
+	}
+	if cfg.Browser.ChromeBinary != "/custom/chrome" {
+		t.Fatalf("chrome binary = %q, want /custom/chrome", cfg.Browser.ChromeBinary)
+	}
+	// Security settings preserved — not overwritten
+	if !boolPtrValue(cfg.Security.AllowEvaluate) {
+		t.Fatal("expected allowEvaluate to be preserved as true")
+	}
+	// Token should be generated (was empty)
+	if strings.TrimSpace(cfg.Server.Token) == "" {
+		t.Fatal("expected recovery to generate a token")
+	}
+}
+
+func TestSystemdUserManagerInstallWritesUnitAndEnablesService(t *testing.T) {
+	root := t.TempDir()
+	runner := &fakeCommandRunner{}
+	manager := &systemdUserManager{
+		env: daemonEnvironment{
+			homeDir:       root,
+			osName:        "linux",
+			execPath:      "/usr/local/bin/pinchtab",
+			xdgConfigHome: filepath.Join(root, ".config"),
+		},
+		runner: runner,
+	}
+
+	message, err := manager.Install("/usr/local/bin/pinchtab", "/tmp/pinchtab/config.json")
+	if err != nil {
+		t.Fatalf("Install returned error: %v", err)
+	}
+	if !strings.Contains(message, manager.ServicePath()) {
+		t.Fatalf("install message = %q, want path %q", message, manager.ServicePath())
+	}
+
+	data, err := os.ReadFile(manager.ServicePath())
+	if err != nil {
+		t.Fatalf("reading service file: %v", err)
+	}
+	content := string(data)
+	if !strings.Contains(content, `ExecStart="/usr/local/bin/pinchtab" server`) {
+		t.Fatalf("unexpected unit content: %s", content)
+	}
+	if !strings.Contains(content, `Environment="PINCHTAB_CONFIG=/tmp/pinchtab/config.json"`) {
+		t.Fatalf("expected config env in unit content: %s", content)
+	}
+
+	expectedCalls := []string{
+		"systemctl --user daemon-reload",
+		"systemctl --user enable --now pinchtab.service",
+	}
+	if strings.Join(runner.calls, "\n") != strings.Join(expectedCalls, "\n") {
+		t.Fatalf("systemd calls = %v, want %v", runner.calls, expectedCalls)
+	}
+}
+
+func TestLaunchdManagerInstallWritesPlistAndBootstrapsAgent(t *testing.T) {
+	root := t.TempDir()
+	runner := &fakeCommandRunner{}
+	manager := &launchdManager{
+		env: daemonEnvironment{
+			homeDir:  root,
+			osName:   "darwin",
+			execPath: "/Applications/Pinchtab.app/Contents/MacOS/pinchtab",
+			userID:   "501",
+		},
+		runner: runner,
+	}
+
+	message, err := manager.Install("/Applications/Pinchtab.app/Contents/MacOS/pinchtab", "/tmp/pinchtab/config.json")
+	if err != nil {
+		t.Fatalf("Install returned error: %v", err)
+	}
+	if !strings.Contains(message, manager.ServicePath()) {
+		t.Fatalf("install message = %q, want path %q", message, manager.ServicePath())
+	}
+
+	data, err := os.ReadFile(manager.ServicePath())
+	if err != nil {
+		t.Fatalf("reading launchd plist: %v", err)
+	}
+	content := string(data)
+	if !strings.Contains(content, "<string>com.pinchtab.pinchtab</string>") {
+		t.Fatalf("expected launchd label in plist: %s", content)
+	}
+	if !strings.Contains(content, "<string>/Applications/Pinchtab.app/Contents/MacOS/pinchtab</string>") {
+		t.Fatalf("expected executable path in plist: %s", content)
+	}
+	if !strings.Contains(content, "<string>/tmp/pinchtab/config.json</string>") {
+		t.Fatalf("expected config path in plist: %s", content)
+	}
+
+	expectedCalls := []string{
+		"launchctl bootout gui/501 " + manager.ServicePath(),
+		"launchctl bootstrap gui/501 " + manager.ServicePath(),
+		"launchctl kickstart -k gui/501/com.pinchtab.pinchtab",
+	}
+	if strings.Join(runner.calls, "\n") != strings.Join(expectedCalls, "\n") {
+		t.Fatalf("launchctl calls = %v, want %v", runner.calls, expectedCalls)
+	}
+}
+
+func TestSystemdUserManagerPreflightRequiresUserSession(t *testing.T) {
+	runner := &fakeCommandRunner{
+		errors: map[string]error{
+			"systemctl --user show-environment": errors.New("exit status 1"),
+		},
+	}
+	manager := &systemdUserManager{
+		env:    daemonEnvironment{osName: "linux"},
+		runner: runner,
+	}
+
+	err := manager.Preflight()
+	if err == nil {
+		t.Fatal("expected preflight error")
+	}
+	if !strings.Contains(err.Error(), "working user systemd session") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestLaunchdManagerPreflightRequiresGUIDomain(t *testing.T) {
+	runner := &fakeCommandRunner{
+		errors: map[string]error{
+			"launchctl print gui/501": errors.New("exit status 113"),
+		},
+	}
+	manager := &launchdManager{
+		env:    daemonEnvironment{osName: "darwin", userID: "501"},
+		runner: runner,
+	}
+
+	err := manager.Preflight()
+	if err == nil {
+		t.Fatal("expected preflight error")
+	}
+	if !strings.Contains(err.Error(), "active launchd GUI session") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestNewDaemonManagerRejectsUnsupportedOS(t *testing.T) {
+	_, err := newDaemonManager(daemonEnvironment{osName: "windows"}, &fakeCommandRunner{})
+	if err == nil {
+		t.Fatal("expected unsupported OS error")
+	}
+}
+
+func TestDaemonMenuOptions(t *testing.T) {
+	tests := []struct {
+		name      string
+		installed bool
+		running   bool
+		want      []string
+	}{
+		{
+			name:      "not installed",
+			installed: false,
+			running:   false,
+			want:      []string{"install", "exit"},
+		},
+		{
+			name:      "installed stopped",
+			installed: true,
+			running:   false,
+			want:      []string{"start", "uninstall", "exit"},
+		},
+		{
+			name:      "installed running",
+			installed: true,
+			running:   true,
+			want:      []string{"stop", "restart", "uninstall", "exit"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := daemonMenuOptions(tt.installed, tt.running)
+			if len(got) != len(tt.want) {
+				t.Fatalf("len(daemonMenuOptions()) = %d, want %d", len(got), len(tt.want))
+			}
+			for i, want := range tt.want {
+				if got[i].value != want {
+					t.Fatalf("daemonMenuOptions()[%d] = %q, want %q", i, got[i].value, want)
+				}
+			}
+		})
+	}
+}

cmd/pinchtab/cmd_mcp.go

@@ -0,0 +1,53 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/pinchtab/pinchtab/internal/config"
+	"github.com/pinchtab/pinchtab/internal/mcp"
+	"github.com/spf13/cobra"
+)
+
+var mcpCmd = &cobra.Command{
+	Use:   "mcp",
+	Short: "Start the MCP stdio server",
+	Long:  "Start the Model Context Protocol stdio server and proxy browser actions to a running PinchTab instance.",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := config.Load()
+		runMCP(cfg)
+	},
+}
+
+func init() {
+	mcpCmd.GroupID = "primary"
+	rootCmd.AddCommand(mcpCmd)
+}
+
+func runMCP(cfg *config.RuntimeConfig) {
+	// Default: http://127.0.0.1:{port}
+	port := cfg.Port
+	if port == "" {
+		port = "9867"
+	}
+	baseURL := "http://127.0.0.1:" + port
+
+	// --server flag overrides
+	if serverURL != "" {
+		baseURL = strings.TrimRight(serverURL, "/")
+	}
+
+	// Token from config, env var overrides
+	token := cfg.Token
+	if envToken := os.Getenv("PINCHTAB_TOKEN"); envToken != "" {
+		token = envToken
+	}
+
+	mcp.Version = version
+
+	if err := mcp.Serve(baseURL, token); err != nil {
+		fmt.Fprintf(os.Stderr, "mcp server error: %v\n", err)
+		os.Exit(1)
+	}
+}

cmd/pinchtab/cmd_security.go

@@ -0,0 +1,474 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"slices"
+	"strings"
+
+	"github.com/pinchtab/pinchtab/internal/cli"
+	"github.com/pinchtab/pinchtab/internal/config"
+	"github.com/spf13/cobra"
+)
+
+var securityCmd = &cobra.Command{
+	Use:   "security",
+	Short: "Review runtime security posture",
+	Long:  "Shows runtime security posture and offers to restore recommended security defaults.",
+	Run: func(cmd *cobra.Command, args []string) {
+		cfg := loadConfig()
+		handleSecurityCommand(cfg)
+	},
+}
+
+func init() {
+	securityCmd.GroupID = "config"
+	securityCmd.AddCommand(&cobra.Command{
+		Use:   "up",
+		Short: "Apply recommended security defaults",
+		Run: func(cmd *cobra.Command, args []string) {
+			handleSecurityUpCommand()
+		},
+	})
+	securityCmd.AddCommand(&cobra.Command{
+		Use:   "down",
+		Short: "Lower guards while keeping loopback bind and API auth enabled",
+		Run: func(cmd *cobra.Command, args []string) {
+			handleSecurityDownCommand()
+		},
+	})
+	rootCmd.AddCommand(securityCmd)
+}
+
+func handleSecurityCommand(cfg *config.RuntimeConfig) {
+	interactive := isInteractiveTerminal()
+
+	for {
+		posture := cli.AssessSecurityPosture(cfg)
+		warnings := cli.AssessSecurityWarnings(cfg)
+		recommended := cli.RecommendedSecurityDefaultLines(cfg)
+
+		printSecuritySummary(posture, interactive)
+
+		if len(warnings) > 0 {
+			fmt.Println()
+			fmt.Println(cli.StyleStdout(cli.HeadingStyle, "Warnings"))
+			fmt.Println()
+			for _, warning := range warnings {
+				fmt.Printf("  - %s\n", cli.StyleStdout(cli.WarningStyle, warning.Message))
+				for i := 0; i+1 < len(warning.Attrs); i += 2 {
+					key, ok := warning.Attrs[i].(string)
+					if !ok || key == "hint" {
+						continue
+					}
+					fmt.Printf("      %s: %s\n", cli.StyleStdout(cli.MutedStyle, key), cli.StyleStdout(cli.ValueStyle, formatSecurityValue(warning.Attrs[i+1])))
+				}
+				for i := 0; i+1 < len(warning.Attrs); i += 2 {
+					key, ok := warning.Attrs[i].(string)
+					if ok && key == "hint" {
+						fmt.Printf("      %s: %s\n", cli.StyleStdout(cli.MutedStyle, "hint"), cli.StyleStdout(cli.ValueStyle, formatSecurityValue(warning.Attrs[i+1])))
+					}
+				}
+			}
+		}
+
+		if len(recommended) == 0 && len(warnings) == 0 {
+			fmt.Println()
+			fmt.Println("  " + cli.StyleStdout(cli.SuccessStyle, "All recommended security defaults are active."))
+		} else if len(recommended) > 0 {
+			fmt.Println()
+			fmt.Println(cli.StyleStdout(cli.HeadingStyle, "Recommended defaults"))
+			fmt.Println()
+			printRecommendedSecurityDefaults(recommended)
+		}
+
+		if !interactive {
+			if len(recommended) > 0 {
+				fmt.Println()
+				fmt.Println(cli.StyleStdout(cli.MutedStyle, "Interactive editing skipped because stdin/stdout is not a terminal."))
+			}
+			return
+		}
+
+		nextCfg, changed, done, err := promptSecurityEdit(cfg, posture, len(recommended) > 0)
+		if err != nil {
+			fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, err.Error()))
+			os.Exit(1)
+		}
+		if done {
+			return
+		}
+		if !changed {
+			fmt.Println()
+			fmt.Println(cli.StyleStdout(cli.MutedStyle, "No changes made."))
+			return
+		}
+		cfg = nextCfg
+		fmt.Println()
+	}
+}
+
+func formatSecurityValue(value any) string {
+	switch v := value.(type) {
+	case []string:
+		return strings.Join(v, ", ")
+	default:
+		return fmt.Sprint(v)
+	}
+}
+
+func printRecommendedSecurityDefaults(lines []string) {
+	for _, line := range lines {
+		fmt.Printf("  - %s\n", cli.StyleStdout(cli.ValueStyle, line))
+	}
+}
+
+func printSecuritySummary(posture cli.SecurityPosture, interactive bool) {
+	fmt.Println(cli.StyleStdout(cli.HeadingStyle, "Security"))
+	fmt.Println()
+	fmt.Printf("  %s  %s\n", posture.Bar, cli.StyleStdout(cli.ValueStyle, posture.Level))
+	for i, check := range posture.Checks {
+		indicator := cli.StyleStdout(cli.WarningStyle, "!!")
+		if check.Passed {
+			indicator = cli.StyleStdout(cli.SuccessStyle, "ok")
+		}
+		if interactive {
+			fmt.Printf("  %d. %s %-20s %s\n", i+1, indicator, check.Label, check.Detail)
+			continue
+		}
+		fmt.Printf("    %s %-20s %s\n", indicator, check.Label, check.Detail)
+	}
+}
+
+func promptSecurityEdit(cfg *config.RuntimeConfig, posture cli.SecurityPosture, canRestoreDefaults bool) (*config.RuntimeConfig, bool, bool, error) {
+	fmt.Println()
+	prompt := "Edit item (1-8"
+	if canRestoreDefaults {
+		prompt += ", u = security up"
+	}
+	prompt += ", d = security down, blank to exit):"
+
+	choice, err := promptInput(cli.StyleStdout(cli.HeadingStyle, prompt), "")
+	if err != nil {
+		return nil, false, false, err
+	}
+	choice = strings.ToLower(strings.TrimSpace(choice))
+	if choice == "" {
+		return nil, false, true, nil
+	}
+
+	if (choice == "u" || choice == "up") && canRestoreDefaults {
+		nextCfg, changed, err := applySecurityUp()
+		return nextCfg, changed, false, err
+	}
+
+	if choice == "d" || choice == "down" {
+		nextCfg, changed, err := applySecurityDown()
+		return nextCfg, changed, false, err
+	}
+
+	index := strings.TrimSpace(choice)
+	for i, check := range posture.Checks {
+		if index == fmt.Sprint(i+1) {
+			nextCfg, changed, err := editSecurityCheck(cfg, check)
+			return nextCfg, changed, false, err
+		}
+	}
+
+	return nil, false, false, fmt.Errorf("invalid selection %q", choice)
+}
+
+func editSecurityCheck(cfg *config.RuntimeConfig, check cli.SecurityPostureCheck) (*config.RuntimeConfig, bool, error) {
+	switch check.ID {
+	case "bind_loopback":
+		value, err := promptInput("Set server.bind:", cfg.Bind)
+		if err != nil {
+			return nil, false, err
+		}
+		return updateConfigValue("server.bind", value)
+	case "api_auth_enabled":
+		picked, err := promptSelect("API authentication", []menuOption{
+			{label: "Generate new token (Recommended)", value: "generate"},
+			{label: "Set custom token", value: "custom"},
+			{label: "Disable token", value: "disable"},
+			{label: "Cancel", value: "cancel"},
+		})
+		if err != nil || picked == "" || picked == "cancel" {
+			return cfg, false, nil
+		}
+		switch picked {
+		case "generate":
+			token, err := config.GenerateAuthToken()
+			if err != nil {
+				return nil, false, err
+			}
+			return updateConfigValue("server.token", token)
+		case "custom":
+			token, err := promptInput("Set server.token:", cfg.Token)
+			if err != nil {
+				return nil, false, err
+			}
+			return updateConfigValue("server.token", token)
+		case "disable":
+			return updateConfigValue("server.token", "")
+		}
+	case "sensitive_endpoints_disabled":
+		current := strings.Join(cfg.EnabledSensitiveEndpoints(), ",")
+		value, err := promptInput("Enable sensitive endpoints (evaluate,macro,screencast,download,upload; blank = disable all):", current)
+		if err != nil {
+			return nil, false, err
+		}
+		return updateSensitiveEndpoints(value)
+	case "attach_disabled":
+		picked, err := promptSelect("Attach endpoint", []menuOption{
+			{label: "Disable (Recommended)", value: "disable"},
+			{label: "Enable", value: "enable"},
+			{label: "Cancel", value: "cancel"},
+		})
+		if err != nil || picked == "" || picked == "cancel" {
+			return cfg, false, nil
+		}
+		return updateConfigValue("security.attach.enabled", fmt.Sprintf("%t", picked == "enable"))
+	case "attach_local_only":
+		value, err := promptInput("Set security.attach.allowHosts (comma-separated):", strings.Join(cfg.AttachAllowHosts, ","))
+		if err != nil {
+			return nil, false, err
+		}
+		return updateConfigValue("security.attach.allowHosts", value)
+	case "idpi_whitelist_scoped":
+		value, err := promptInput("Set security.idpi.allowedDomains (comma-separated):", strings.Join(cfg.IDPI.AllowedDomains, ","))
+		if err != nil {
+			return nil, false, err
+		}
+		return updateConfigValue("security.idpi.allowedDomains", value)
+	case "idpi_strict_mode":
+		picked, err := promptSelect("IDPI strict mode", []menuOption{
+			{label: "Enforce (Recommended)", value: "true"},
+			{label: "Warn only", value: "false"},
+			{label: "Cancel", value: "cancel"},
+		})
+		if err != nil || picked == "" || picked == "cancel" {
+			return cfg, false, nil
+		}
+		return updateConfigValue("security.idpi.strictMode", picked)
+	case "idpi_content_protection":
+		picked, err := promptSelect("IDPI content guard", []menuOption{
+			{label: "Active: scan + wrap (Recommended)", value: "both"},
+			{label: "Scan only", value: "scan"},
+			{label: "Wrap only", value: "wrap"},
+			{label: "Disable", value: "off"},
+			{label: "Cancel", value: "cancel"},
+		})
+		if err != nil || picked == "" || picked == "cancel" {
+			return cfg, false, nil
+		}
+		return updateContentGuard(picked)
+	}
+	return cfg, false, nil
+}
+
+func updateConfigValue(path, value string) (*config.RuntimeConfig, bool, error) {
+	fc, configPath, err := config.LoadFileConfig()
+	if err != nil {
+		return nil, false, fmt.Errorf("load config: %w", err)
+	}
+	if err := config.SetConfigValue(fc, path, value); err != nil {
+		return nil, false, fmt.Errorf("set %s: %w", path, err)
+	}
+	if errs := config.ValidateFileConfig(fc); len(errs) > 0 {
+		return nil, false, errs[0]
+	}
+	if err := config.SaveFileConfig(fc, configPath); err != nil {
+		return nil, false, fmt.Errorf("save config: %w", err)
+	}
+	return config.Load(), true, nil
+}
+
+func updateSensitiveEndpoints(value string) (*config.RuntimeConfig, bool, error) {
+	fc, configPath, err := config.LoadFileConfig()
+	if err != nil {
+		return nil, false, fmt.Errorf("load config: %w", err)
+	}
+
+	selected := map[string]bool{}
+	for _, item := range splitCommaList(value) {
+		selected[item] = true
+	}
+	for endpoint, path := range map[string]string{
+		"evaluate":   "security.allowEvaluate",
+		"macro":      "security.allowMacro",
+		"screencast": "security.allowScreencast",
+		"download":   "security.allowDownload",
+		"upload":     "security.allowUpload",
+	} {
+		enabled := selected[endpoint]
+		if err := config.SetConfigValue(fc, path, fmt.Sprintf("%t", enabled)); err != nil {
+			return nil, false, fmt.Errorf("set %s: %w", endpoint, err)
+		}
+	}
+	if errs := config.ValidateFileConfig(fc); len(errs) > 0 {
+		return nil, false, errs[0]
+	}
+	if err := config.SaveFileConfig(fc, configPath); err != nil {
+		return nil, false, fmt.Errorf("save config: %w", err)
+	}
+	return config.Load(), true, nil
+}
+
+func updateContentGuard(mode string) (*config.RuntimeConfig, bool, error) {
+	fc, configPath, err := config.LoadFileConfig()
+	if err != nil {
+		return nil, false, fmt.Errorf("load config: %w", err)
+	}
+
+	scan := mode == "both" || mode == "scan"
+	wrap := mode == "both" || mode == "wrap"
+	for _, item := range []struct {
+		path  string
+		value bool
+	}{
+		{path: "security.idpi.scanContent", value: scan},
+		{path: "security.idpi.wrapContent", value: wrap},
+	} {
+		if err := config.SetConfigValue(fc, item.path, fmt.Sprintf("%t", item.value)); err != nil {
+			return nil, false, fmt.Errorf("set %s: %w", item.path, err)
+		}
+	}
+	if errs := config.ValidateFileConfig(fc); len(errs) > 0 {
+		return nil, false, errs[0]
+	}
+	if err := config.SaveFileConfig(fc, configPath); err != nil {
+		return nil, false, fmt.Errorf("save config: %w", err)
+	}
+	return config.Load(), true, nil
+}
+
+func applyGuardsDownPreset() (*config.RuntimeConfig, string, bool, error) {
+	fc, configPath, err := config.LoadFileConfig()
+	if err != nil {
+		return nil, "", false, fmt.Errorf("load config: %w", err)
+	}
+	originalJSON, err := formatFileConfigJSON(fc)
+	if err != nil {
+		return nil, "", false, err
+	}
+
+	original, err := config.GetConfigValue(fc, "server.token")
+	if err != nil {
+		return nil, "", false, fmt.Errorf("read server.token: %w", err)
+	}
+	if strings.TrimSpace(original) == "" {
+		token, err := config.GenerateAuthToken()
+		if err != nil {
+			return nil, "", false, fmt.Errorf("generate token: %w", err)
+		}
+		if err := config.SetConfigValue(fc, "server.token", token); err != nil {
+			return nil, "", false, fmt.Errorf("set server.token: %w", err)
+		}
+	}
+
+	for _, item := range []struct {
+		path  string
+		value string
+	}{
+		{path: "server.bind", value: "127.0.0.1"},
+		{path: "security.allowEvaluate", value: "true"},
+		{path: "security.allowMacro", value: "true"},
+		{path: "security.allowScreencast", value: "true"},
+		{path: "security.allowDownload", value: "true"},
+		{path: "security.allowUpload", value: "true"},
+		{path: "security.attach.enabled", value: "true"},
+		{path: "security.attach.allowHosts", value: "127.0.0.1,localhost,::1"},
+		{path: "security.attach.allowSchemes", value: "ws,wss"},
+		{path: "security.idpi.enabled", value: "false"},
+		{path: "security.idpi.strictMode", value: "false"},
+		{path: "security.idpi.scanContent", value: "false"},
+		{path: "security.idpi.wrapContent", value: "false"},
+	} {
+		if err := config.SetConfigValue(fc, item.path, item.value); err != nil {
+			return nil, "", false, fmt.Errorf("set %s: %w", item.path, err)
+		}
+	}
+
+	if errs := config.ValidateFileConfig(fc); len(errs) > 0 {
+		return nil, "", false, errs[0]
+	}
+
+	nextJSON, err := formatFileConfigJSON(fc)
+	if err != nil {
+		return nil, "", false, err
+	}
+	changed := originalJSON != nextJSON
+	if !changed {
+		return config.Load(), configPath, false, nil
+	}
+
+	if err := config.SaveFileConfig(fc, configPath); err != nil {
+		return nil, "", false, fmt.Errorf("save config: %w", err)
+	}
+	return config.Load(), configPath, true, nil
+}
+
+func applySecurityUp() (*config.RuntimeConfig, bool, error) {
+	configPath, changed, err := cli.RestoreSecurityDefaults()
+	if err != nil {
+		return nil, false, fmt.Errorf("restore defaults: %w", err)
+	}
+	if !changed {
+		fmt.Println(cli.StyleStdout(cli.MutedStyle, fmt.Sprintf("Security defaults already match %s", configPath)))
+		return config.Load(), false, nil
+	}
+	fmt.Println(cli.StyleStdout(cli.SuccessStyle, fmt.Sprintf("Security defaults restored in %s", configPath)))
+	fmt.Println(cli.StyleStdout(cli.MutedStyle, "Restart PinchTab to apply file-based changes."))
+	return config.Load(), true, nil
+}
+
+func applySecurityDown() (*config.RuntimeConfig, bool, error) {
+	nextCfg, configPath, changed, err := applyGuardsDownPreset()
+	if err != nil {
+		return nil, false, fmt.Errorf("guards down: %w", err)
+	}
+	if !changed {
+		fmt.Println(cli.StyleStdout(cli.MutedStyle, fmt.Sprintf("Guards down preset already matches %s", configPath)))
+		return nextCfg, false, nil
+	}
+	fmt.Println(cli.StyleStdout(cli.WarningStyle, fmt.Sprintf("Guards down preset applied in %s", configPath)))
+	fmt.Println(cli.StyleStdout(cli.MutedStyle, "Loopback bind and API auth remain enabled; sensitive endpoints and attach are enabled, IDPI is disabled."))
+	return nextCfg, true, nil
+}
+
+func handleSecurityUpCommand() {
+	if _, _, err := applySecurityUp(); err != nil {
+		fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, err.Error()))
+		os.Exit(1)
+	}
+}
+
+func handleSecurityDownCommand() {
+	if _, _, err := applySecurityDown(); err != nil {
+		fmt.Fprintln(os.Stderr, cli.StyleStderr(cli.ErrorStyle, err.Error()))
+		os.Exit(1)
+	}
+}
+
+func formatFileConfigJSON(fc *config.FileConfig) (string, error) {
+	data, err := json.Marshal(fc)
+	if err != nil {
+		return "", fmt.Errorf("marshal config: %w", err)
+	}
+	return string(data), nil
+}
+
+func splitCommaList(value string) []string {
+	parts := strings.Split(value, ",")
+	items := make([]string, 0, len(parts))
+	for _, part := range parts {
+		trimmed := strings.TrimSpace(strings.ToLower(part))
+		if trimmed != "" {
+			items = append(items, trimmed)
+		}
+	}
+	slices.Sort(items)
+	return slices.Compact(items)
+}