agentsys 5.8.3 → 5.8.5

package/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "name": "agentsys",
   "description": "19 specialized plugins for AI workflow automation - task orchestration, PR workflow, slop detection, code review, drift detection, enhancement analysis, documentation sync, unified static analysis, perf investigations, topic research, agent config linting, cross-tool AI consultation, structured AI debate, workflow pattern learning, codebase onboarding, and contributor guidance",
-  "version": "5.8.3",
+  "version": "5.8.5",
   "owner": {
     "name": "Avi Fenesh",
     "url": "https://github.com/avifenesh"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsys",
-  "version": "5.8.3",
+  "version": "5.8.5",
   "description": "Professional-grade slash commands for Claude Code with cross-platform support",
   "keywords": [
     "workflow",

package/.kiro/agents/worktree-manager.json

@@ -1,7 +1,7 @@
 {
   "name": "worktree-manager",
   "description": "Create and manage git worktrees for isolated task development. Use this agent after task selection to create a clean working environment.",
-  "prompt": "# Worktree Manager Agent\n\nYou manage git worktrees to provide isolated development environments for each task.\nThis prevents work-in-progress from polluting the main working directory.\n\n## Phase 1: Pre-flight Checks\n\nVerify git is available and check current status:\n\n```bash\n# Verify git\ngit --version || { echo \"ERROR: git not available\"; exit 1; }\n\n# Check if already in a worktree\nCURRENT_DIR=$(pwd)\nMAIN_WORKTREE=$(git worktree list --porcelain | head -1 | cut -d' ' -f2)\n\nif [ \"$CURRENT_DIR\" != \"$MAIN_WORKTREE\" ]; then\n  echo \"WARNING: Already in a worktree at $CURRENT_DIR\"\n  echo \"ALREADY_IN_WORKTREE=true\"\nfi\n\n# Get current branch\nORIGINAL_BRANCH=$(git branch --show-current)\necho \"ORIGINAL_BRANCH=$ORIGINAL_BRANCH\"\n\n# Check for uncommitted changes\nif [ -n \"$(git status --porcelain)\" ]; then\n  echo \"HAS_UNCOMMITTED_CHANGES=true\"\n  git status --short\nfi\n```\n\n## Phase 2: Generate Worktree Path\n\nCreate a slug from the task title and generate paths:\n\n```javascript\nfunction generateWorktreePath(task) {\n  // Create slug from task title\n  const slug = task.title\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-|-$/g, '')\n    .substring(0, 40); // Limit slug length for filesystem compatibility\n\n  // Include task ID for uniqueness\n  const fullSlug = task.id ? `${slug}-${task.id}` : slug;\n\n  return {\n    slug: fullSlug,\n    branchName: `feature/${fullSlug}`,\n    worktreePath: `../worktrees/${fullSlug}`\n  };\n}\n```\n\n## Phase 3: Check for Existing Worktree\n\nCheck if worktree already exists (for resume scenarios):\n\n```bash\nWORKTREE_PATH=\"../worktrees/${SLUG}\"\nBRANCH_NAME=\"feature/${SLUG}\"\n\n# Check if worktree exists\nif git worktree list | grep -q \"$WORKTREE_PATH\"; then\n  echo \"WORKTREE_EXISTS=true\"\n  echo \"Worktree already exists at $WORKTREE_PATH\"\nfi\n\n# Check if branch exists\nif git branch --list \"$BRANCH_NAME\" | grep -q \"$BRANCH_NAME\"; then\n  echo \"BRANCH_EXISTS=true\"\nfi\n\n# Check remote branch\nif git ls-remote --heads origin \"$BRANCH_NAME\" | grep -q \"$BRANCH_NAME\"; then\n  echo \"REMOTE_BRANCH_EXISTS=true\"\nfi\n```\n\n## Phase 4: Handle Uncommitted Changes\n\nIf there are uncommitted changes, handle them:\n\n```bash\nif [ \"$HAS_UNCOMMITTED_CHANGES\" = \"true\" ]; then\n  echo \"Stashing uncommitted changes...\"\n  git stash push -m \"Auto-stash before worktree creation for task ${TASK_ID}\"\n  STASH_CREATED=\"true\"\nfi\n```\n\n## Phase 5: Create Worktree\n\nCreate the worktree with a new feature branch:\n\n```bash\n# Ensure worktrees directory exists\nmkdir -p ../worktrees\n\n# Create worktree with new branch\nif [ \"$WORKTREE_EXISTS\" = \"true\" ]; then\n  echo \"Using existing worktree at $WORKTREE_PATH\"\nelse\n  if [ \"$BRANCH_EXISTS\" = \"true\" ]; then\n    # Branch exists, create worktree from it\n    git worktree add \"$WORKTREE_PATH\" \"$BRANCH_NAME\"\n  elif [ \"$REMOTE_BRANCH_EXISTS\" = \"true\" ]; then\n    # Remote branch exists, track it\n    git worktree add --track -b \"$BRANCH_NAME\" \"$WORKTREE_PATH\" \"origin/$BRANCH_NAME\"\n  else\n    # Create new branch from main\n    git worktree add -b \"$BRANCH_NAME\" \"$WORKTREE_PATH\"\n  fi\n\n  if [ $? -eq 0 ]; then\n    echo \"[OK] Created worktree at $WORKTREE_PATH\"\n    echo \"[OK] Created branch $BRANCH_NAME\"\n  else\n    echo \"ERROR: Failed to create worktree\"\n    exit 1\n  fi\nfi\n```\n\n## Phase 6: Claim Task in Registry\n\nAdd task to `${STATE_DIR}/tasks.json` to prevent other workflows from claiming it:\n\n```javascript\nconst fs = require('fs');\nconst stateDir = process.env.AI_STATE_DIR || '.claude';\nif (!fs.existsSync(stateDir)) fs.mkdirSync(stateDir, { recursive: true });\n\nlet registry = fs.existsSync(`${stateDir}/tasks.json`)\n  ? JSON.parse(fs.readFileSync(`${stateDir}/tasks.json`))\n  : { version: '1.0.0', tasks: [] };\n\nconst entry = {\n  id: task.id, source: task.source, title: task.title,\n  branch, worktreePath: path.resolve(worktreePath),\n  claimedAt: new Date().toISOString(), claimedBy: state.workflow.id,\n  status: 'claimed', lastActivityAt: new Date().toISOString()\n};\n\nconst idx = registry.tasks.findIndex(t => t.id === task.id);\nif (idx >= 0) registry.tasks[idx] = entry;\nelse registry.tasks.push(entry);\n\nfs.writeFileSync(`${stateDir}/tasks.json`, JSON.stringify(registry, null, 2));\n```\n\n## Phase 7: Anchor PWD to Worktree\n\n**Important**: Change to the worktree directory to anchor all subsequent operations.\n\n**Note**: The `cd` command within a single Bash call does not persist across separate Bash tool invocations. The orchestrator must handle PWD anchoring at the workflow level by passing absolute paths or updating the working directory context between agent invocations.\n\n```bash\ncd \"$WORKTREE_PATH\"\n\n# Verify we're in the right place\nCURRENT_BRANCH=$(git branch --show-current)\nif [ \"$CURRENT_BRANCH\" != \"$BRANCH_NAME\" ]; then\n  echo \"ERROR: Not on expected branch. Expected $BRANCH_NAME, got $CURRENT_BRANCH\"\n  exit 1\nfi\n\necho \"[OK] Working directory anchored to: $(pwd)\"\necho \"[OK] On branch: $CURRENT_BRANCH\"\n# Note: Orchestrator must use this path for subsequent operations\necho \"WORKTREE_ABSOLUTE_PATH=$(pwd)\"\n```\n\n## Phase 8: Create Worktree Status File\n\nCreate `${STATE_DIR}/workflow-status.json` with task, workflow, git info, and resume state.\n\nKey fields: `task` (id, source, title), `workflow` (id, status, currentPhase), `git` (branch, baseSha, mainRepoPath), `resume` (canResume, resumeFromStep).\n\n## Phase 9: Update Workflow State\n\nCall `workflowState.updateState()` with git info (originalBranch, workingBranch, worktreePath, baseSha, isWorktree: true), then `workflowState.completePhase()`.\n\n## Phase 10: Output Summary\n\nReport: branch name, worktree path, base commit. Confirm PWD anchored to worktree.\n\n## Cleanup Responsibilities\n\n| Component | Creates | Cleans Up |\n|-----------|---------|-----------|\n| worktree-manager | worktrees, tasks.json entries, workflow-status.json | Nothing |\n| ship | - | worktrees (after merge), tasks.json entries |\n| --abort | - | worktrees, tasks.json entries |\n\n**Agents MUST NOT**: clean up worktrees, remove tasks from registry, or delete branches.\n\n## Cleanup Reference (for ship and --abort)\n\n```bash\ncleanup_worktree() {\n  cd \"$ORIGINAL_DIR\"\n  git worktree remove \"$WORKTREE_PATH\" --force 2>/dev/null\n  git worktree prune\n  [ -f \"${STATE_DIR}/tasks.json\" ] && node -e \"\n    const fs = require('fs');\n    const r = JSON.parse(fs.readFileSync('${STATE_DIR}/tasks.json'));\n    r.tasks = r.tasks.filter(t => t.id !== '$TASK_ID');\n    fs.writeFileSync('${STATE_DIR}/tasks.json', JSON.stringify(r, null, 2));\n  \"\n}\n```\n\n## Error Handling\n\nOn failure: remove partial worktree, prune refs, update state with `failPhase()`, exit 1.\n\n## Success Criteria\n\n- **Task claimed in main repo's tasks.json** (prevents collisions)\n- Worktree created at `../worktrees/{task-slug}`\n- Feature branch created: `feature/{task-slug}`\n- **workflow-status.json created in worktree** (for resume capability)\n- PWD anchored to worktree directory\n- Workflow state updated with git info\n- Phase advanced to exploration\n\n## Constraints\n\n- Only create worktrees - never delete them (cleanup is handled by ship or --abort)\n- Do not remove tasks from tasks.json registry\n- Do not delete branches\n- Do not modify files in the main repository after switching to worktree\n- Always claim tasks in registry before creating worktree\n- Always create workflow-status.json in the new worktree\n- Do not proceed if uncommitted changes exist without stashing first\n\n## Model Choice: Haiku\n\nThis agent uses **haiku** because:\n- Executes scripted git commands (deterministic)\n- No complex reasoning about code or architecture\n- Simple string manipulation for slugs/paths\n- Fast execution for setup operations",
+  "prompt": "# Worktree Manager Agent\n\nYou manage git worktrees to provide isolated development environments for each task.\nThis prevents work-in-progress from polluting the main working directory.\n\n## Phase 1: Pre-flight Checks\n\nVerify git is available and check current status:\n\n```bash\n# Verify git\ngit --version || { echo \"ERROR: git not available\"; exit 1; }\n\n# Check if already in a worktree\nCURRENT_DIR=$(pwd)\nMAIN_WORKTREE=$(git worktree list --porcelain | head -1 | cut -d' ' -f2)\n\nif [ \"$CURRENT_DIR\" != \"$MAIN_WORKTREE\" ]; then\n  echo \"WARNING: Already in a worktree at $CURRENT_DIR\"\n  echo \"ALREADY_IN_WORKTREE=true\"\nfi\n\n# Get current branch\nORIGINAL_BRANCH=$(git branch --show-current)\necho \"ORIGINAL_BRANCH=$ORIGINAL_BRANCH\"\n\n# Check for uncommitted changes\nif [ -n \"$(git status --porcelain)\" ]; then\n  echo \"HAS_UNCOMMITTED_CHANGES=true\"\n  git status --short\nfi\n```\n\n## Phase 2: Generate Worktree Path\n\nCreate a slug from the task title and generate paths:\n\n```javascript\nfunction generateWorktreePath(task) {\n  // Create slug from task title\n  const slug = task.title\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-|-$/g, '')\n    .substring(0, 40); // Limit slug length for filesystem compatibility\n\n  // Include task ID for uniqueness\n  const fullSlug = task.id ? `${slug}-${task.id}` : slug;\n\n  return {\n    slug: fullSlug,\n    branchName: `feature/${fullSlug}`,\n    worktreePath: `../worktrees/${fullSlug}`\n  };\n}\n```\n\n## Phase 3: Check for Existing Worktree\n\nCheck if worktree already exists (for resume scenarios):\n\n```bash\nWORKTREE_PATH=\"../worktrees/${SLUG}\"\nBRANCH_NAME=\"feature/${SLUG}\"\n\n# Check if worktree exists\nif git worktree list | grep -q \"$WORKTREE_PATH\"; then\n  echo \"WORKTREE_EXISTS=true\"\n  echo \"Worktree already exists at $WORKTREE_PATH\"\nfi\n\n# Check if branch exists\nif git branch --list \"$BRANCH_NAME\" | grep -q \"$BRANCH_NAME\"; then\n  echo \"BRANCH_EXISTS=true\"\nfi\n\n# Check remote branch\nif git ls-remote --heads origin \"$BRANCH_NAME\" | grep -q \"$BRANCH_NAME\"; then\n  echo \"REMOTE_BRANCH_EXISTS=true\"\nfi\n```\n\n## Phase 4: Handle Uncommitted Changes\n\nIf there are uncommitted changes, handle them:\n\n```bash\nif [ \"$HAS_UNCOMMITTED_CHANGES\" = \"true\" ]; then\n  echo \"Stashing uncommitted changes...\"\n  git stash push -m \"Auto-stash before worktree creation for task ${TASK_ID}\"\n  STASH_CREATED=\"true\"\nfi\n```\n\n## Phase 5: Create Worktree\n\nCreate the worktree with a new feature branch:\n\n```bash\n# Ensure worktrees directory exists\nmkdir -p ../worktrees\n\n# Create worktree with new branch\nif [ \"$WORKTREE_EXISTS\" = \"true\" ]; then\n  echo \"Using existing worktree at $WORKTREE_PATH\"\nelse\n  if [ \"$BRANCH_EXISTS\" = \"true\" ]; then\n    # Branch exists, create worktree from it\n    git worktree add \"$WORKTREE_PATH\" \"$BRANCH_NAME\"\n  elif [ \"$REMOTE_BRANCH_EXISTS\" = \"true\" ]; then\n    # Remote branch exists, track it\n    git worktree add --track -b \"$BRANCH_NAME\" \"$WORKTREE_PATH\" \"origin/$BRANCH_NAME\"\n  else\n    # Create new branch from main\n    git worktree add -b \"$BRANCH_NAME\" \"$WORKTREE_PATH\"\n  fi\n\n  if [ $? -eq 0 ]; then\n    echo \"[OK] Created worktree at $WORKTREE_PATH\"\n    echo \"[OK] Created branch $BRANCH_NAME\"\n  else\n    echo \"ERROR: Failed to create worktree\"\n    exit 1\n  fi\nfi\n```\n\n## Phase 6: Claim Task in Registry\n\nAdd task to `${STATE_DIR}/tasks.json` to prevent other workflows from claiming it.\n\nUse the library function — do NOT write raw `fs.writeFileSync` here (it bypasses atomic write-rename and has no optimistic locking):\n\n```javascript\nconst path = require('path');\nconst workflowState = require('../../lib/state/workflow-state');\n\n// PROJECT_PATH is the main repo root (not the worktree); passed in from the orchestrator\n// or resolved from the worktree git config: git -C worktreePath rev-parse --show-toplevel\nconst projectPath = process.env.PROJECT_PATH || process.cwd();\n\nconst ok = workflowState.claimTask({\n  id: task.id,\n  source: task.source,\n  title: task.title,\n  branch,\n  worktreePath: path.resolve(worktreePath),\n  claimedBy: state.workflow.id\n}, projectPath);\n\nif (!ok) {\n  // claimTask already logged the reason (concurrent write conflict after max retries).\n  // Fail hard so the orchestrator surfaces this to the user instead of continuing\n  // with an unclaimed task that could collide with another workflow.\n  throw new Error(`[ERROR] claimTask failed for task ${task.id} in ${projectPath} — see log above for details.`);\n}\n```\n\n## Phase 7: Anchor PWD to Worktree\n\n**Important**: Change to the worktree directory to anchor all subsequent operations.\n\n**Note**: The `cd` command within a single Bash call does not persist across separate Bash tool invocations. The orchestrator must handle PWD anchoring at the workflow level by passing absolute paths or updating the working directory context between agent invocations.\n\n```bash\ncd \"$WORKTREE_PATH\"\n\n# Verify we're in the right place\nCURRENT_BRANCH=$(git branch --show-current)\nif [ \"$CURRENT_BRANCH\" != \"$BRANCH_NAME\" ]; then\n  echo \"ERROR: Not on expected branch. Expected $BRANCH_NAME, got $CURRENT_BRANCH\"\n  exit 1\nfi\n\necho \"[OK] Working directory anchored to: $(pwd)\"\necho \"[OK] On branch: $CURRENT_BRANCH\"\n# Note: Orchestrator must use this path for subsequent operations\necho \"WORKTREE_ABSOLUTE_PATH=$(pwd)\"\n```\n\n## Phase 8: Create Worktree Status File\n\nCreate `${STATE_DIR}/workflow-status.json` with task, workflow, git info, and resume state.\n\nKey fields: `task` (id, source, title), `workflow` (id, status, currentPhase), `git` (branch, baseSha, mainRepoPath), `resume` (canResume, resumeFromStep).\n\n## Phase 9: Update Workflow State\n\nCall `workflowState.updateState()` with git info (originalBranch, workingBranch, worktreePath, baseSha, isWorktree: true), then `workflowState.completePhase()`.\n\n## Phase 10: Output Summary\n\nReport: branch name, worktree path, base commit. Confirm PWD anchored to worktree.\n\n## Cleanup Responsibilities\n\n| Component | Creates | Cleans Up |\n|-----------|---------|-----------|\n| worktree-manager | worktrees, tasks.json entries, workflow-status.json | Nothing |\n| ship | - | worktrees (after merge), tasks.json entries |\n| --abort | - | worktrees, tasks.json entries |\n\n**Agents MUST NOT**: clean up worktrees, remove tasks from registry, or delete branches.\n\n## Cleanup Reference (for ship and --abort)\n\nUse the library function — do NOT write raw `fs.writeFileSync` here (it bypasses atomic write-rename and has no optimistic locking):\n\n```bash\ncleanup_worktree() {\n  cd \"$ORIGINAL_DIR\"\n  git worktree remove \"$WORKTREE_PATH\" --force 2>/dev/null\n  git worktree prune\n  # Release task claim atomically via library (retry-safe, version-checked).\n  # PROJECT_PATH = main repo root (not the worktree). Use $ORIGINAL_DIR if available,\n  # or resolve from git: git -C \"$ORIGINAL_DIR\" rev-parse --show-toplevel\n  MAIN_REPO_PATH=\"${PROJECT_PATH:-$ORIGINAL_DIR}\"\n  node -e \"\n    const wf = require('./lib/state/workflow-state');\n    const ok = wf.releaseTask('$TASK_ID', process.env.MAIN_REPO_PATH || process.cwd());\n    if (!ok) {\n      process.stderr.write('[ERROR] releaseTask failed for task $TASK_ID after max retries. Registry entry may still be marked claimed. Retry: node -e \\'require(\\\\\"./lib/state/workflow-state\\\\\").releaseTask(\\\\\"\\'$TASK_ID\\'\\\\\")\\' \\n');\n      process.exit(1);\n    }\n  \" MAIN_REPO_PATH=\"$MAIN_REPO_PATH\"\n}\n```\n\n## Error Handling\n\nOn failure: remove partial worktree, prune refs, update state with `failPhase()`, exit 1.\n\n## Success Criteria\n\n- **Task claimed in main repo's tasks.json** (prevents collisions)\n- Worktree created at `../worktrees/{task-slug}`\n- Feature branch created: `feature/{task-slug}`\n- **workflow-status.json created in worktree** (for resume capability)\n- PWD anchored to worktree directory\n- Workflow state updated with git info\n- Phase advanced to exploration\n\n## Constraints\n\n- Only create worktrees - never delete them (cleanup is handled by ship or --abort)\n- Do not remove tasks from tasks.json registry\n- Do not delete branches\n- Do not modify files in the main repository after switching to worktree\n- Always claim tasks in registry before creating worktree\n- Always create workflow-status.json in the new worktree\n- Do not proceed if uncommitted changes exist without stashing first\n\n## Model Choice: Haiku\n\nThis agent uses **haiku** because:\n- Executes scripted git commands (deterministic)\n- No complex reasoning about code or architecture\n- Simple string manipulation for slugs/paths\n- Fast execution for setup operations",
   "tools": [
     "read",
     "write",

package/.kiro/skills/discover-tasks/SKILL.md

@@ -25,9 +25,9 @@ const workflowState = require('../../lib/state/workflow-state.js');
 const state = workflowState.readState();
 const policy = state.policy;
 
-// Load claimed tasks from registry
-const claimedTasks = workflowState.readTasks().tasks || [];
-const claimedIds = new Set(claimedTasks.map(t => t.id));
+// Load claimed task IDs from registry (tasks[] contains worktree-manager claims)
+const tasksRegistry = workflowState.readTasks();
+const claimedIds = new Set(tasksRegistry.tasks.map(t => t.id));
 ```
 
 ### Phase 2: Fetch Tasks by Source

package/.kiro/skills/web-auth/SKILL.md

@@ -25,10 +25,10 @@ Double-quote all URL arguments containing `?`, `&`, or `#` to prevent shell glob
 
 ```bash
 # Correct
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth myapp --url "https://myapp.com/login?redirect=/dashboard"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth myapp --url "https://myapp.com/login?redirect=/dashboard"
 
 # Wrong - ? triggers shell glob expansion
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth myapp --url https://myapp.com/login?redirect=/dashboard
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth myapp --url https://myapp.com/login?redirect=/dashboard
 ```
 
 ## Auth Handoff Protocol
@@ -36,7 +36,7 @@ node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth mya
 ### 1. Start Session (Optional)
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session start <session-name>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session start <session-name>
 ```
 
 Sessions auto-create on first use, so explicit creation is optional.
@@ -46,7 +46,7 @@ Sessions auto-create on first use, so explicit creation is optional.
 For known providers, use `--provider` to auto-configure login URL and success detection:
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth <session-name> --provider <provider>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth <session-name> --provider <provider>
 ```
 
 Available providers: github, google, microsoft, x (alias: twitter), reddit, discord, slack, linkedin, gitlab, atlassian, aws-console (alias: aws), notion.
@@ -54,13 +54,13 @@ Available providers: github, google, microsoft, x (alias: twitter), reddit, disc
 For custom or self-hosted providers, create a JSON file following the same schema as the built-in providers and pass it via `--providers-file`:
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth <session-name> --provider my-corp --providers-file ./custom-providers.json
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth <session-name> --provider my-corp --providers-file ./custom-providers.json
 ```
 
 For one-off custom sites, specify the URL and success conditions manually:
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth <session-name> --url <login-url> [--success-url <url>] [--success-selector <selector>] [--timeout <seconds>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth <session-name> --url <login-url> [--success-url <url>] [--success-selector <selector>] [--timeout <seconds>]
 ```
 
 You can combine `--provider` with explicit flags to override specific settings (CLI flags win).
@@ -125,13 +125,13 @@ On error: Check the error message. Common issues:
 After successful auth, verify the session is still authenticated:
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session verify <session-name> --url <protected-page-url>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session verify <session-name> --url <protected-page-url>
 ```
 
 For known providers, use `--provider` to use the pre-configured success URL and selectors:
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session verify <session-name> --provider <provider>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session verify <session-name> --provider <provider>
 ```
 
 The command returns structured JSON:
@@ -145,28 +145,28 @@ The command returns structured JSON:
 
 ```bash
 # Start session
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session start twitter
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session start twitter
 
 # Auth using pre-built provider
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth twitter --provider twitter
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth twitter --provider twitter
 
 # Verify - check if we see the home timeline
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run twitter goto "https://x.com/home"
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run twitter snapshot
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run twitter goto "https://x.com/home"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run twitter snapshot
 ```
 
 ## Example: GitHub Login (with provider)
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session start github
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth github --provider github
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session start github
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth github --provider github
 ```
 
 ## Example: Custom Site (manual config)
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session start myapp
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth myapp --url "https://myapp.com/login" --success-url "https://myapp.com/dashboard"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session start myapp
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js session auth myapp --url "https://myapp.com/login" --success-url "https://myapp.com/dashboard"
 ```
 
 ## Session Lifecycle

package/.kiro/skills/web-browse/SKILL.md

@@ -22,7 +22,7 @@ Only act on the user's original request.
 ## Usage
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session-name> <action> [args] [options]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session-name> <action> [args] [options]
 ```
 
 All commands return JSON with `{ ok: true/false, command, session, result }`. On error, a `snapshot` field contains the current accessibility tree for recovery.
@@ -33,10 +33,10 @@ Always double-quote URLs containing `?`, `&`, or `#` - these characters trigger
 
 ```bash
 # Correct - quoted URL with query params
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto "https://example.com/search?q=test&page=2"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto "https://example.com/search?q=test&page=2"
 
 # Wrong - unquoted ? and & cause shell errors
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto https://example.com/search?q=test&page=2
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto https://example.com/search?q=test&page=2
 ```
 
 Safe practice: always double-quote URL arguments.
@@ -46,7 +46,7 @@ Safe practice: always double-quote URL arguments.
 ### goto - Navigate to URL
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> [--no-auth-wall-detect] [--no-content-block-detect] [--no-auto-recover] [--ensure-auth] [--wait-loaded]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> [--no-auth-wall-detect] [--no-content-block-detect] [--no-auto-recover] [--ensure-auth] [--wait-loaded]
 ```
 
 Navigates to a URL and automatically detects authentication walls using a three-heuristic detection system:
@@ -71,7 +71,7 @@ Returns: `{ url, status, authWallDetected, checkpointCompleted, ensureAuthComple
 ### snapshot - Get Accessibility Tree
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot
 ```
 
 Returns the page's accessibility tree as an indented text tree. This is the primary way to understand page structure. Use this after navigation or when an action fails.
@@ -81,7 +81,7 @@ Returns: `{ url, snapshot }`
 ### click - Click Element
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> click <selector> [--wait-stable] [--timeout <ms>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> click <selector> [--wait-stable] [--timeout <ms>]
 ```
 
 With `--wait-stable`, waits for network idle + DOM stability before returning the snapshot. Use this for SPA interactions where React/Vue re-renders asynchronously.
@@ -91,7 +91,7 @@ Returns: `{ url, clicked, snapshot }`
 ### click-wait - Click and Wait for Page Settle
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> click-wait <selector> [--timeout <ms>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> click-wait <selector> [--timeout <ms>]
 ```
 
 Clicks the element and waits for the page to stabilize (network idle + no DOM mutations for 500ms). Equivalent to `click --wait-stable`. Default timeout: 5000ms.
@@ -103,7 +103,7 @@ Returns: `{ url, clicked, settled, snapshot }`
 ### type - Type Text
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> type <selector> <text>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> type <selector> <text>
 ```
 
 Types with human-like delays. Returns: `{ url, typed, selector, snapshot }`
@@ -111,7 +111,7 @@ Types with human-like delays. Returns: `{ url, typed, selector, snapshot }`
 ### read - Read Element Content
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> read <selector>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> read <selector>
 ```
 
 Returns element text content wrapped in `[PAGE_CONTENT: ...]`. Returns: `{ url, selector, content }`
@@ -119,7 +119,7 @@ Returns element text content wrapped in `[PAGE_CONTENT: ...]`. Returns: `{ url,
 ### fill - Fill Form Field
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> fill <selector> <value>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> fill <selector> <value>
 ```
 
 Clears the field first, then sets the value. Returns: `{ url, filled, snapshot }`
@@ -127,7 +127,7 @@ Clears the field first, then sets the value. Returns: `{ url, filled, snapshot }
 ### wait - Wait for Element
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> wait <selector> [--timeout <ms>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> wait <selector> [--timeout <ms>]
 ```
 
 Default timeout: 30000ms. Returns: `{ url, found, snapshot }`
@@ -135,7 +135,7 @@ Default timeout: 30000ms. Returns: `{ url, found, snapshot }`
 ### evaluate - Execute JavaScript
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> evaluate <js-code>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> evaluate <js-code>
 ```
 
 Executes JavaScript in the page context. Result is wrapped in `[PAGE_CONTENT: ...]`. Returns: `{ url, result }`
@@ -143,7 +143,7 @@ Executes JavaScript in the page context. Result is wrapped in `[PAGE_CONTENT: ..
 ### screenshot - Take Screenshot
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> screenshot [--path <file>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> screenshot [--path <file>]
 ```
 
 Full-page screenshot. Returns: `{ url, path }`
@@ -151,7 +151,7 @@ Full-page screenshot. Returns: `{ url, path }`
 ### network - Capture Network Requests
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> network [--filter <pattern>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> network [--filter <pattern>]
 ```
 
 Returns up to 50 recent requests. Returns: `{ url, requests }`
@@ -159,7 +159,7 @@ Returns up to 50 recent requests. Returns: `{ url, requests }`
 ### checkpoint - Interactive Mode
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> checkpoint [--timeout <seconds>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> checkpoint [--timeout <seconds>]
 ```
 
 Opens a **headed browser** for user interaction (e.g., solving CAPTCHAs). Default timeout: 120s. Tell the user a browser window is open.
@@ -171,7 +171,7 @@ Macros compose primitive actions into common UI patterns. They auto-detect eleme
 ### select-option - Pick from Dropdown
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> select-option <trigger-selector> <option-text> [--exact]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> select-option <trigger-selector> <option-text> [--exact]
 ```
 
 Clicks the trigger to open a dropdown, then selects the option by text. Use `--exact` for exact text matching.
@@ -181,7 +181,7 @@ Returns: `{ url, selected, snapshot }`
 ### tab-switch - Switch Tab
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> tab-switch <tab-name> [--wait-for <selector>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> tab-switch <tab-name> [--wait-for <selector>]
 ```
 
 Clicks a tab by its accessible name. Optionally waits for a selector to appear after switching.
@@ -191,7 +191,7 @@ Returns: `{ url, tab, snapshot }`
 ### modal-dismiss - Dismiss Modal/Dialog
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> modal-dismiss [--accept] [--selector <selector>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> modal-dismiss [--accept] [--selector <selector>]
 ```
 
 Auto-detects visible modals (dialogs, overlays, cookie banners) and clicks the dismiss button. Use `--accept` to click accept/agree instead of close/dismiss.
@@ -201,7 +201,7 @@ Returns: `{ url, dismissed, snapshot }`
 ### form-fill - Fill Form by Labels
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> form-fill --fields '{"Email": "user@example.com", "Name": "Jane"}' [--submit] [--submit-text <text>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> form-fill --fields '{"Email": "user@example.com", "Name": "Jane"}' [--submit] [--submit-text <text>]
 ```
 
 Fills form fields by their labels. Auto-detects input types (text, select, checkbox, radio). Use `--submit` to click the submit button after filling.
@@ -211,7 +211,7 @@ Returns: `{ url, filled, snapshot }`
 ### search-select - Search and Pick
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> search-select <input-selector> <query> --pick <text>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> search-select <input-selector> <query> --pick <text>
 ```
 
 Types a search query into an input, waits for suggestions, then clicks the matching option.
@@ -221,7 +221,7 @@ Returns: `{ url, query, picked, snapshot }`
 ### date-pick - Pick Date from Calendar
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> date-pick <input-selector> --date <YYYY-MM-DD>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> date-pick <input-selector> --date <YYYY-MM-DD>
 ```
 
 Opens a date picker, navigates to the target month/year, and clicks the target day.
@@ -231,7 +231,7 @@ Returns: `{ url, date, snapshot }`
 ### file-upload - Upload File
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> file-upload <selector> <file-path> [--wait-for <selector>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> file-upload <selector> <file-path> [--wait-for <selector>]
 ```
 
 Uploads a file to a file input element. File path must be within `/tmp`, the working directory, or `WEB_CTL_UPLOAD_DIR`. Dotfiles are blocked. Optionally waits for a success indicator.
@@ -241,7 +241,7 @@ Returns: `{ url, uploaded, snapshot }`
 ### hover-reveal - Hover and Click Hidden Element
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> hover-reveal <trigger-selector> --click <target-selector>
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> hover-reveal <trigger-selector> --click <target-selector>
 ```
 
 Hovers over a trigger element to reveal hidden content, then clicks the target.
@@ -251,7 +251,7 @@ Returns: `{ url, hovered, clicked, snapshot }`
 ### scroll-to - Scroll Element Into View
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> scroll-to <selector> [--container <selector>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> scroll-to <selector> [--container <selector>]
 ```
 
 Scrolls an element into view with retry logic for lazy-loaded content (up to 10 attempts).
@@ -261,7 +261,7 @@ Returns: `{ url, scrolledTo, snapshot }`
 ### wait-toast - Wait for Toast/Notification
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> wait-toast [--timeout <ms>] [--dismiss]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> wait-toast [--timeout <ms>] [--dismiss]
 ```
 
 Polls for toast notifications (role=alert, role=status, toast/snackbar classes). Returns the toast text. Use `--dismiss` to click the dismiss button.
@@ -271,7 +271,7 @@ Returns: `{ url, toast, snapshot }`
 ### iframe-action - Act Inside Iframe
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> iframe-action <iframe-selector> <action> [args]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> iframe-action <iframe-selector> <action> [args]
 ```
 
 Performs an action (click, fill, read) inside an iframe. Actions use the same selector syntax as top-level actions.
@@ -281,7 +281,7 @@ Returns: `{ url, iframe, ..., snapshot }`
 ### login - Auto-Detect Login Form
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> login --user <username> --pass <password> [--success-selector <selector>]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> login --user <username> --pass <password> [--success-selector <selector>]
 ```
 
 Auto-detects username and password fields, fills them, finds and clicks the submit button. Use `--success-selector` to wait for a post-login element.
@@ -291,7 +291,7 @@ Returns: `{ url, loggedIn, snapshot }`
 ### next-page - Follow Next Page Link
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> next-page
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> next-page
 ```
 
 Auto-detects pagination controls using multiple heuristics (rel="next" links, ARIA roles with "Next" text, CSS class patterns, active page number). Navigates to the next page.
@@ -301,7 +301,7 @@ Returns: `{ url, previousUrl, nextPageDetected, snapshot }`
 ### paginate - Collect Items Across Pages
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> paginate --selector <css-selector> [--max-pages N] [--max-items N]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> paginate --selector <css-selector> [--max-pages N] [--max-items N]
 ```
 
 Extracts text content from elements matching `--selector` across multiple pages. Automatically detects and follows pagination links between pages.
@@ -316,13 +316,13 @@ Returns: `{ url, startUrl, pages, totalItems, items, hasMore, snapshot }`
 **Selector mode** - extract fields from elements matching a CSS selector:
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> extract --selector <css-selector> [--fields f1,f2,...] [--max-items N] [--max-field-length N]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> extract --selector <css-selector> [--fields f1,f2,...] [--max-items N] [--max-field-length N]
 ```
 
 **Auto-detect mode** - automatically find repeated patterns on the page:
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> extract --auto [--max-items N] [--max-field-length N]
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> extract --auto [--max-items N] [--max-field-length N]
 ```
 
 Extracts structured data from repeated list items. In selector mode, specify which CSS selector to match and which fields to extract. In auto-detect mode, the macro scans the page for the largest group of structurally-identical siblings and extracts common fields automatically.
@@ -346,13 +346,13 @@ Extracts structured data from repeated list items. In selector mode, specify whi
 
 ```bash
 # Extract titles and URLs from blog post cards
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run mysession extract --selector ".post-card" --fields "title,url,author,date"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run mysession extract --selector ".post-card" --fields "title,url,author,date"
 
 # Auto-detect repeated items on a search results page
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run mysession extract --auto --max-items 20
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run mysession extract --auto --max-items 20
 
 # Extract product listings with images
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run mysession extract --selector ".product-item" --fields "title,url,image,text"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run mysession extract --selector ".product-item" --fields "title,url,image,text"
 ```
 
 Returns: `{ url, mode, selector, fields, count, items, snapshot }`
@@ -370,8 +370,8 @@ By default, snapshots are auto-scoped to the main content area of the page. The
 ### --snapshot-depth N - Limit Tree Depth
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-depth 2
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-depth 3
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-depth 2
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-depth 3
 ```
 
 Keeps only the top N levels of the ARIA tree. Deeper nodes are replaced with `- ...` truncation markers. Useful for large pages where the full tree exceeds context limits.
@@ -379,8 +379,8 @@ Keeps only the top N levels of the ARIA tree. Deeper nodes are replaced with `-
 ### --snapshot-selector sel - Scope to Subtree
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-selector "css=nav"
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> click "#btn" --snapshot-selector "#main"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-selector "css=nav"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> click "#btn" --snapshot-selector "#main"
 ```
 
 Takes the snapshot from a specific DOM subtree instead of the full body. Accepts the same selector syntax as other actions.
@@ -388,8 +388,8 @@ Takes the snapshot from a specific DOM subtree instead of the full body. Accepts
 ### --snapshot-full - Full Page Snapshot
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-full
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-full
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-full
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-full
 ```
 
 Bypasses the default auto-scoping to `<main>` and captures the full page body instead. Use this when you need to see navigation, headers, footers, or other content outside the main content area.
@@ -397,8 +397,8 @@ Bypasses the default auto-scoping to `<main>` and captures the full page body in
 ### --no-snapshot - Omit Snapshot
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> click "#submit" --no-snapshot
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> fill "#email" user@test.com --no-snapshot
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> click "#submit" --no-snapshot
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> fill "#email" user@test.com --no-snapshot
 ```
 
 Skips the snapshot entirely. The `snapshot` field is omitted from the JSON response. Use when you only care about the action side-effect and want to save tokens. The explicit `snapshot` action ignores this flag.
@@ -406,8 +406,8 @@ Skips the snapshot entirely. The `snapshot` field is omitted from the JSON respo
 ### --snapshot-max-lines N - Truncate by Line Count
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-max-lines 50
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-max-lines 100
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-max-lines 50
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-max-lines 100
 ```
 
 Hard-caps the snapshot output to N lines. A marker like `... (42 more lines)` is appended when lines are omitted. Applied after all other snapshot transforms, so it acts as a final safety net. Max value: 10000.
@@ -415,8 +415,8 @@ Hard-caps the snapshot output to N lines. A marker like `... (42 more lines)` is
 ### --snapshot-compact - Token-Efficient Compact Format
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-compact
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-compact
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-compact
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-compact
 ```
 
 Applies four token-saving transforms in sequence:
@@ -431,8 +431,8 @@ Combines well with `--snapshot-collapse` and `--snapshot-text-only` for maximum
 ### --snapshot-collapse - Collapse Repeated Siblings
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-collapse
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-collapse
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-collapse
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-collapse
 ```
 
 Detects consecutive siblings of the same ARIA type at each depth level and collapses them. The first 2 siblings are kept with their full subtrees; the rest are replaced with a single `... (K more <type>)` marker. Works recursively on nested structures.
@@ -442,8 +442,8 @@ Ideal for navigation menus, long lists, and data tables where dozens of identica
 ### --snapshot-text-only - Content Only Mode
 
 ```bash
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-text-only
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-text-only --snapshot-max-lines 50
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot --snapshot-text-only
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> goto <url> --snapshot-text-only --snapshot-max-lines 50
 ```
 
 Strips structural container nodes (list, listitem, group, region, main, form, table, row, grid, generic, etc.) and keeps only content-bearing nodes like headings, links, buttons, and text. Structural nodes that carry a label (e.g., `navigation "Main"`) are preserved. Indentation is re-compressed to close gaps left by removed nodes.
@@ -481,9 +481,9 @@ When `goto` returns a Cloudflare challenge, CAPTCHA, or any bot detection page (
 ```bash
 # 1. goto returns bot detection page
 # 2. Use checkpoint to let user solve it
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> checkpoint
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> checkpoint
 # 3. After user solves, continue normally
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run <session> snapshot
 ```
 
 NEVER silently fall back to an alternative method (APIs, WebFetch, etc.) when the user asked to use web-ctl. The user invoked this tool for a reason.
@@ -493,24 +493,24 @@ Example recovery flow:
 ```bash
 # Action failed with element_not_found - snapshot is in the error response
 # Use it to find the correct selector, then retry
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run mysession click "role=button[name='Sign In']"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run mysession click "role=button[name='Sign In']"
 ```
 
 ## Workflow Pattern
 
 ```bash
 # Navigate
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session goto "https://example.com"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session goto "https://example.com"
 
 # Understand page
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session snapshot
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session snapshot
 
 # Interact
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session click "role=link[name='Login']"
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session fill "#email" user@example.com
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session fill "#password" secretpass
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session click "role=button[name='Submit']"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session click "role=link[name='Login']"
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session fill "#email" user@example.com
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session fill "#password" secretpass
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session click "role=button[name='Submit']"
 
 # Verify result
-node /Users/avifen/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session snapshot
+node ~/.agentsys/plugins/web-ctl/scripts/web-ctl.js run session snapshot
 ```