crewly 1.20.193 → 1.20.195

package/config/skills/agent/core/experiment-card/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: Experiment Card
+description: Attach an experiment to an optimisation ticket — hypothesis ("change X → metric Y from a to b"), a Search Console or GA4 metric (via seo-ops), an observation window (default 14 days). Crewly captures the baseline when the change ships, measures it when the window ends, labels it worked / didn't / inconclusive, resolves your prediction, writes the wiki experiment log and tells the owner.
+version: 1.1.0
+category: analysis
+skillType: claude-skill
+assignableRoles:
+  - marketing
+  - content-strategist
+  - generalist
+  - developer
+  - fullstack-dev
+  - product-manager
+  - team-leader
+  - orchestrator
+triggers:
+  - experiment
+  - measure the impact
+  - did it work
+  - a/b
+  - hypothesis
+tags:
+  - experiments
+  - seo
+  - analytics
+  - outcomes
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 180000
+---
+
+# Experiment Card
+
+A ticket that is meant to *move a number* (rewrite a title, add FAQ schema,
+shorten the inquiry form) should carry an experiment, so we learn whether it
+worked instead of assuming it did. Create the card **before** the change ships;
+Crewly does the rest:
+
+1. **Ship** — when the linked ticket reaches `done` (or you run `ship`), the
+   windows are fixed and the **baseline** is fetched right away: the
+   `windowDays` days that had settled before the ship day. The ship time is
+   the ticket's move to `done` in its log. If you link a ticket that is
+   already done and its log has no done time, `create` asks for
+   `--shipped-at` (when the change went live).
+2. **Wait** — the observation window is the `windowDays` days after the ship
+   day. Nothing to do; don't re-check it by hand.
+3. **Measure** — once those days have settled (Search Console +3 days, GA4
+   +2), Crewly fetches the result and labels it:
+   - **worked** — a real change in the hypothesis's direction (|z| ≥ 1.96);
+   - **didn't** — enough data, but no real change (or the wrong way);
+   - **inconclusive** — too little data (e.g. fewer than 10 form submissions
+     across both windows, fewer than 30 clicks/sessions).
+4. **Learn** — your prediction (recorded at ship with `--confidence`) is
+   resolved, the result is appended to the wiki experiment log
+   (`llm-curated/experiments/log.md`), the owner gets it, and a project
+   ticket gets a log line. `show` has the whole timeline (the run's trace).
+
+## Create
+
+The metric comes from the seo-ops skill, so you need a seo-ops site config
+(`--config`, absolute path; it names the GSC property / GA4 property and the
+service-account credentials).
+
+```bash
+# Search Console: organic clicks to one page, on a project ticket
+bash execute.sh create --hypothesis "FAQ schema on the H-1B guide → organic clicks from 120 to 160" \
+  --source gsc --measure clicks --page https://visa.careerengine.us/h1b-guide \
+  --from 120 --to 160 --config /abs/path/ce.seo-ops.json --project ce-site --ticket CE-31 --confidence 0.6
+
+# GA4: inquiry-form submissions (all channels), on a harness ticket
+bash execute.sh create --hypothesis "3-field inquiry form → submissions from 8 to 14 per two weeks" \
+  --source ga4 --measure events --event generate_lead --channel all \
+  --config /abs/path/ce.seo-ops.json --tkt TKT-212
+```
+
+- gsc measures: `clicks`, `impressions`, `ctr`, `position` (lower is better;
+  direction defaults to `decrease`). Filters: `--page URL`, `--query Q`,
+  `--page-match` / `--query-match exact|contains`.
+- ga4 measures: `sessions` (Organic Search unless `--channel all`),
+  `events` (`--event NAME`) and `conversions` (GA4 key events; `--event NAME`
+  for one of them). Filter: `--page /landing-path` (a full URL is reduced to
+  its path; the query string is dropped).
+- `--window-days` 7–90, whole weeks preferred (default 14).
+- One experiment per change: two changes on the same page in one window
+  can't be told apart.
+
+## Follow it
+
+```bash
+bash execute.sh list --status running
+bash execute.sh show --id EXP-3          # baseline, result, verdict, timeline
+bash execute.sh ship --id EXP-3          # only if it has no ticket, or shipped before the ticket closed
+bash execute.sh measure --id EXP-3       # only after dueAt; normally automatic
+bash execute.sh cancel --id EXP-3 --reason "change reverted"
+```
+
+If a fetch keeps failing (credentials, property access) the owner is told
+once with the error; after 6 failures in a row it retries once a day.

package/config/skills/agent/core/experiment-card/execute.sh

@@ -0,0 +1,149 @@
+#!/bin/bash
+# =============================================================================
+# experiment-card — attach an experiment to an optimisation ticket; Crewly
+# captures the baseline when it ships and measures it when the window ends.
+#
+# Backed by /api/experiments (specs/experiment-cards.md, issue #986).
+#
+# Usage:
+#   bash execute.sh create --hypothesis "…" --source gsc|ga4 --measure M --config /abs/seo-ops.config.json
+#                          [--page P] [--page-match exact|contains] [--query Q] [--query-match exact|contains]
+#                          [--event NAME] [--channel all] [--label "…"] [--title "…"]
+#                          [--from A] [--to B] [--direction increase|decrease] [--window-days 14]
+#                          [--confidence 0.6] [--project P --ticket ID | --tkt TKT-12] [--shipped-at ISO]
+#   bash execute.sh ship    --id EXP-3 [--shipped-at ISO]
+#   bash execute.sh show    --id EXP-3
+#   bash execute.sh list    [--status planned|running|done|cancelled] [--ticket ID]
+#   bash execute.sh measure --id EXP-3
+#   bash execute.sh cancel  --id EXP-3 [--reason "…"]
+#   bash execute.sh '{"action":"create","hypothesis":"…","metric":{…},"ticket":{…}}'
+# =============================================================================
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../../_common/lib.sh"
+
+print_usage() {
+  cat <<'EOF_USAGE'
+Usage:
+  bash execute.sh create --hypothesis "change X → metric Y from a to b" --source gsc|ga4 --measure M
+                         --config /abs/path/seo-ops.config.json [filters] [--from A] [--to B]
+                         [--window-days 14] [--confidence 0.6] [--project P --ticket ID | --tkt TKT-12]
+                         [--shipped-at ISO]   (required when the ticket is already done but has no recorded done time)
+      gsc measures: clicks impressions ctr position   (filters: --page URL --query Q, --page-match/--query-match exact|contains)
+      ga4 measures: sessions events conversions       (filters: --page /path, --event NAME, --channel all)
+  bash execute.sh ship    --id EXP-3 [--shipped-at ISO]   The change is live (automatic when the ticket is done)
+  bash execute.sh show    --id EXP-3                      Card, baseline, result and timeline
+  bash execute.sh list    [--status S] [--ticket ID]
+  bash execute.sh measure --id EXP-3                      Measure now (only once it is due)
+  bash execute.sh cancel  --id EXP-3 [--reason "…"]
+EOF_USAGE
+}
+
+ACTION=""; ID=""; JSON_BODY=""
+HYPOTHESIS=""; TITLE=""; SOURCE=""; MEASURE=""; CONFIG=""; PAGE=""; PAGE_MATCH=""; QUERY=""; QUERY_MATCH=""
+EVENT=""; CHANNEL=""; LABEL=""; FROM=""; TO=""; DIRECTION=""; WINDOW=""; CONFIDENCE=""; PROJECT=""; TICKET=""; TKT=""
+SHIPPED_AT=""; STATUS=""; REASON=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  J=$(read_json_input "$1"); shift
+  ACTION=$(printf '%s' "$J" | jq -r '.action // empty')
+  ID=$(printf '%s' "$J" | jq -r '.id // empty')
+  SHIPPED_AT=$(printf '%s' "$J" | jq -r '.shippedAt // empty')
+  STATUS=$(printf '%s' "$J" | jq -r '.status // empty')
+  REASON=$(printf '%s' "$J" | jq -r '.reason // empty')
+  TICKET=$(printf '%s' "$J" | jq -r 'if (.ticket|type) == "string" then .ticket else empty end')
+  JSON_BODY=$(printf '%s' "$J" | jq -c 'del(.action, .id, .status, .reason)')
+fi
+if [[ -z "$ACTION" && $# -gt 0 && ${1:0:1} != '-' ]]; then ACTION="$1"; shift; fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --id)            [ $# -ge 2 ] || error_exit "--id requires a value"; ID="$2"; shift 2 ;;
+    --hypothesis)    [ $# -ge 2 ] || error_exit "--hypothesis requires a value"; HYPOTHESIS="$2"; shift 2 ;;
+    --title)         [ $# -ge 2 ] || error_exit "--title requires a value"; TITLE="$2"; shift 2 ;;
+    --source)        [ $# -ge 2 ] || error_exit "--source requires a value"; SOURCE="$2"; shift 2 ;;
+    --measure)       [ $# -ge 2 ] || error_exit "--measure requires a value"; MEASURE="$2"; shift 2 ;;
+    --config)        [ $# -ge 2 ] || error_exit "--config requires a value"; CONFIG="$2"; shift 2 ;;
+    --page)          [ $# -ge 2 ] || error_exit "--page requires a value"; PAGE="$2"; shift 2 ;;
+    --page-match)    [ $# -ge 2 ] || error_exit "--page-match requires a value"; PAGE_MATCH="$2"; shift 2 ;;
+    --query)         [ $# -ge 2 ] || error_exit "--query requires a value"; QUERY="$2"; shift 2 ;;
+    --query-match)   [ $# -ge 2 ] || error_exit "--query-match requires a value"; QUERY_MATCH="$2"; shift 2 ;;
+    --event)         [ $# -ge 2 ] || error_exit "--event requires a value"; EVENT="$2"; shift 2 ;;
+    --channel)       [ $# -ge 2 ] || error_exit "--channel requires a value"; CHANNEL="$2"; shift 2 ;;
+    --label)         [ $# -ge 2 ] || error_exit "--label requires a value"; LABEL="$2"; shift 2 ;;
+    --from)          [ $# -ge 2 ] || error_exit "--from requires a value"; FROM="$2"; shift 2 ;;
+    --to)            [ $# -ge 2 ] || error_exit "--to requires a value"; TO="$2"; shift 2 ;;
+    --direction)     [ $# -ge 2 ] || error_exit "--direction requires a value"; DIRECTION="$2"; shift 2 ;;
+    --window-days)   [ $# -ge 2 ] || error_exit "--window-days requires a value"; WINDOW="$2"; shift 2 ;;
+    --confidence)    [ $# -ge 2 ] || error_exit "--confidence requires a value"; CONFIDENCE="$2"; shift 2 ;;
+    --project|-p)    [ $# -ge 2 ] || error_exit "--project requires a value"; PROJECT="$2"; shift 2 ;;
+    --ticket)        [ $# -ge 2 ] || error_exit "--ticket requires a value"; TICKET="$2"; shift 2 ;;
+    --tkt)           [ $# -ge 2 ] || error_exit "--tkt requires a value"; TKT="$2"; shift 2 ;;
+    --shipped-at)    [ $# -ge 2 ] || error_exit "--shipped-at requires a value"; SHIPPED_AT="$2"; shift 2 ;;
+    --status)        [ $# -ge 2 ] || error_exit "--status requires a value"; STATUS="$2"; shift 2 ;;
+    --reason)        [ $# -ge 2 ] || error_exit "--reason requires a value"; REASON="$2"; shift 2 ;;
+    --help|-h)       print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1" ;;
+  esac
+done
+
+enc() { jq -rn --arg v "$1" '$v|@uri'; }
+CARD='{id, status, title, hypothesis, metric: (.metric | {source, measure, page, query, event, label} | with_entries(select(.value != null))), windowDays, ticket, shippedAt, dueAt, baseline: (.baseline.total // null), result: (.result.total // null), verdict, verdictReason, lastError, traceId}'
+
+case "$ACTION" in
+  create)
+    if [ -n "$JSON_BODY" ] && [ "$JSON_BODY" != "{}" ]; then
+      BODY="$JSON_BODY"
+    else
+      require_param "hypothesis (--hypothesis)" "$HYPOTHESIS"
+      require_param "source (--source gsc|ga4)" "$SOURCE"
+      require_param "measure (--measure)" "$MEASURE"
+      require_param "config (--config, the seo-ops site config)" "$CONFIG"
+      if [ -n "$TICKET" ] && [ -z "$PROJECT" ]; then error_exit "--ticket needs --project (or use --tkt TKT-n for a harness ticket)"; fi
+      BODY=$(jq -cn \
+        --arg h "$HYPOTHESIS" --arg t "$TITLE" --arg s "$SOURCE" --arg m "$MEASURE" --arg c "$CONFIG" \
+        --arg page "$PAGE" --arg pm "$PAGE_MATCH" --arg q "$QUERY" --arg qm "$QUERY_MATCH" --arg ev "$EVENT" \
+        --arg ch "$CHANNEL" --arg lb "$LABEL" --arg from "$FROM" --arg to "$TO" --arg dir "$DIRECTION" \
+        --arg win "$WINDOW" --arg conf "$CONFIDENCE" --arg proj "$PROJECT" --arg tic "$TICKET" --arg tkt "$TKT" '
+        def opt($k; $v): if $v == "" then {} else {($k): $v} end;
+        {hypothesis: $h}
+        + opt("title"; $t)
+        + {metric: ({source: $s, measure: $m, config: $c}
+            + opt("page"; $page) + opt("pageMatch"; $pm) + opt("query"; $q) + opt("queryMatch"; $qm)
+            + opt("event"; $ev) + opt("channel"; $ch) + opt("label"; $lb))}
+        + (if $from == "" and $to == "" then {} else {expected: (opt("from"; $from) + opt("to"; $to))} end)
+        + opt("direction"; $dir) + opt("windowDays"; $win) + opt("confidence"; $conf)
+        + (if $tkt != "" then {ticket: {kind: "harness", id: $tkt}}
+           elif $tic != "" then {ticket: {kind: "project", project: $proj, id: $tic}}
+           else {} end)')
+    fi
+    if [ -n "$SHIPPED_AT" ]; then BODY=$(printf '%s' "$BODY" | jq -c --arg at "$SHIPPED_AT" '. + {shippedAt: $at}'); fi
+    api_call POST "/experiments" "$BODY" | jq "{success, experiment: (.data | ${CARD})}"
+    ;;
+  ship)
+    require_param "id (--id EXP-n)" "$ID"
+    BODY=$(jq -cn --arg at "$SHIPPED_AT" 'if $at == "" then {} else {shippedAt: $at} end')
+    api_call POST "/experiments/$(enc "$ID")/ship" "$BODY" | jq "{success, experiment: (.data | ${CARD})}"
+    ;;
+  show)
+    require_param "id (--id EXP-n)" "$ID"
+    api_call GET "/experiments/$(enc "$ID")" | jq "{success, experiment: (.data | ${CARD} + {timeline})}"
+    ;;
+  list)
+    QS=""
+    [ -n "$STATUS" ] && QS="status=$(enc "$STATUS")"
+    [ -n "$TICKET" ] && QS="${QS:+$QS&}ticket=$(enc "$TICKET")"
+    api_call GET "/experiments${QS:+?$QS}" | jq "{success, experiments: [.data[] | ${CARD}]}"
+    ;;
+  measure)
+    require_param "id (--id EXP-n)" "$ID"
+    api_call POST "/experiments/$(enc "$ID")/measure" '{}' | jq "{success, experiment: (.data | ${CARD})}"
+    ;;
+  cancel)
+    require_param "id (--id EXP-n)" "$ID"
+    BODY=$(jq -cn --arg r "$REASON" 'if $r == "" then {} else {reason: $r} end')
+    api_call POST "/experiments/$(enc "$ID")/cancel" "$BODY" | jq "{success, experiment: (.data | ${CARD})}"
+    ;;
+  ""|help) print_usage; [ -n "$ACTION" ] || exit 1 ;;
+  *) error_exit "Unknown action: $ACTION (create, ship, show, list, measure, cancel)" ;;
+esac

package/config/skills/agent/core/experiment-card/execute.test.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# Tests for experiment-card — run with: bash execute.test.sh
+# A python HTTP stub plays the backend; asserts the calls and the output.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() {
+  local name="$1"; local got="$2"; local want="$3"
+  if [ "$got" = "$want" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $name"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+PORT=18853
+STUB_LOG="$(mktemp)"; export STUB_LOG; export STUB_PORT="$PORT"
+python3 -u <<'PY' >/dev/null 2>&1 &
+from http.server import BaseHTTPRequestHandler, HTTPServer
+import json, os
+LOG = os.environ['STUB_LOG']; PORT = int(os.environ['STUB_PORT'])
+E = {'id': 'EXP-1', 'traceId': 'exp:EXP-1', 'status': 'planned', 'title': 'T', 'hypothesis': 'H',
+     'metric': {'source': 'gsc', 'measure': 'clicks', 'config': '/c.json', 'page': 'https://x/'}, 'windowDays': 14,
+     'baseline': {'total': 100, 'days': [1, 2]}, 'timeline': [{'at': 'a', 'event': 'created'}], 'createdBy': 'ella'}
+class H(BaseHTTPRequestHandler):
+    def reply(self, code, obj):
+        self.send_response(code); self.send_header('Content-Type', 'application/json'); self.end_headers()
+        self.wfile.write(json.dumps(obj).encode())
+    def record(self, body=None):
+        open(LOG, 'w').write(json.dumps({'method': self.command, 'path': self.path, 'body': body, 'agent': self.headers.get('X-Agent-Session')}))
+    def do_GET(self):
+        self.record()
+        if self.path.startswith('/api/experiments/'):
+            return self.reply(200, {'success': True, 'data': E})
+        return self.reply(200, {'success': True, 'data': [E, dict(E, id='EXP-2', status='done', verdict='worked')]})
+    def do_POST(self):
+        n = int(self.headers.get('content-length', '0')); body = json.loads(self.rfile.read(n).decode() or '{}')
+        self.record(body)
+        if self.path.endswith('/measure'):
+            return self.reply(409, {'success': False, 'error': 'EXP-1 is not due until 2026-10-28'})
+        return self.reply(200, {'success': True, 'data': E})
+    def log_message(self, *a, **k): pass
+HTTPServer(('127.0.0.1', PORT), H).serve_forever()
+PY
+STUB_PID=$!
+disown "$STUB_PID" 2>/dev/null || true
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -f "$STUB_LOG"' EXIT
+for i in $(seq 1 30); do curl -s -o /dev/null -m 0.2 "http://127.0.0.1:${PORT}/" 2>/dev/null && break; sleep 0.1; done
+
+run() { CREWLY_SESSION_NAME=ella CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { CREWLY_SESSION_NAME=ella CREWLY_API_URL="http://127.0.0.1:${PORT}" bash "$EXEC" "$@" 2>&1 >/dev/null; }
+last() { jq -r "$1" "$STUB_LOG"; }
+
+# --- create on a project ticket: metric, expectation, window ---
+OUT=$(run create --hypothesis "FAQ schema → clicks 100 to 140" --source gsc --measure clicks --config /c.json \
+  --page https://x/ --from 100 --to 140 --window-days 21 --project ce --ticket T-12)
+check "create: path" "$(last .path)" "/api/experiments"
+check "create: body" "$(last '.body | tostring')" '{"hypothesis":"FAQ schema → clicks 100 to 140","metric":{"source":"gsc","measure":"clicks","config":"/c.json","page":"https://x/"},"expected":{"from":"100","to":"140"},"windowDays":"21","ticket":{"kind":"project","project":"ce","id":"T-12"}}'
+check "create: agent header" "$(last .agent)" "ella"
+check "create: card" "$(printf '%s' "$OUT" | jq -c '.experiment | [.id, .baseline, .metric.page]')" '["EXP-1",100,"https://x/"]'
+
+# --- create on a harness ticket with GA4 form events ---
+run create --hypothesis "Shorter form" --source ga4 --measure events --event generate_lead --channel all --config /c.json --tkt TKT-40 >/dev/null
+check "create ga4: body" "$(last '.body | tostring')" '{"hypothesis":"Shorter form","metric":{"source":"ga4","measure":"events","config":"/c.json","event":"generate_lead","channel":"all"},"ticket":{"kind":"harness","id":"TKT-40"}}'
+
+# --- create from JSON passes the body through ---
+run '{"action":"create","hypothesis":"J","metric":{"source":"gsc","measure":"ctr","config":"/c.json"}}' >/dev/null
+check "create json: body" "$(last '.body | tostring')" '{"hypothesis":"J","metric":{"source":"gsc","measure":"ctr","config":"/c.json"}}'
+
+# --- create on an already-done ticket with an explicit ship time ---
+run create --hypothesis "Late card" --source gsc --measure clicks --config /c.json --project ce --ticket T-9 --shipped-at 2026-10-01T10:00:00Z >/dev/null
+check "create shipped-at: body" "$(last '.body.shippedAt')" "2026-10-01T10:00:00Z"
+run '{"action":"create","hypothesis":"J","metric":{"source":"gsc","measure":"ctr","config":"/c.json"},"shippedAt":"2026-10-01T10:00:00Z"}' >/dev/null
+check "create json shipped-at: body" "$(last '.body.shippedAt')" "2026-10-01T10:00:00Z"
+
+# --- missing params / a ticket without its project ---
+check "create: missing" "$(run_err create --hypothesis h --source gsc --measure clicks | grep -c 'config')" "1"
+check "create: ticket w/o project" "$(run_err create --hypothesis h --source gsc --measure clicks --config /c --ticket T-1 | grep -c 'needs --project')" "1"
+
+# --- ship / show / list / cancel ---
+run ship --id EXP-1 --shipped-at 2026-10-01T10:00:00Z >/dev/null
+check "ship: path" "$(last .path)" "/api/experiments/EXP-1/ship"
+check "ship: body" "$(last '.body | tostring')" '{"shippedAt":"2026-10-01T10:00:00Z"}'
+OUT=$(run show --id EXP-1)
+check "show: timeline" "$(printf '%s' "$OUT" | jq -c '.experiment.timeline | map(.event)')" '["created"]'
+OUT=$(run list --status done --ticket TKT-40)
+check "list: path" "$(last .path)" "/api/experiments?status=done&ticket=TKT-40"
+check "list: rows" "$(printf '%s' "$OUT" | jq -c '[.experiments[] | [.id, .verdict]]')" '[["EXP-1",null],["EXP-2","worked"]]'
+run cancel --id EXP-1 --reason dup >/dev/null
+check "cancel: body" "$(last '.body | tostring')" '{"reason":"dup"}'
+
+# --- measure refused before it is due: the error reaches the agent ---
+check "measure: not due" "$(run_err measure --id EXP-1 | grep -c 'not due')" "1"
+
+# --- unknown action / option ---
+check "unknown action" "$(run_err frobnicate | grep -c 'Unknown action')" "1"
+check "unknown option" "$(run_err list --nope | grep -c 'Unknown option')" "1"
+
+echo "experiment-card: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/desktop-app-control/execute.sh

@@ -32,6 +32,9 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 LOG_DIR="${HOME}/.crewly/logs"
 LOG_FILE="${LOG_DIR}/desktop-app-control.log"
+# Where `scan` looks for installed apps. Overridable so the scan can be
+# exercised against a fixture directory on machines without /Applications.
+APPLICATIONS_DIR="${CREWLY_APPLICATIONS_DIR:-/Applications}"
 
 # Ensure log directory exists
 mkdir -p "$LOG_DIR"
@@ -108,7 +111,7 @@ do_scan() {
   }
 
   # Scan for Electron apps by checking framework directory
-  for app_dir in /Applications/*.app; do
+  for app_dir in "$APPLICATIONS_DIR"/*.app; do
     [ ! -d "$app_dir" ] && continue
     if [ -d "$app_dir/Contents/Frameworks/Electron Framework.framework" ]; then
       local app_name
@@ -138,7 +141,7 @@ do_scan() {
   local browser port
   while IFS='|' read -r browser port; do
     [ -z "$browser" ] && continue
-    if [ -d "/Applications/$browser.app" ]; then
+    if [ -d "$APPLICATIONS_DIR/$browser.app" ]; then
       local running="false"
       if pgrep -f "$browser" > /dev/null 2>&1; then
         running="true"

package/config/skills/orchestrator/send-message/execute.sh

@@ -5,10 +5,27 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "${SCRIPT_DIR}/../_common/lib.sh"
 
-INPUT=$(read_json_input "${1:-}")
+# CLI flags (--session/--to, --message, --force) are accepted too: the Gemini
+# safe-call guide shows the flag form.
+if [ "${1:-}" != "" ] && [ "${1#--}" != "${1}" ]; then
+  FLAG_SESSION=""; FLAG_MESSAGE=""; FLAG_FORCE=""
+  while [ $# -gt 0 ]; do
+    case "$1" in
+      --session|--sessionName|--to) FLAG_SESSION="${2:-}"; shift 2 ;;
+      --message) FLAG_MESSAGE="${2:-}"; shift 2 ;;
+      --force) FLAG_FORCE="true"; shift ;;
+      *) error_exit "Unknown option: $1" ;;
+    esac
+  done
+  INPUT=$(jq -n --arg s "$FLAG_SESSION" --arg m "$FLAG_MESSAGE" --arg f "$FLAG_FORCE" \
+    '{sessionName: $s, message: $m} + (if $f == "true" then {force: true} else {} end)')
+else
+  INPUT=$(read_json_input "${1:-}")
+fi
 [ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"sessionName\":\"agent-session\",\"message\":\"hello\"}' or echo '{...}' | execute.sh"
 
-SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // empty')
+# `to` is accepted as an alias for `sessionName` (older prompt examples used it).
+SESSION_NAME=$(printf '%s' "$INPUT" | jq -r '.sessionName // .to // empty')
 MESSAGE=$(printf '%s' "$INPUT" | jq -r '.message // empty')
 FORCE=$(printf '%s' "$INPUT" | jq -r '.force // empty')
 require_param "sessionName" "$SESSION_NAME"

package/config/skills/orchestrator/send-message/execute.test.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+# Tests for the orchestrator send-message skill.
+#
+# Guards the input forms the orchestrator prompt teaches: JSON with
+# `sessionName` (canonical), JSON with `to` (older examples), and the CLI
+# flag form from the Gemini safe-call guide. `curl` is stubbed on PATH, so
+# every case runs offline and records the real request the skill issues.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PASS=0
+FAIL=0
+
+check() {
+  local name="$1" needle="$2" haystack="$3"
+  if printf '%s' "$haystack" | grep -qF -- "$needle"; then
+    PASS=$((PASS + 1)); echo "  ✓ ${name}"
+  else
+    FAIL=$((FAIL + 1)); echo "  ✗ ${name}"; echo "    expected to contain: ${needle}"; echo "    actual: ${haystack}"
+  fi
+}
+
+STUB_DIR="$(mktemp -d)"
+cat > "$STUB_DIR/curl" << 'STUB_EOF'
+#!/bin/bash
+URL=""; BODY=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -d) BODY="$2"; shift 2 ;;
+    -X|-H|-w) shift 2 ;;
+    -s) shift ;;
+    *) URL="$1"; shift ;;
+  esac
+done
+printf '%s %s\n' "$URL" "$(printf '%s' "$BODY" | tr -d '\n ')" >> "$CURL_LOG"
+printf '{"success":true}\n200'
+STUB_EOF
+chmod +x "$STUB_DIR/curl"
+export PATH="$STUB_DIR:$PATH" CREWLY_API_URL="http://stub.invalid" CREWLY_SESSION_NAME="crewly-orc"
+
+# Runs the skill; sets OUT (stdout+stderr) and REQ (requests sent).
+run() {
+  CURL_LOG="$(mktemp)"; export CURL_LOG
+  OUT="$(bash "$SCRIPT_DIR/execute.sh" "$@" </dev/null 2>&1)" || true
+  REQ="$(cat "$CURL_LOG")"; rm -f "$CURL_LOG"
+}
+
+echo "=== orchestrator send-message tests ==="
+
+run '{"sessionName":"dev-1","message":"hi"}'
+check "sessionName JSON reaches /deliver for that session" "http://stub.invalid/api/terminal/dev-1/deliver" "$REQ"
+check "readiness-aware delivery by default" '"waitForReady":true' "$REQ"
+
+run '{"to":"dev-2","message":"hi"}'
+check "'to' is accepted as an alias for sessionName" "/api/terminal/dev-2/deliver" "$REQ"
+
+run --to dev-3 --message "hello there"
+check "--to/--message flags work" "/api/terminal/dev-3/deliver" "$REQ"
+check "flag message is sent" '"message":"hellothere"' "$REQ"
+
+run --session dev-4 --message hi --force
+check "--session and --force flags work" "/api/terminal/dev-4/deliver" "$REQ"
+check "--force sends force:true" '"force":true' "$REQ"
+
+run '{"message":"no target"}'
+check "missing session is reported" "sessionName" "$OUT"
+# (lib.sh sends a skill-start heartbeat; what must not happen is a delivery.)
+if printf '%s' "$REQ" | grep -q "/deliver"; then
+  FAIL=$((FAIL + 1)); echo "  ✗ missing session must not deliver anything"
+else
+  PASS=$((PASS + 1)); echo "  ✓ missing session delivers nothing"
+fi
+
+run --bogus x
+check "unknown flag is refused" "Unknown option: --bogus" "$OUT"
+
+rm -rf "$STUB_DIR"
+echo ""
+echo "=== Results: ${PASS} passed, ${FAIL} failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/registry.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 2,
-  "lastUpdated": "2026-09-29T01:47:07.718Z",
+  "lastUpdated": "2026-10-03T01:12:43.309Z",
   "cdnBaseUrl": "https://raw.githubusercontent.com/stevehuang0115/crewly/main",
   "source": "github",
   "items": [
@@ -1412,7 +1412,7 @@
       "name": "SEO Ops",
       "description": "Search Console-driven SEO operations for any site: query patterns (low-CTR top-3, near-miss 4-20, rising queries, keyword cannibalization), per-URL report cards, pre-publish SEO/AEO checks, a gated programmatic-page queue, and a live-diff gate that stops agents from removing things from live pages. Use when auditing organic search, deciding what to rewrite, or before changing a live page. For writing posts use seo-blog-writer instead.",
       "author": "Crewly",
-      "version": "1.0.0",
+      "version": "1.2.0",
       "category": "development",
       "tags": [
         "seo",
@@ -1425,12 +1425,12 @@
       "downloads": 0,
       "rating": 0,
       "createdAt": "2026-09-29T01:43:29.904Z",
-      "updatedAt": "2026-09-29T01:47:07.718Z",
+      "updatedAt": "2026-10-03T01:12:43.309Z",
       "source": "config/skills/agent/marketplace/seo-ops",
       "assets": {
         "archive": "config/skills/agent/marketplace/seo-ops",
         "checksum": "",
-        "sizeBytes": 95495
+        "sizeBytes": 149452
       },
       "metadata": {
         "skillType": "claude-skill",
@@ -1447,7 +1447,9 @@
           "keyword cannibalization",
           "pre-publish seo check",
           "programmatic seo pages",
-          "live page diff"
+          "live page diff",
+          "experiment metric",
+          "url inspection"
         ],
         "files": [
           "execute.sh",

package/config/skills/team-leader/signal-digest/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: Signal Digest
+description: "Daily signal digest for a site you own as team lead: GA4 traffic and key events, Search Console opportunities (low-CTR top-3, near-miss 4-20, rising, cannibalization), the site's inbound mail and broken pages / JS errors, minus what was already tried — turned into 3-5 ranked actions the owner answers Do / Skip on one Slack card. Do opens an experiment ticket."
+version: 1.1.0
+category: productivity
+skillType: claude-skill
+assignableRoles:
+  - team-leader
+triggers:
+  - daily signal digest
+  - daily signals
+  - what should we try on the site
+  - site opportunities
+tags:
+  - seo
+  - analytics
+  - experiments
+  - owner-decisions
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 180000
+---
+
+# Signal Digest (team lead)
+
+One run per site per day (#987, `specs/2026-10-03-signal-digest.md`):
+
+1. **collect** — gathers the signals and drafts actions.
+2. **you decide** — keep the 3–5 actions most worth the owner's tap, rewrite them in plain words,
+   add your own (e.g. a question the inbox keeps asking → an FAQ section).
+3. **propose** — the owner gets **one card**: each action with **Do** / **Skip**.
+   - **Do** opens an experiment ticket in the site's project and, when the action names an
+     `experiment` metric, an **experiment card** (#986) linked to it: the baseline is captured when
+     the ticket is done and the result is measured after 14 days, automatically. You get a
+     `[SIGNAL DIGEST]` message with both ids. Ship it and close the ticket.
+   - **Skip** keeps that action off your list for 30 days. A Do keeps it off for 90.
+   - Unanswered actions are replaced by your next digest (you may propose them again).
+
+## Setup (once per site)
+
+The config is the site's **seo-ops** config plus a `signalDigest` section — copy
+`signal-digest.config.example.json`. Google access is seo-ops's service account
+(`SEO_OPS_GOOGLE_CREDENTIALS`, read-only: Search Console user + GA4 Viewer).
+
+| `signalDigest` key | Meaning |
+|---|---|
+| `site` | Site name on the card and in the history (default: host of `siteUrl`) |
+| `project` | Project the Do tickets go into (name or id). Without it a Do opens no ticket |
+| `days` | Window, compared with the window before it (default 7) |
+| `ga4.conversionEvents` | Key events that count as conversions (default: all key events) |
+| `inbox.query` / `.account` / `.max` | Gmail search for the site's inbound requests (Google connector) |
+| `errors.checkSitemap` / `.maxUrls` | Fetch up to N sitemap pages and report the ones not answering 200 (default on, 60) |
+| `errors.url` or `errors.command` | JS errors as JSON: `[{"message","count","url"}]` or `{"errors":[…]}` |
+| `experimentLog` | Extra Markdown experiment log; a draft whose query/page it mentions is dropped (experiment cards are always checked) |
+| `thresholds` | `ga4DropPct` (20), `ga4MinPrevSessions` (50), `ga4MinPrevKeyEvents` (5) |
+
+Daily run: `bash execute.sh schedule --config <file> [--cron "0 8 * * *"] [--timezone America/New_York]`
+prints the cron task; hand it to the orchestrator to create with `create-cron`.
+
+## Commands
+
+```bash
+bash execute.sh collect --config ce.signal.json            # JSON: signals, alreadyTried, candidates
+bash execute.sh propose --config ce.signal.json --actions actions.json
+```
+
+`collect` prints `sources` (ok / not configured / error: why), the signals (`ga4`, `gsc`,
+`inbox`, `errors`), `alreadyTried` (dropped drafts and why: the owner's earlier Do / Skip, an
+experiment card on the same query or page, or the experiment log), `pendingOnOwner` and up to 10
+`candidates`, best first. GA4 respects seo-ops' `ga4HostName`. The sitemap check takes a different
+slice of `errors.maxUrls` pages each day, so the whole sitemap is covered over a few days.
+
+`collect` also reports the source statuses to Crewly (`sourceReport` in the output). The owner is
+told **once** when a source starts failing and once when it works again; the digest card shows
+each source's status. So never post about a failing source yourself. Exit `1` when no source
+could be examined: stop there and do not propose from nothing.
+
+`--actions` is a JSON array (file or inline) of 3–5 actions, best first:
+
+```json
+[{"key":"gsc:low-ctr:h1b visa fee","source":"gsc",
+  "signal":"'h1b visa fee' ranks #2 with 4% CTR on 900 impressions (7 days)",
+  "proposal":"Rewrite the title and description of /h1b-fee to answer the fee question",
+  "expectedEffect":"CTR 4% → ~16%: about +100 clicks a week",
+  "effort":"S — 1 h","metric":"GSC CTR for 'h1b visa fee'",
+  "experiment":{"source":"gsc","measure":"ctr","query":"h1b visa fee","page":"https://visa.careerengine.us/h1b-fee"}}]
+```
+
+- `key` is the action's identity across days. Keep the draft's key when you keep its action;
+  for your own, use `<source>:<kind>:<subject>`.
+- `source`: `ga4` | `gsc` | `inbox` | `errors` | `other`.
+- Lengths: signal ≤ 400, proposal ≤ 200, expectedEffect ≤ 240, effort ≤ 60 characters.
+- `experiment` (optional, keep the draft's): the seo-ops metric that measures it —
+  `source` gsc (`clicks` / `impressions` / `ctr` / `position`, filters `query`, `page`) or
+  ga4 (`sessions` / `events`, `event`, `channel`). Leave it out for fixes that move no metric
+  (a broken page, a JS error).
+
+`propose` answers `{"success":true,"digestId":"SD-4","card":"posted"}`. A `409` lists actions
+the owner already decided — replace them and propose again. One card a day: while today's
+digest (the last 20 hours) still has open actions, proposing the same actions returns it and
+different ones get a `409` — do not post a second card.
+
+## Rules
+
+- Never propose what `alreadyTried` lists, and never more than 5 actions.
+- Each action states signal → proposal → expected effect → effort, with a number when there is one.
+- This skill only reads Google and Gmail; it never changes the site.