agentwire-dev 1.42.0__tar.gz → 1.43.0__tar.gz

agentwire_dev-1.43.0/.agents/skills/agentwire-cli/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: agentwire-cli
+description: Full `agentwire` CLI command reference — session/pane management, portal, TTS/STT, voice, channels (email + quo, outbound-only), machine/tunnel/lock management, projects/history/roles, scheduler, web helper (fetch), safety/diagnostics. Use when running or composing `agentwire ...` shell commands, building automation scripts, or answering "how do I X from the CLI".
+---
+
+# AgentWire CLI Reference
+
+```bash
+# Session management
+agentwire new -s name           # not: tmux new-session
+agentwire new -s name --no-soul # skip the always-injected soul personality role
+agentwire new -s name --first-message "idea"  # deliver first prompt once agent boots
+                                #   (verified paste, local only; failure ≠ command failure)
+agentwire send -s name "prompt" # not: tmux send-keys
+agentwire send -s name --wait-ready --timeout 60 -- "prompt"
+                                # wait for agent boot (banner + screen-stable +
+                                #   trust-prompt auto-accept), verified delivery,
+                                #   exit 1 if unverified; local only
+agentwire send-keys -s name key1 key2  # raw keys with pauses
+agentwire send-keys -s name --pane 2 key  # target a specific pane
+agentwire new -s name --created-by orch  # record creator (prompt-routing parent);
+                                #   default: calling tmux session; '' opts out
+agentwire output -s name        # not: tmux capture-pane
+agentwire info -s name          # session metadata (cwd, panes) as JSON
+agentwire kill -s name          # not: tmux kill-session
+agentwire list                  # not: tmux list-sessions
+agentwire recreate -s name      # destroy and recreate with fresh worktree
+agentwire worktree name         # new branch + worktree + STANDALONE session
+                                #   "worktree session" ALWAYS means this command — never
+                                #   `spawn --branch` (that makes a pane). Defaults to the
+                                #   bypass posture (autonomous); override with --posture.
+                                #   The worktree-session etiquette role is intrinsic to
+                                #   the verb (isolation, no rebuild/restart, verify
+                                #   in-worktree, draft PR + notify-back) — first prompts
+                                #   only need the task itself
+                                #   Base branch (default mode): --base wins, else config
+                                #   worktree.default_base, else the repo's actual default
+                                #   branch (origin/HEAD, fallback current) — no hardcoded 'main'.
+                                #   --project defaults to the git root of cwd (monorepo-safe:
+                                #   many sessions can target one repo from different branches).
+                                #   config worktree.naming can template the NEW branch name.
+agentwire worktree name -b develop  # from specific base branch
+agentwire worktree name -c      # from repo's current branch
+agentwire worktree name -e      # checkout existing branch (no new branch)
+agentwire worktree name --ref v2.0  # detached at tag/commit
+agentwire worktree --list       # list this repo's worktree sessions (registry); --all = every repo
+agentwire worktree --remove name  # kill session + remove worktree + unregister (cleanup/recovery)
+agentwire worktree --prune      # drop registry entries whose worktree is gone + git worktree prune
+agentwire fork -s name          # fork session into new worktree
+agentwire fork -s name -t project/branch --commit abc123  # fork from specific commit
+
+# Pane commands (worker PANES inside the current session — NOT worktree
+# sessions; for parallel autonomous work use `agentwire worktree` above)
+agentwire spawn --roles worker  # spawn worker pane
+agentwire spawn --branch name   # worker pane on an isolated worktree (still a pane)
+agentwire send --pane 1 "task"  # send to pane
+agentwire output --pane 1       # read pane output
+agentwire kill --pane 1         # kill pane
+agentwire jump --pane 1         # focus pane
+agentwire split -s name         # add terminal pane(s)
+agentwire detach -s name        # move pane to its own session
+agentwire resize -s name        # resize window to fit largest client
+
+# Boot everything
+agentwire up                    # boot all services (portal, TTS, STT, scheduler,
+                                #   custom) then start/attach the dev session
+agentwire up --no-tts --no-stt  # skip optional voice services
+agentwire up --dev              # run portal from source (uv run)
+
+# Portal management
+agentwire portal start          # start in tmux
+agentwire portal stop           # stop portal
+agentwire portal restart        # stop + start
+agentwire portal status         # check health
+agentwire portal token          # print the auth token (devices enter it once)
+agentwire portal token --rotate # generate a new token (re-enter on devices)
+
+# Scratch pad (shared notes — portal drawer Alt+N; file: ~/.agentwire/scratchpad.json)
+agentwire scratchpad list       # list notes (newest first)
+agentwire scratchpad add "text" --source mysession  # add a note (drawer refreshes live)
+agentwire scratchpad remove <id> # delete a note
+agentwire scratchpad clear      # delete all notes
+
+# Custom services (registered long-running sessions — services.custom in config;
+# autostart on portal launch, health-checked + restarted by the portal watchdog)
+agentwire services list         # registry: autostart/restart/healthcheck per service
+agentwire services status       # run healthchecks now (exit 1 if something's down)
+agentwire services status name  # one service
+agentwire services up <name>    # start (also clears 'down' state)
+agentwire services up --all     # start all autostart services (skips downed)
+agentwire services down <name>  # stop AND keep stopped (watchdog won't respawn)
+
+# TTS/STT servers
+agentwire tts start|stop|status # TTS server management
+agentwire stt start|stop|status # STT server management (host shim on :8101)
+agentwire stt start             # engine from stt.engine (auto|moonshine|whisper); moonshine = fast CPU
+agentwire stt start --backend moonshine --model moonshine/base --port 8101  # ad-hoc overrides
+
+# Voice
+agentwire say "text"            # speak (auto-routes to browser or local)
+agentwire say -s name "text"    # speak to specific session
+agentwire notify-parent "text"   # notify parent session (worker→orchestrator)
+agentwire notify-parent --to name "text" # notify specific session
+agentwire notify-parent --raw --to name "text"  # verbatim, no [NOTIFY ...] prefix
+                                # (delivery is safety-gated: refuses targets showing a
+                                #  live dialog / bare shells / parked sessions, verified paste)
+
+# Prompt routing (interactive prompts → parent session; see wiki sessions/prompt-routing.md)
+agentwire prompts status        # pending prompt markers
+agentwire prompts tick          # run one sweep now (watchdog does this every 60s)
+agentwire prompts answer -s name --pane 0 --expect <hash> 2  # guarded answer:
+                                #   re-detects + hash-compares before sending keys —
+                                #   NEVER answer dialogs with raw send-keys
+agentwire prompts clear -s name --pane 1  # drop a marker
+
+# Polite messaging (non-interrupting agent-to-agent inbox; see wiki sessions/messaging.md)
+agentwire msg send --to name "text"          # queue a message (delivers when their box is clear)
+agentwire msg send --to name --kind done "PR #312 drafted"  # kinds: note|done|request|escalation
+agentwire msg send --to @all "team update"   # broadcast to live agent sessions except sender
+agentwire msg inbox -s name                  # peek pending (does not drain)
+agentwire msg dead -s name                   # list dropped (dead-lettered) msgs + reason/timestamp
+agentwire msg flush -s name                  # attempt a drain now (still gated on empty box + safe target)
+                                # `msg` NEVER clobbers a human's draft — unlike `send`, which
+                                # pastes + Enter immediately. Use `send` only to forcibly drive a session now.
+
+agentwire listen start|stop|cancel  # host voice recording (needs stt.backend: custom + the :8101 shim)
+agentwire listen stop -s name   # transcribe + send to a tmux session (default)
+agentwire listen stop --type    # transcribe + type at cursor (Hammerspoon paste)
+agentwire listen stop --stdout  # transcribe + print raw transcript to stdout, no paste/send
+                                #   (scripting hook — Hammerspoon etc. capture $())
+
+# Voice cloning
+agentwire voiceclone start      # start recording voice sample
+agentwire voiceclone stop name  # stop and save as voice clone
+agentwire voiceclone list       # list available voices
+agentwire voiceclone delete name # delete a voice clone
+
+# Artifact windows (agent visual canvas)
+agentwire open <url> --title "T"  # open URL or local file as artifact window
+agentwire open dashboard.html     # open from ~/.agentwire/artifacts/
+
+# Channels (outbound notification integrations — email + quo)
+agentwire channels list         # list all registered channels
+agentwire channels list --json  # JSON output
+
+# Email (send-only channel)
+agentwire email --to addr --subject "Subject" --body "Body"
+agentwire email --body "msg" # uses default_to from config
+agentwire email --attach file.pdf --body "See attached"
+
+# Quo SMS (send-only channel, no deps)
+agentwire quo --body "msg" --to "+1234567890"
+
+# Machine management
+agentwire machine list
+agentwire machine add <id> --host <host> --user <user>
+agentwire machine remove <id>
+
+# SSH tunnels (for remote services)
+agentwire tunnels up            # create all required tunnels
+agentwire tunnels down          # tear down all tunnels
+agentwire tunnels status        # show tunnel health
+agentwire tunnels check         # verify tunnels are working
+
+# Lock management (for scheduled tasks)
+agentwire lock list             # list all locks
+agentwire lock clean            # remove stale locks
+agentwire lock remove <session> # force-remove a specific lock
+
+# Project discovery
+agentwire projects list         # discover projects from projects_dir
+agentwire projects list --json  # JSON output for scripting
+agentwire projects create name              # mkdir + minimal .agentwire.yml (Codex-bypass)
+                                            # (in git repos, .agentwire.yml is auto-added to
+                                            #  .gitignore — personal config, keep it untracked)
+agentwire projects create name --git-init   # also run `git init`
+agentwire projects create name --from URL   # git clone URL instead of mkdir
+
+# Session history
+agentwire history list          # list conversation history
+agentwire history show <id>     # show session details
+agentwire history resume <id>   # resume session (always forks)
+
+# Shareable conversation handoffs (issue #157)
+agentwire handoff init [--title hint]      # create bundle dir + pre-filled ai-handoff.md template
+agentwire handoff render <bundle-dir>      # render show-the-story.html from ai-handoff.md
+agentwire handoff list                     # list past bundles
+# Inside a Codex session, prefer the /handoff slash command — it walks the
+# agent through filling the template using full conversation context (free, no
+# fresh LLM call). Outputs land in ~/.agentwire/artifacts/handoff-<slug>/.
+
+# Roles management
+agentwire roles list            # list available roles
+agentwire roles show <name>     # show role details
+
+# Scheduled workloads
+agentwire ensure -s name --task task  # run named task reliably
+agentwire task list [session]         # list tasks for session/project
+agentwire task show session/task      # show task definition
+agentwire task validate session/task  # validate task syntax
+
+# URL fetch (helper usable from any session, including pi)
+agentwire fetch <url>                 # fetch a page via Jina Reader (markdown, JS-rendered)
+agentwire fetch <url> --limit 4000    # cap chars (default 8000, 0 = no limit)
+
+# Safety & diagnostics
+agentwire safety check "cmd"    # test if command would be blocked
+agentwire safety status         # show pattern counts and recent blocks
+agentwire safety logs           # query audit logs
+agentwire safety install        # install damage control hooks
+agentwire hooks install         # install permission hook (Codex only)
+agentwire hooks uninstall       # remove permission hook (Codex only)
+agentwire hooks status          # check hook installation status
+agentwire network status        # complete network health check
+agentwire doctor                # auto-diagnose and fix issues
+agentwire doctor --voice        # only the push-to-talk path: mic, STT shim, portal/tunnel, tmux+PTT (pass/fail + fix)
+
+# Notifications
+agentwire notify event          # notify portal of state changes (session/pane events)
+
+# MCP Server
+agentwire mcp                   # expose agentwire as MCP server
+
+# Scheduler
+agentwire scheduler start|serve|stop|status # manage scheduler daemon
+agentwire scheduler board                   # show task board with overdue scores
+agentwire scheduler live                    # show live scheduler state
+agentwire scheduler events                  # show recent scheduler events
+agentwire scheduler history                 # show recent run history
+agentwire scheduler run task                # force-run a task now
+agentwire scheduler enable|disable task     # enable/disable a task
+agentwire scheduler report [--since 8h] [--artifact]  # generate morning report HTML
+agentwire scheduler dashboard               # open scheduler dashboard
+
+# Usage-limit recovery (deterministic watchdog, see docs/wiki/usage-limit-recovery.md)
+agentwire limits tick           # one watchdog pass: sweep panes, resume what's due
+agentwire limits status         # show sessions parked on usage limits
+agentwire limits resume -s name [--force]  # manually resume a parked session now
+agentwire limits install        # install + load the launchd watchdog (60s tick)
+agentwire limits uninstall      # unload + remove the watchdog
+
+# Setup & Development
+agentwire init                  # interactive setup wizard
+agentwire generate-certs        # generate SSL certificates
+agentwire up                    # boot all services + dev session (see "Boot everything")
+agentwire dev                   # start/attach to dev session ONLY (no services)
+agentwire rebuild               # clear uv cache and reinstall
+agentwire uninstall             # uninstall the tool
+```
+
+`agentwire dev` only spawns the `agentwire` agent session — it does NOT start
+the portal or any service. Use `agentwire up` after a reboot to bring up the
+full stack. `up` brings up portal → TTS → STT → autostart custom services, then
+runs `dev`; the scheduler rides along via the portal's `scheduler.autostart`.
+TTS is skipped for `none`/`runpod` backends; STT is skipped without `stt.url`.
+
+Session formats: `name`, `project/branch` (worktree), `name@machine` (remote)
+Pane targeting: `--pane N` auto-detects session from `$TMUX_PANE`
+
+For CLI details: `agentwire --help` or `agentwire <cmd> --help`

agentwire_dev-1.43.0/.agents/skills/agentwire-config/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: agentwire-config
+description: Reference for `~/.agentwire/config.yaml` — main config structure including server/portal/SSL, projects, TTS/STT, agent, dev, services, executables, pi (binary/system_prompt/extra_env/providers), uploads/artifacts/wiki, channels (email + quo, outbound-only), scheduler, worktree, session defaults. Use when editing or debugging agentwire config, setting up TTS/STT backends, configuring pi providers, or explaining config fields to the user.
+---
+
+# AgentWire Config (`~/.agentwire/config.yaml`)
+
+## Layout of `~/.agentwire/`
+
+| File | Purpose |
+|------|---------|
+| `config.yaml` | Main config (see structure below) |
+| `machines.json` | Remote machines registry |
+| `scripts/` | Machine-specific helper scripts (TTS management, startup, etc.) |
+| `voices/` | Custom TTS voice samples |
+| `uploads/` | Uploaded images for cross-machine sharing |
+| `artifacts/` | Agent-generated HTML for artifact windows |
+| `wiki/` | LLM-maintained knowledge base (Karpathy LLM Wiki pattern) |
+| `logs/` | Audit logs for damage-control |
+
+Per-session config (type, roles, voice) lives in `.agentwire.yml` in each project directory (see `agentwire-project-config` skill).
+
+## Machine Scripts (`~/.agentwire/scripts/`)
+
+Each machine has a `~/.agentwire/scripts/` directory for machine-specific helper scripts (TTS management, startup hooks, service wrappers, etc.). This is the standard location — agents should look here first and put new scripts here.
+
+Scripts in `~/bin/` should symlink to `~/.agentwire/scripts/` so they're callable from PATH but the source of truth is in one place.
+
+These scripts are **not** managed by agentwire — they're local to each machine and not version controlled. They exist because different machines have different roles (GPU server runs TTS, Mac runs the portal, etc.) and need different glue scripts.
+
+## config.yaml Structure
+
+```yaml
+server:
+  host: "127.0.0.1"  # default; "0.0.0.0" allows LAN/phone access and requires the auth token (see SECURITY.md)
+  port: 8765
+  activity_threshold_seconds: 3  # Seconds before session considered idle
+  ssl:
+    cert: "~/.agentwire/cert.pem"
+    key: "~/.agentwire/key.pem"
+  # Auth token: unset = use ~/.agentwire/portal.token (auto-generated on first
+  # non-loopback start; print/rotate with `agentwire portal token [--rotate]`).
+  # Set a string to override the file; "" disables auth (loopback binds only —
+  # the portal refuses to start on 0.0.0.0 with auth disabled).
+  # auth_token: ""
+  # Extra browser origins allowed on state-changing requests (exact
+  # scheme://host[:port]). The portal's own origin and localhost always pass.
+  # Needed when fronting with Cloudflare Tunnel:
+  allowed_origins: []  # e.g. ["https://portal.example.com"]
+
+projects:
+  dir: "~/projects"
+  worktrees:
+    enabled: true
+    suffix: "-worktrees"
+    auto_create_branch: true
+    copy_files: [".env", ".agentwire.yml"]   # gitignored files seeded into each new worktree
+                           # (git worktree add only checks out tracked files,
+                           #  so .env/secrets/local config don't carry over —
+                           #  add ".env.local", ".envrc", etc. as needed).
+                           # Keep .agentwire.yml gitignored: a TRACKED copy means
+                           # worktree runs use the committed version (HEAD) and
+                           # silently ignore live edits — see agentwire-project-config skill.
+
+tts:
+  backend: "default"  # tier: default (in-process Kokoro, zero setup — ~200MB model
+                      # auto-downloads on first portal start; speechSynthesis covers
+                      # the wait) | custom (self-hosted shim at url)
+  url: "http://localhost:8100"  # custom tier only — shim endpoint
+  default_voice: "dotdev"
+  voices_dir: "~/.agentwire/voices"  # Custom voice samples for cloning
+  instructions: ""  # free-text prompt passed through to the shim
+  options:  # opaque JSON passed to the shim; the bundled shim reads:
+    backend: kokoro  # engine: kokoro | chatterbox | chatterbox-streaming | qwen-base-0.6b | qwen-base-1.7b | qwen-custom | qwen-design | zonos-transformer | zonos-hybrid
+  exaggeration: 0.5  # Voice expressiveness (0-1, Chatterbox)
+  cfg_weight: 0.5  # CFG weight (0-1, Chatterbox)
+  timeout: 60
+
+stt:
+  backend: "default"  # TIER (where transcription happens): default (portal-owned
+                      # in-process Moonshine — bundled, auto-downloads on first boot,
+                      # no setup; falls back to browser SpeechRecognition while it
+                      # warms up or on py3.14+) | cloud (portal → hosted OpenAI-
+                      # compatible transcription API, no shim daemon) | custom
+                      # (self-hosted shim at url)
+  engine: "auto"      # ENGINE (which model the self-hosted shim loads): auto | moonshine |
+                      # whisper. Orthogonal to backend — used only by `agentwire stt start/serve`.
+                      # `{backend: custom, engine: whisper}` = boot shim AND run faster-whisper.
+  moonshine_model: "moonshine/base"  # moonshine engine only — ONNX model id (moonshine/tiny | moonshine/base)
+  model: "base"       # whisper engine only — faster-whisper/openai-whisper model (tiny → large-v3)
+  url: "http://localhost:8101"  # custom tier only — shim endpoint (also the `agentwire stt` port)
+  cloud:  # cloud tier only — all fields optional, defaults shown
+    base_url: "https://api.openai.com/v1"  # any OpenAI-compatible endpoint (Groq, Mistral, speaches, ...)
+    model: "gpt-4o-mini-transcribe"
+    api_key_env: "OPENAI_API_KEY"  # NAME of the env var holding the key — the key itself
+                                   # never lives in config and never reaches the browser;
+                                   # portal refuses to start if the var is unset
+    language: ""  # optional ISO-639-1 hint
+  timeout: 30
+  silence_prepend_ms: 0  # prepend silence if your backend clips the first syllable
+  instructions: ""  # free-text hint passed through to the shim
+  options: {}  # opaque JSON passed to the shim (language hints, vocab biasing, ...)
+  corrections: {}  # post-transcription find/replace, e.g. {"agent wire": "agentwire"}
+
+agent:
+  command: "Codex --dangerously-skip-permissions"
+
+dev:
+  source_dir: "~/projects/agentwire-dev"  # agentwire source for TTS/STT venv
+
+services:  # Where services run (for multi-machine setups)
+  portal:
+    machine: null  # null = local
+    port: 8765
+    session_name: "agentwire-portal"  # tmux session name
+  tts:
+    machine: "gpu-server"  # or null for local
+    port: 8100
+    session_name: "agentwire-tts"
+  stt:
+    session_name: "agentwire-stt"
+  custom:  # User-defined service sessions — autostart on portal launch AND
+           #   `agentwire up`, health-checked by the portal watchdog, shown in
+           #   the portal's Services column. Manage with `agentwire services ...`.
+           #   The notifications bridge is a built-in registry entry (override
+           #   by defining a service with its name).
+    - name: "agent-brain"          # tmux session name (required)
+      project: "~/projects/brain"  # project dir; defaults to dev source dir
+      autostart: true              # boot on portal launch / `agentwire up` (default true)
+      roles: "brain"               # optional; overrides project .agentwire.yml
+      type: "Codex-bypass"        # optional; session type override
+      restart: on-failure          # never | on-failure | always (watchdog respawn
+                                   #   with 30s..10m exponential backoff; default on-failure;
+                                   #   `agentwire services down` always sticks)
+      healthcheck:                 # optional; defaults to tmux_session/60s
+        kind: tmux_session         # tmux_session | http | command
+        url: "http://..."          # for http (2xx = healthy)
+        command: "curl -sf ..."    # for command (exit 0 = healthy)
+        interval: 60               # seconds between watchdog checks
+    - "simple-service"             # string shorthand = name only, all defaults
+
+executables:  # Override executable paths (optional, auto-detected by default)
+  ffmpeg: "/opt/homebrew/bin/ffmpeg"
+  whisperkit-cli: "/opt/homebrew/bin/whisperkit-cli"
+  hs: "/opt/homebrew/bin/hs"
+  agentwire: "~/.local/bin/agentwire"
+
+pi:  # Pi coding agent — drives all `pi-<provider>` session types. See `agentwire-pi` skill.
+  binary: "pi"  # path override if pi isn't on PATH (e.g., nvm-installed)
+
+  # Appended via --append-system-prompt to every non-restricted pi-* session.
+  # Use to teach pi about local helpers — agentwire fetch, etc.
+  system_prompt: |
+    ## Fetching URLs
+    Use `agentwire fetch <url>` to fetch a page as clean markdown (Jina Reader).
+
+  # Env vars injected into every pi-* session, in addition to the provider key.
+  # Values are stored in plaintext here — non-secrets only. Secrets belong in
+  # ~/.agentwire/.env (docs/wiki/security/secrets.md).
+  extra_env:
+    MY_SERVICE_URL: "https://internal.example.com"
+
+  # Per-provider config. Session type `pi-<name>` resolves the provider here.
+  # Adding a new provider is config-only — no code changes needed. For non-built-in
+  # providers (e.g. DeepSeek), also register them in `~/.pi/agent/models.json`.
+  # env_var is the NAME of the env var holding the key — the key itself lives
+  # in ~/.agentwire/.env (e.g. ZAI_API_KEY=...), never here.
+  providers:
+    zai:
+      env_var: ZAI_API_KEY
+      default_model: glm-5.1
+    deepseek:
+      env_var: DEEPSEEK_API_KEY
+      default_model: deepseek-chat
+
+uploads:
+  dir: "~/.agentwire/uploads"
+  max_size_mb: 10
+  cleanup_days: 7
+
+artifacts:
+  dir: "~/.agentwire/artifacts"
+  max_size_mb: 10
+
+wiki:
+  dir: "~/.agentwire/wiki"           # Wiki vault location
+
+portal:
+  url: "https://localhost:8765"
+
+channels:  # Outbound-only notifications. Only email + quo ship.
+  # Keys are env-only: RESEND_API_KEY / QUO_API_KEY in ~/.agentwire/.env
+  # (docs/wiki/security/secrets.md) — never in config.yaml.
+  email:
+    from_address: "Echo <echo@yourdomain.com>"
+    default_to: "user@example.com"
+    banner_image_url: "https://yourdomain.com/images/banner.png"
+    echo_image_url: "https://yourdomain.com/images/echo.png"
+    echo_small_url: "https://yourdomain.com/images/echo-small.png"
+    logo_image_url: "https://yourdomain.com/images/logo.png"
+  quo:
+    from_number: "+1234567890"  # E.164 or phone number ID (PNxxx)
+    default_to: "+0987654321"
+
+scheduler:
+  autostart: true        # Start the scheduler daemon when the portal boots (default: true)
+  dispatch_cooldown: 60  # Seconds between task dispatches (default: 60)
+
+usage_limit:             # Usage-limit recovery watchdog (docs/wiki/usage-limit-recovery.md)
+  enabled: true          # Master switch for dialog detection/parking (default: true)
+  exclude_sessions: []   # Session names never auto-parked (gates NEW parks only)
+
+worktree:                         # `agentwire worktree <name>` orchestration (WorktreeConfig).
+                                  # Distinct from projects.worktrees above (the legacy
+                                  # project/branch layout). `quicktask:` is a legacy alias for
+                                  # this key — prefer `worktree:`.
+  worktree_dir: ~/worktrees       # Where worktrees are created (one dir per session)
+  default_base: develop           # Base branch new worktrees fork from. OMIT to derive from
+                                  # the repo's actual default branch (origin/HEAD, fallback to
+                                  # current branch) — no hardcoded 'main'. --base always wins.
+  default_project: ~/projects/my-repo  # Repo used when --project is omitted AND cwd isn't in a
+                                  # git repo. Otherwise --project / the git root of cwd is used.
+  naming: "{user}/{slug}"         # Optional branch-name template for NEW branches. Placeholders:
+                                  # {name} (verbatim), {slug} (slugified), {user} (OS login).
+                                  # Omit → branch == name verbatim. Only the git branch is
+                                  # templated; the tmux session name stays {project}-{name}.
+
+session:
+  # No global default-role: a session's etiquette is derived from its spawn
+  # verb (new → orchestrator, worktree → worktree-session, spawn → worker),
+  # then any --roles / .agentwire.yml roles: replace it. See resolve_roles.
+  inject_soul: true          # Append the bundled 'soul' personality role to every human-facing
+                             # session (appended last for recency weight). Headless roles
+                             # (worker, task-runner, notifications) and soul/soul-* sessions
+                             # are excluded automatically; per-session opt-out: --no-soul on new/dev
+```

agentwire_dev-1.43.0/.agents/skills/agentwire-desktop-ui/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: agentwire-desktop-ui
+description: Portal desktop UI patterns — left sidebar (click-toggle tab handle, accordion sections, session grouping into Sessions/Services via explicit allowlist, keyboard nav), session window modes (Monitor `<pre>` vs Terminal xterm.js — Monitor MUST NOT use xterm), artifact windows (sandboxed iframes from `~/.agentwire/artifacts/`), window collage (preview overlay — NEVER mutate real WinBox windows). Use when editing portal static files (`static/js/sidebar/*`, `desktop.js`, `desktop.css`), changing window behavior, or adding sidebar sections.
+---
+
+# Portal Desktop UI Patterns
+
+## Left Sidebar (click-toggle tab handle)
+
+The portal uses a left sidebar with a floating tab handle instead of hover hotzone. A small tab (›) peeks from the left edge — click to slide sidebar open, click again to close. Click outside or press Escape to dismiss. Pin to keep visible (reflows desktop area).
+
+**Structure:**
+- **Tab handle**: floating 20×40px button on left edge, rides sidebar when open, chevron flips direction
+- **Header**: connection status dot, session count, clock, pin toggle
+- **Open Windows section**: lists currently-open windows (drag to reorder, click to focus, × to close). Persisted in `localStorage['taskbar-state']` — restores on refresh.
+- **Accordion sections**: Sessions, Services, Machines, Projects, Artifacts, Scheduler, Safety, Config. Click header to expand/collapse. Data fetched on first expand.
+- **Footer**: global PTT button, voice indicator
+
+**Session grouping:** Sessions are split into two accordion sections based on the name:
+- **Services**: infrastructure sessions. The built-in allowlist in `service-classification.js` (`agentwire-portal`, `agentwire-tts`, `agentwire-stt`, `agentwire-scheduler`, `agentwire-notifications`) is merged at load time with config-defined custom services fetched from `/api/services/custom` (driven by `services.custom` in `config.yaml`). When the fetch resolves, `notifyListeners()` re-renders so flagged sessions hop into this column.
+- **Sessions**: everything else (working sessions, worktrees, remote sessions)
+
+Both share session data from `sessions-section.js` (single fetch, shared activity state, pub-sub via `onSessionsChanged`).
+
+**Keyboard:** Tab cycles forward through open windows, Shift+Tab cycles backward. Works inside terminals (captured on `window` in capture phase before xterm).
+
+**Files:** `static/js/sidebar.js` (shell + click-toggle), `static/js/sidebar/<name>-section.js` (per-section modules), `static/css/desktop.css` (sidebar-* classes).
+
+## Command Palette & Idea-First Capture
+
+`Cmd/Ctrl+K` opens the command palette (`static/js/command-palette.js`) **straight into the `new-idea` view** — Esc reaches the root menu (New idea / New session / New worktree / Open session / Window collage). The full-width 💡 **New idea** sidebar button (between header and sections) and the Projects section `+` route to the same view.
+
+**New-idea flow (issue #253):** idea textarea (Enter submits, Shift+Enter newline, 🎤 dictation via `voice/browser-stt.js`) → kebab-case project name derived client-side (`deriveProjectName`, stopword-stripped; stops auto-updating once the user edits it) → submit POSTs `/api/projects/create` then `/api/create` with `first_message` → window opens immediately while the idea is delivered to the booting agent in the background (server calls `agentwire send --wait-ready`; failure posts a toast). There is no name-first modal anymore — `new-project-modal.js` was deleted.
+
+## Session Window Modes
+
+| Mode | Element | Use Case |
+|------|---------|----------|
+| **Monitor** | `<pre>` with ANSI-to-HTML | Read-only output viewing, polls `tmux capture-pane` |
+| **Terminal** | xterm.js | Interactive terminal, attaches via `tmux attach` |
+
+**Important:** Monitor mode must use a simple `<pre>` element, NOT xterm.js. xterm.js requires precise container dimensions for its fit addon to work correctly. Since monitor mode just displays captured text output, a `<pre>` element with `white-space: pre-wrap` and ANSI-to-HTML conversion is simpler and more reliable.
+
+**Per-session PTT** lives in the WinBox titlebar (next to the activity indicator), not as a floating button.
+
+## Window Collage (Mission Control)
+
+F3 or Alt/Option+` / `desktop_collage` MCP / command palette → grid of live previews of every open window; click a tile to focus, Esc to exit.
+
+**The one rule: tiles are overlay-local previews — NEVER mutate the real WinBox windows.** Session tiles stream pane content over a second monitor WS (`/ws/{sessionId}`, rendered via shared `utils/ansi.js`); artifact tiles are cloned iframes. Real windows are never moved/resized/transformed/un-minimized, so exit has nothing to restore.
+
+Why this is load-bearing (each broke a previous implementation — full autopsy in `docs/wiki/internals/window-collage.md`):
+- Faking `winbox.min` corrupts WinBox's internal min-stack → later minimizes re-lay windows out as 250×35px bars, with duplicate entries compounding per cycle.
+- WinBox animates geometry over 300ms → `getBoundingClientRect` right after a write returns mid-transition garbage.
+- Resizing a terminal window fires ResizeObserver → `fitAddon.fit()` + PTY resize per frame → resizes the real tmux session and corrupts the xterm WebGL layer (transparent windows).
+- `registerWindow`/`setActiveWindow` auto-minimize all others (single-window mode) → any window event mid-overlay fights manual layouts.
+
+**Z-index landscape:** WinBox windows (inline, grows from 10) < collage overlay (1400) < toasts (1500) < modals (2000) < command palette (3000) < sidebar (9001) < tile drag overlay (99999).
+
+## Artifact Windows
+
+Agents can display HTML content in sandboxed iframe windows on the portal desktop.
+
+**Agent workflow (MCP):**
+```python
+# Write HTML and open in one step
+desktop_write_artifact(filename="dashboard.html", html_content="<h1>Hello</h1>", title="Dashboard")
+
+# Or open an existing file or external URL
+desktop_open_artifact(url="dashboard.html", title="Dashboard")
+desktop_open_artifact(url="https://example.com", title="External")
+```
+
+**Files served from:** `~/.agentwire/artifacts/` via `/artifacts/` route.
+
+**Sandboxing:** Local files get `allow-scripts allow-same-origin`. External URLs get `allow-scripts allow-forms allow-popups` (no same-origin).