crewly 1.20.302 → 1.20.304

package/config/roles/developer/prompt.md

@@ -406,6 +406,13 @@ Default tier: **Fast Path** (greenfield, internal tools, prototypes). Escalate t
 - The Owner is consulted only for goal change, scope change, customer-facing commitment, irreversible expense, or strategic direction.
 
 
+## Long Builds and Background Forks
+
+- Do long multi-step builds (rendering, video, large refactors) in the foreground of your own turn. That is the default.
+- A background subagent or fork can die silently, and then nobody delivers what you promised. If you do use one, keep its description specific, tell the owner only what you can verify, and check on it: look at its output or transcript yourself within a few minutes, and do not end the turn on "it will report back" without a plan for when you look.
+- Crewly tells you when a background task made no progress for about 10 minutes (`[BACKGROUND TASK STALLED]`). When you see it, inspect what it produced and continue the work yourself in the foreground.
+- A promise to the owner ("starting now, will post here") stays yours until the result is posted, whoever does the work.
+
 ## Lazy Behavior Anti-Patterns
 
 You are failing the task if you:

package/config/roles/fullstack-dev/prompt.md

@@ -186,6 +186,13 @@ Default tier: **Fast Path** (greenfield, internal tools, prototypes). Escalate t
 - The Owner is consulted only for goal change, scope change, customer-facing commitment, irreversible expense, or strategic direction.
 
 
+## Long Builds and Background Forks
+
+- Do long multi-step builds (rendering, video, large refactors) in the foreground of your own turn. That is the default.
+- A background subagent or fork can die silently, and then nobody delivers what you promised. If you do use one, keep its description specific, tell the owner only what you can verify, and check on it: look at its output or transcript yourself within a few minutes, and do not end the turn on "it will report back" without a plan for when you look.
+- Crewly tells you when a background task made no progress for about 10 minutes (`[BACKGROUND TASK STALLED]`). When you see it, inspect what it produced and continue the work yourself in the foreground.
+- A promise to the owner ("starting now, will post here") stays yours until the result is posted, whoever does the work.
+
 ## Lazy Behavior Anti-Patterns
 
 You are failing the task if you:

package/config/roles/product-manager/prompt.md

@@ -296,6 +296,13 @@ Default tier: **Standard Path** (customer-facing or coordination work). Drop to
 - The Owner is consulted only for goal change, scope change, customer-facing commitment, irreversible expense, or strategic direction.
 
 
+## Long Builds and Background Forks
+
+- Do long multi-step builds (rendering, video, large refactors) in the foreground of your own turn. That is the default.
+- A background subagent or fork can die silently, and then nobody delivers what you promised. If you do use one, keep its description specific, tell the owner only what you can verify, and check on it: look at its output or transcript yourself within a few minutes, and do not end the turn on "it will report back" without a plan for when you look.
+- Crewly tells you when a background task made no progress for about 10 minutes (`[BACKGROUND TASK STALLED]`). When you see it, inspect what it produced and continue the work yourself in the foreground.
+- A promise to the owner ("starting now, will post here") stays yours until the result is posted, whoever does the work.
+
 ## Lazy Behavior Anti-Patterns
 
 You are failing the task if you:

package/config/skills/orchestrator/move-team/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: Move Team
+description: Move a whole team (members, memory, tickets, wiki, schedules, Slack identity) to another machine of the owner's account. Use only after the owner said yes to a specific team and machine.
+version: 1.0.0
+category: management
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+triggers:
+  - move team
+  - move the team to
+  - move to the other machine
+  - move to my Air
+  - migrate team to another machine
+tags:
+  - team
+  - machines
+  - migration
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Move Team
+
+The owner's Mac runs out of CPU or memory; another machine of the same account has room. "Move team CE to the Air" moves the whole team: members, prompts, memory and handover notes, tickets, wiki, schedules, open decisions, channels, and the agents' Slack identity. Code is cloned on the target from its git remote. Credentials and logins do not move; the owner gets a short list to reconnect. Crewly Cloud only carries an encrypted package.
+
+## Steps (the owner is on their phone: never ask for a terminal step)
+
+1. List the machines: `bash {{ORCHESTRATOR_SKILLS_PATH}}/move-team/execute.sh '{"action":"machines"}'`
+2. If the owner did not name the machine, or the name is ambiguous, ask which one (show the names).
+3. Check what would block it: `... '{"action":"check","team":"CE"}'`. If a repository has unpushed or uncommitted work, tell the owner in one sentence what to push (the lines it returns) and stop. Never move with `allowDirty` unless the owner says to move without that work.
+4. Ask the owner for approval in your own words, in the owner's thread: team, from which machine to which machine, and that the team stops here and starts there. Wait for a yes. A move without a yes in chat is refused by the backend.
+5. Start it: `... '{"action":"start","team":"CE","to":"Air"}'`. It returns a move id and runs in the background.
+6. Do not narrate progress in the owner's thread. Crewly Cloud sends the owner one summary (what moved, what to reconnect, a rollback link) when it is done.
+
+## Actions
+
+| Parameter | Used by | Description |
+|-----------|---------|-------------|
+| `action` | all | `machines`, `check`, `start`, `status`, `moves` |
+| `team` | check, start | Team name or id on this machine |
+| `to` | start | Target machine name (from `machines`) |
+| `moveId` | status | A move id |
+| `allowDirty` | start | `true` only on the owner's word: move although a repo has unpushed work (that work stays here) |
+| `skipFlagged` | start | `true` to leave out notes that hold credentials instead of stopping |
+
+## Rollback
+
+Within 7 days the owner can undo a move from the portal ("Moves") or by asking you. Rolling back is the owner's call: it needs the owner's tap, not yours.

package/config/skills/orchestrator/move-team/execute.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Move a team to another machine of the owner's account
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+INPUT=$(read_json_input "${1:-}")
+[ -z "$INPUT" ] && error_exit "Usage: execute.sh '{\"action\":\"machines|check|start|status|moves\",\"team\":\"CE\",\"to\":\"Air\"}'"
+
+ACTION=$(printf '%s' "$INPUT" | jq -r '.action // empty')
+require_param "action" "$ACTION"
+
+case "$ACTION" in
+  machines)
+    api_call GET "/team-moves/machines"
+    ;;
+  moves)
+    api_call GET "/team-moves"
+    ;;
+  status)
+    MOVE_ID=$(printf '%s' "$INPUT" | jq -r '.moveId // empty')
+    require_param "moveId" "$MOVE_ID"
+    api_call GET "/team-moves/${MOVE_ID}"
+    ;;
+  check)
+    TEAM=$(printf '%s' "$INPUT" | jq -r '.team // empty')
+    require_param "team" "$TEAM"
+    BODY=$(jq -n --arg t "$TEAM" '{teamName: $t}')
+    api_call POST "/team-moves/check" "$BODY"
+    ;;
+  start)
+    TEAM=$(printf '%s' "$INPUT" | jq -r '.team // empty')
+    TO=$(printf '%s' "$INPUT" | jq -r '.to // empty')
+    require_param "team" "$TEAM"
+    require_param "to" "$TO"
+    BODY=$(printf '%s' "$INPUT" | jq -c --arg t "$TEAM" --arg to "$TO" '{teamName: $t, targetName: $to, allowDirty: (.allowDirty // false), skipFlagged: (.skipFlagged // false)}')
+    api_call POST "/team-moves" "$BODY"
+    ;;
+  *)
+    error_exit "Unknown action: ${ACTION}. Use machines | check | start | status | moves"
+    ;;
+esac

package/config/skills/orchestrator/usage-categories/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: Usage Categories
+description: Save, list or remove the owner's own categories for usage reports (for example "self-media" and "book"). Categories are optional and only change how reports group tickets; they never alter ticket facts.
+version: 1.0.0
+category: monitoring
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+triggers:
+  - usage categories
+  - track time by category
+  - split usage into
+  - count self-media separately
+tags:
+  - usage
+  - categories
+  - report
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 20000
+---
+
+# Usage Categories
+
+The owner decides how usage should be grouped ("how much on self-media vs the book?"). Turn what they say into a category and save it. Nothing is required: with no categories, reports group by team.
+
+## Usage
+
+```bash
+bash execute.sh list
+
+# The description doubles as the keyword list when it is comma separated
+bash execute.sh set --name self-media --description "Xiaohongshu, Substack, LinkedIn, videos"
+
+# Explicit hints: keywords match ticket titles and text; teams / projects match by name
+bash execute.sh set --name book --keywords "chapter,manuscript,Bible study book" --teams "Writers"
+
+bash execute.sh remove --name book
+bash execute.sh clear
+```
+
+## How a ticket gets its category
+
+At report time, in this order:
+
+1. Keywords (case-insensitive), then team and project hints. The best score wins.
+2. If nothing matched and a small model is available, one batched question for the unmatched tickets.
+3. Otherwise `other`.
+
+The result is cached per ticket and category set, and changes the moment a definition changes. Tickets themselves are never modified, so redefining categories re-slices all past usage.
+
+## Etiquette
+
+- Use the owner's own words for names. Do not invent categories they did not ask for.
+- After saving, offer to run `usage-report --by category` so they see the split.
+- `other` is reserved and cannot be defined.

package/config/skills/orchestrator/usage-categories/execute.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# The owner's report categories ("self-media", "book", ...).
+#
+# Usage:
+#   execute.sh list
+#   execute.sh set --name self-media --description "Xiaohongshu, Substack, LinkedIn, videos" \
+#                  [--keywords a,b,c] [--teams "Marketing,Media"] [--projects "Site,Newsletter"]
+#   execute.sh remove --name self-media
+#   execute.sh clear
+#   execute.sh '{"command":"set","name":"book","keywords":["chapter","manuscript"]}'
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+COMMAND=""
+NAME=""
+DESCRIPTION=""
+KEYWORDS=""
+TEAMS=""
+PROJECTS=""
+INPUT_JSON=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+elif [[ $# -gt 0 && ${1:0:2} != '--' ]]; then
+  COMMAND="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name)        NAME="$2";        shift 2 ;;
+    --description) DESCRIPTION="$2"; shift 2 ;;
+    --keywords)    KEYWORDS="$2";    shift 2 ;;
+    --teams)       TEAMS="$2";       shift 2 ;;
+    --projects)    PROJECTS="$2";    shift 2 ;;
+    --help|-h)
+      echo "Usage: execute.sh list | set --name N [--description D] [--keywords a,b] [--teams a,b] [--projects a,b] | remove --name N | clear"
+      exit 0 ;;
+    *) shift ;;
+  esac
+done
+
+if [[ -n "$INPUT_JSON" ]]; then
+  [[ -z "$COMMAND" ]]     && COMMAND=$(echo "$INPUT_JSON" | jq -r '.command // empty' 2>/dev/null || true)
+  [[ -z "$NAME" ]]        && NAME=$(echo "$INPUT_JSON" | jq -r '.name // empty' 2>/dev/null || true)
+  [[ -z "$DESCRIPTION" ]] && DESCRIPTION=$(echo "$INPUT_JSON" | jq -r '.description // empty' 2>/dev/null || true)
+  [[ -z "$KEYWORDS" ]]    && KEYWORDS=$(echo "$INPUT_JSON" | jq -r '.keywords // empty | if type == "array" then join(",") else . end' 2>/dev/null || true)
+  [[ -z "$TEAMS" ]]       && TEAMS=$(echo "$INPUT_JSON" | jq -r '.teams // empty | if type == "array" then join(",") else . end' 2>/dev/null || true)
+  [[ -z "$PROJECTS" ]]    && PROJECTS=$(echo "$INPUT_JSON" | jq -r '.projects // empty | if type == "array" then join(",") else . end' 2>/dev/null || true)
+fi
+
+require_param "command (list|set|remove|clear)" "$COMMAND"
+
+case "$COMMAND" in
+  list)
+    api_call GET "/usage-ledger/categories"
+    ;;
+  set)
+    require_param "name" "$NAME"
+    BODY=$(jq -n --arg name "$NAME" --arg description "$DESCRIPTION" --arg keywords "$KEYWORDS" --arg teams "$TEAMS" --arg projects "$PROJECTS" '
+      def list($s): $s | split(",") | map(gsub("^\\s+|\\s+$"; "")) | map(select(length > 0));
+      { name: $name }
+      + (if $description != "" then { description: $description } else {} end)
+      + (if $keywords != "" then { keywords: list($keywords) } else {} end)
+      + (if $teams != "" then { teams: list($teams) } else {} end)
+      + (if $projects != "" then { projects: list($projects) } else {} end)')
+    api_call POST "/usage-ledger/categories" "$BODY"
+    ;;
+  remove)
+    require_param "name" "$NAME"
+    api_call DELETE "/usage-ledger/categories/$(jq -rn --arg n "$NAME" '$n|@uri')"
+    ;;
+  clear)
+    api_call PUT "/usage-ledger/categories" '{"categories":[]}'
+    ;;
+  *)
+    error_exit "Unknown command: $COMMAND (use list, set, remove or clear)"
+    ;;
+esac

package/config/skills/orchestrator/usage-categories/execute.test.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Tests for usage-categories — run with: bash execute.test.sh
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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; }
+
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/skills/orchestrator/usage-categories" "$TMP/skills/orchestrator/_common"
+cp "$HERE/execute.sh" "$TMP/skills/orchestrator/usage-categories/execute.sh"
+REAL_LIB="$(cd "$HERE/../../_common" && pwd)/lib.sh"
+cat > "$TMP/skills/orchestrator/_common/lib.sh" <<'STUB'
+source "$REAL_LIB"
+api_call() { printf '%s|%s|%s' "$1" "$2" "${3:-}" > "$CALL_LOG"; echo '{"success":true}'; }
+STUB
+export REAL_LIB CALL_LOG="$TMP/call"
+
+run() { CODE=0; OUT=$(env -u CREWLY_SESSION_NAME bash "$TMP/skills/orchestrator/usage-categories/execute.sh" "$@" 2>"$TMP/err") || CODE=$?; }
+
+run list
+check "list" "$(cat "$CALL_LOG")" "GET|/usage-ledger/categories|"
+
+run set --name self-media --description "Xiaohongshu, Substack, LinkedIn" --keywords "videos, shorts" --teams "Marketing"
+LOG=$(cat "$CALL_LOG"); M=${LOG%%|*}; REST=${LOG#*|}; P=${REST%%|*}; B=${REST#*|}
+check "set uses POST" "$M $P" "POST /usage-ledger/categories"
+check "set body" "$(printf '%s' "$B" | jq -c '.')" '{"name":"self-media","description":"Xiaohongshu, Substack, LinkedIn","keywords":["videos","shorts"],"teams":["Marketing"]}'
+
+run '{"command":"set","name":"book","keywords":["chapter","manuscript"]}'
+LOG=$(cat "$CALL_LOG"); B=${LOG#*|*|}
+check "JSON input set body" "$(printf '%s' "$B" | jq -c '.')" '{"name":"book","keywords":["chapter","manuscript"]}'
+
+run remove --name "Bible study"
+check "remove encodes the name" "$(cat "$CALL_LOG")" "DELETE|/usage-ledger/categories/Bible%20study|"
+
+run clear
+check "clear" "$(cat "$CALL_LOG")" 'PUT|/usage-ledger/categories|{"categories":[]}'
+
+run set
+check "set needs a name" "$CODE" "1"
+
+run frobnicate
+check "unknown command" "$CODE" "1"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/orchestrator/usage-report/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: Usage Report
+description: How much owner time, agent time and tokens went into each category, team, project, agent or ticket (for example self-media vs the book). Computed from the immutable ticket ledger; categories are applied at report time.
+version: 1.0.0
+category: monitoring
+skillType: claude-skill
+assignableRoles:
+  - orchestrator
+triggers:
+  - usage report
+  - how much time did we spend
+  - how many tokens
+  - time and tokens per project
+  - where did the tokens go
+tags:
+  - usage
+  - tokens
+  - time
+  - cost
+  - report
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Usage Report
+
+Answers "how much time and how many tokens went into X?". Every ticket's facts (agent busy time, tokens and estimated cost per model, owner active minutes) are recorded as they happen and never change. This skill adds them up for a window and groups them the way the owner asks.
+
+## Usage
+
+```bash
+# Last 7 days by category (the owner's categories, else by team)
+bash execute.sh --since 7d --by category
+
+# Just the short text to read out or post to Slack
+bash execute.sh --since 30d --by category --text
+
+# Compare two of the owner's categories
+bash execute.sh --since 14d --by category --categories "self-media,book"
+
+# One-off categories (not saved): name:keyword,keyword;name:keyword
+bash execute.sh --since 7d --categories "media:xiaohongshu,substack,linkedin;book:chapter,bible"
+
+# Other groupings
+bash execute.sh --since 7d --by team
+bash execute.sh --since 7d --by project
+bash execute.sh --since 7d --by agent
+bash execute.sh --since 2d --by ticket --limit 10
+```
+
+`--since` takes `24h`, `7d`, `2w` or a date. Figures are summed per UTC hour, so a window edge is accurate to the hour.
+
+## Categories
+
+Categories are never required and never stored on tickets. If the owner has defined categories (see the `usage-categories` skill) the report uses them. If not, tickets are grouped by team (then project). A ticket that matches no category is `other`; usage that happened outside any ticket is `(no ticket)`.
+
+When the owner asks for a new grouping ("how much on self-media vs the book?"), either pass `--categories` for one report or save it with `usage-categories set`.
+
+## Output
+
+Each group has: owner minutes, agent busy minutes, tokens (cost-weighted: cache reads count 0.1x), raw tokens, estimated cost in USD, ticket count and its top 5 tickets. `summary` is a short text suitable for speech or Slack. `notes` lists caveats (for example tickets rebuilt from history are marked inferred).
+
+## Reading the numbers to the owner
+
+- Lead with the summary line, then the two or three biggest groups.
+- Owner minutes are an estimate from message times (messages on one ticket within 10 minutes form one span).
+- Say "about" for cost; it is an API-price estimate, not a bill.

package/config/skills/orchestrator/usage-report/execute.sh

@@ -0,0 +1,84 @@
+#!/bin/bash
+# Usage report: where the owner's time and the agents' tokens went.
+#
+# Usage:
+#   execute.sh [--since 7d] [--until 2026-10-11] [--by category|team|project|agent|ticket]
+#              [--categories "book,self-media" | "media:linkedin,substack;book:chapter"]
+#              [--limit 10] [--text]
+#   execute.sh '{"since":"7d","by":"category"}'
+#
+# --text prints only the short summary (good to read out or post to Slack).
+# Read-only: it changes nothing.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "${SCRIPT_DIR}/../_common/lib.sh"
+
+SINCE=""
+UNTIL=""
+BY=""
+CATEGORIES=""
+LIMIT=""
+TEXT="false"
+INPUT_JSON=""
+
+if [[ $# -gt 0 && ${1:0:1} == '{' ]]; then
+  INPUT_JSON="$1"
+  shift || true
+fi
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --since)      SINCE="$2";      shift 2 ;;
+    --until)      UNTIL="$2";      shift 2 ;;
+    --by)         BY="$2";         shift 2 ;;
+    --categories) CATEGORIES="$2"; shift 2 ;;
+    --limit)      LIMIT="$2";      shift 2 ;;
+    --text)       TEXT="true";     shift ;;
+    --help|-h)
+      echo "Usage: execute.sh [--since 7d] [--until DATE] [--by category|team|project|agent|ticket] [--categories NAMES_OR_DEFS] [--limit N] [--text]"
+      exit 0 ;;
+    *) shift ;;
+  esac
+done
+
+if [[ -n "$INPUT_JSON" ]]; then
+  [[ -z "$SINCE" ]]      && SINCE=$(echo "$INPUT_JSON" | jq -r '.since // empty' 2>/dev/null || true)
+  [[ -z "$UNTIL" ]]      && UNTIL=$(echo "$INPUT_JSON" | jq -r '.until // empty' 2>/dev/null || true)
+  [[ -z "$BY" ]]         && BY=$(echo "$INPUT_JSON" | jq -r '.by // empty' 2>/dev/null || true)
+  [[ -z "$CATEGORIES" ]] && CATEGORIES=$(echo "$INPUT_JSON" | jq -r '.categories // empty | if type == "array" then tojson else . end' 2>/dev/null || true)
+  [[ -z "$LIMIT" ]]      && LIMIT=$(echo "$INPUT_JSON" | jq -r '.limit // empty' 2>/dev/null || true)
+  if [[ "$TEXT" != "true" ]]; then TEXT=$(echo "$INPUT_JSON" | jq -r '.text // false' 2>/dev/null || echo false); fi
+fi
+
+QUERY=$(jq -rn \
+  --arg since "${SINCE:-7d}" --arg until "$UNTIL" --arg by "${BY:-category}" \
+  --arg categories "$CATEGORIES" --arg limit "$LIMIT" \
+  '[ "since=" + ($since|@uri), "by=" + ($by|@uri),
+     (if $until != "" then "until=" + ($until|@uri) else empty end),
+     (if $categories != "" then "categories=" + ($categories|@uri) else empty end),
+     (if $limit != "" then "limit=" + ($limit|@uri) else empty end) ] | join("&")')
+
+if ! RESP=$(api_call_full GET "/usage-ledger/report?${QUERY}"); then
+  error_exit "Could not fetch the usage report"
+fi
+
+if [[ "$TEXT" == "true" ]]; then
+  printf '%s' "$RESP" | jq -r '.data.summary // .error // "No report"'
+  exit 0
+fi
+
+# Compact: the full body has every token kind for every group.
+printf '%s' "$RESP" | jq '
+  if .success then
+    { summary: .data.summary,
+      window: .data.window,
+      by: .data.by,
+      categories: .data.categories,
+      totals: { ownerMinutes: .data.totals.ownerMinutes, agentBusyMinutes: .data.totals.agentBusyMinutes,
+                tokens: .data.totals.tokens.budget, rawTokens: .data.totals.tokens.total,
+                costUsd: .data.totals.costUsd, tickets: .data.totals.ticketCount },
+      groups: [ .data.groups[] | { key, ownerMinutes, agentBusyMinutes, tokens: .tokens.budget, rawTokens: .tokens.total,
+                costUsd, tickets: .ticketCount,
+                topTickets: [ .topTickets[] | { ticketId, title, ownerMinutes, agentBusyMinutes, tokens, costUsd } ] } ],
+      notes: .data.notes }
+  else . end'

package/config/skills/orchestrator/usage-report/execute.test.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# Tests for usage-report — run with: bash execute.test.sh
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+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; }
+
+TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
+mkdir -p "$TMP/skills/orchestrator/usage-report" "$TMP/skills/orchestrator/_common"
+cp "$HERE/execute.sh" "$TMP/skills/orchestrator/usage-report/execute.sh"
+REAL_LIB="$(cd "$HERE/../../_common" && pwd)/lib.sh"
+REPORT='{"success":true,"data":{"summary":"Usage, last 7 days: 3 tickets","window":{},"by":"category","categories":null,
+ "totals":{"ownerMinutes":6,"agentBusyMinutes":30,"tokens":{"budget":5000,"total":9000},"costUsd":1.5,"ticketCount":3},
+ "groups":[{"key":"book","ownerMinutes":6,"agentBusyMinutes":30,"tokens":{"budget":5000,"total":9000},"costUsd":1.5,"ticketCount":3,
+   "topTickets":[{"ticketId":"TKT-1","title":"Chapter","ownerMinutes":6,"agentBusyMinutes":30,"tokens":5000,"costUsd":1.5,"inferred":false}]}],"notes":[]}}'
+cat > "$TMP/skills/orchestrator/_common/lib.sh" <<'STUB'
+source "$REAL_LIB"
+api_call() { echo "$1 $2" > "$CALL_LOG"; printf '%s' "$REPORT"; }
+STUB
+export REAL_LIB REPORT CALL_LOG="$TMP/call"
+
+run() { CODE=0; OUT=$(env -u CREWLY_SESSION_NAME bash "$TMP/skills/orchestrator/usage-report/execute.sh" "$@" 2>"$TMP/err") || CODE=$?; }
+
+run
+check "default window and grouping" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=7d&by=category"
+check "compact groups" "$(printf '%s' "$OUT" | jq -c '.groups[0] | [.key, .tokens, .topTickets[0].ticketId]')" '["book",5000,"TKT-1"]'
+check "totals flattened" "$(printf '%s' "$OUT" | jq -c '.totals.tickets')" "3"
+
+run --since 30d --by team --limit 5 --categories "media:linkedin,substack;book"
+check "flags in the query, encoded" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=30d&by=team&categories=media%3Alinkedin%2Csubstack%3Bbook&limit=5"
+
+run '{"since":"2w","by":"project"}'
+check "JSON input" "$(cat "$CALL_LOG")" "GET /usage-ledger/report?since=2w&by=project"
+
+run --text
+check "--text prints the summary only" "$OUT" "Usage, last 7 days: 3 tickets"
+
+echo "=== Results: $PASS passed, $FAIL failed ==="
+[ "$FAIL" -eq 0 ]

package/config/skills/team-leader/usage-report/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: Usage Report
+description: How much owner time, agent time and tokens went into each category, team, project, agent or ticket (for example self-media vs the book). Computed from the immutable ticket ledger; categories are applied at report time.
+version: 1.0.0
+category: monitoring
+skillType: claude-skill
+assignableRoles:
+  - team-leader
+triggers:
+  - usage report
+  - how much time did we spend
+  - how many tokens
+  - time and tokens per project
+  - where did the tokens go
+tags:
+  - usage
+  - tokens
+  - time
+  - cost
+  - report
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Usage Report
+
+Answers "how much time and how many tokens went into X?". Every ticket's facts (agent busy time, tokens and estimated cost per model, owner active minutes) are recorded as they happen and never change. This skill adds them up for a window and groups them the way the owner asks.
+
+## Usage
+
+```bash
+# Last 7 days by category (the owner's categories, else by team)
+bash execute.sh --since 7d --by category
+
+# Just the short text to read out or post to Slack
+bash execute.sh --since 30d --by category --text
+
+# Compare two of the owner's categories
+bash execute.sh --since 14d --by category --categories "self-media,book"
+
+# One-off categories (not saved): name:keyword,keyword;name:keyword
+bash execute.sh --since 7d --categories "media:xiaohongshu,substack,linkedin;book:chapter,bible"
+
+# Other groupings
+bash execute.sh --since 7d --by team
+bash execute.sh --since 7d --by project
+bash execute.sh --since 7d --by agent
+bash execute.sh --since 2d --by ticket --limit 10
+```
+
+`--since` takes `24h`, `7d`, `2w` or a date. Figures are summed per UTC hour, so a window edge is accurate to the hour.
+
+## Categories
+
+Categories are never required and never stored on tickets. If the owner has defined categories (see the `usage-categories` skill) the report uses them. If not, tickets are grouped by team (then project). A ticket that matches no category is `other`; usage that happened outside any ticket is `(no ticket)`.
+
+When the owner asks for a new grouping ("how much on self-media vs the book?"), either pass `--categories` for one report or save it with `usage-categories set`.
+
+## Output
+
+Each group has: owner minutes, agent busy minutes, tokens (cost-weighted: cache reads count 0.1x), raw tokens, estimated cost in USD, ticket count and its top 5 tickets. `summary` is a short text suitable for speech or Slack. `notes` lists caveats (for example tickets rebuilt from history are marked inferred).
+
+## Reading the numbers to the owner
+
+- Lead with the summary line, then the two or three biggest groups.
+- Owner minutes are an estimate from message times (messages on one ticket within 10 minutes form one span).
+- Say "about" for cost; it is an API-price estimate, not a bill.