crewly 1.20.301 → 1.20.303

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/agent/core/receive-file/SKILL.md

@@ -49,5 +49,9 @@ Prints:
   24 hours pass).
 - An interrupted download keeps its `.part` file and resumes on the next run.
 - `--no-ack` keeps the server copy so another run can fetch it again.
+- Also how an **owner's upload** reaches you: when the owner uploads a file for a
+  link you made with `request-file`, you get a message with the handoff id and this
+  command (file kept up to 7 days). If the owner has a file that is too large for
+  Slack, use `request-file` instead of asking them to compress it or use Drive.
 - A handoff is gone once received, cancelled or expired (24 h): ask the sender
   to send it again.

package/config/skills/agent/core/request-file/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: Request File
+description: Ask the OWNER for a file that is too big for Slack (video, archive, anything over 1 GB or not on Slack) by creating a private upload link they open on their phone. The upload lands on this machine and you are told to receive it. Use instead of asking the owner to compress it or put it in Drive.
+version: 1.0.0
+category: productivity
+skillType: claude-skill
+assignableRoles:
+  - "*"
+triggers:
+  - request file
+  - upload link
+  - file too large
+  - could not be downloaded
+  - the video is too big
+  - get the file from the owner
+  - need the footage
+tags:
+  - files
+  - upload
+  - owner
+execution:
+  type: script
+  script:
+    file: execute.sh
+    interpreter: bash
+    timeoutMs: 60000
+---
+
+# Request File
+
+Gets a big file from **the owner**, who is probably on a phone and away from the machine.
+
+```bash
+bash execute.sh --purpose "the raw footage for the launch video"
+bash execute.sh --purpose "the signed contract (PDF)" --max-files 1
+bash execute.sh --status ur_AbCdEfGhIjKlMnOpQrStUv
+bash execute.sh --cancel ur_AbCdEfGhIjKlMnOpQrStUv
+```
+
+Prints:
+
+```json
+{"success":true,"requestId":"ur_…","url":"https://crewlyai.com/portal/upload/ur_…","expiresAt":"…",
+ "limits":{"maxFileBytes":2147483648,"maxFiles":10},"instruction":"Post the link to the owner in your own words…"}
+```
+
+## What to do with it
+
+1. **Post the `url` to the owner** where you are talking to them (the Slack
+   thread, the chat), in your own words: what you need, why, and that they open
+   the link on their phone, sign in if asked, and pick the file from the camera
+   roll. One short message. Do not paste this skill's JSON.
+2. **Carry on with anything else you can do.** You do not need to wait or poll:
+   when the upload finishes you get a message with the file name and the exact
+   `receive-file` command. Run it, then tell the owner in your own words that you
+   have it.
+3. If the owner says it does not work or the link expired (48 hours), run the
+   skill again for a fresh link. `--cancel` withdraws a link you no longer need.
+
+## When to use it
+
+- A Slack attachment came with `could not be downloaded` and a size over the
+  limit (1 GB by default), or the disk is too full to take it.
+- The file is not on Slack at all (a phone video, a folder the owner zipped).
+- **Never** answer a large file with "please compress it" or "put it in Drive".
+
+Needs the machine to be signed in to Crewly Cloud. Files over about 100 MB
+need the owner's paid plan (up to 2 GB); on the free plan the page tells the
+owner so. The file is kept on a temporary server until you receive it
+(`receive-file` deletes it) or for 7 days. Do not use it for secrets.
+
+Options: `--purpose` (required, up to 300 characters, shown to the owner on the
+upload page; say what the file is for), `--agent-name` (the name the owner sees,
+default your session name), `--max-files` (1 to 10, default 10).

package/config/skills/agent/core/request-file/execute.sh

@@ -0,0 +1,89 @@
+#!/bin/bash
+# =============================================================================
+# request-file — ask the owner for a (large) file through a Crewly Cloud upload
+# link (crewly-services apps/SPEC.md section 19).
+#
+# The backend (POST /api/apps/upload-requests) asks Cloud for a request; the
+# owner opens the link on their phone and uploads in chunks; the machine's
+# upload watcher tells the agent when the file is ready (receive-file).
+#
+# Usage:
+#   bash execute.sh --purpose <text> [--agent-name <name>] [--max-files <n>]
+#   bash execute.sh --status <requestId>
+#   bash execute.sh --cancel <requestId>
+# =============================================================================
+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 --purpose <text> [--agent-name <name>] [--max-files <n>]
+  bash execute.sh --status <requestId>
+  bash execute.sh --cancel <requestId>
+
+Options:
+  --purpose     What you need the file for, in your words (required, up to 300 characters; the owner sees it)
+  --agent-name  The name the owner sees (default: your session name)
+  --max-files   How many files the link accepts, 1 to 10 (default 10)
+  --status      Show a request: state, limits, files uploaded so far
+  --cancel      Withdraw a link you no longer need
+  --help | -h   Show this help
+EOF_USAGE
+}
+
+fail_from() {
+  printf '%s' "$1" | jq -c '{success: false, status: (.status // 0), reason: (.details.error // .error // "unknown"), message: (.details.message // .details // "")}' 2>/dev/null \
+    || jq -cn --arg r "$1" '{success: false, reason: $r}'
+  exit 1
+}
+
+call() {
+  local out
+  out=$(api_call "$@" 2>&1) || { fail_from "$(printf '%s\n' "$out" | tail -n 1)"; }
+  printf '%s\n' "$out" | tail -n 1
+}
+
+PURPOSE=""; AGENT_NAME=""; MAX_FILES=""; STATUS=""; CANCEL=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --purpose)    [ $# -ge 2 ] || error_exit "--purpose requires a value"; PURPOSE="$2"; shift 2 ;;
+    --agent-name) [ $# -ge 2 ] || error_exit "--agent-name requires a value"; AGENT_NAME="$2"; shift 2 ;;
+    --max-files)  [ $# -ge 2 ] || error_exit "--max-files requires a value"; MAX_FILES="$2"; shift 2 ;;
+    --status)     [ $# -ge 2 ] || error_exit "--status requires a request id"; STATUS="$2"; shift 2 ;;
+    --cancel)     [ $# -ge 2 ] || error_exit "--cancel requires a request id"; CANCEL="$2"; shift 2 ;;
+    --help|-h)    print_usage; exit 0 ;;
+    *) error_exit "Unknown option: $1" ;;
+  esac
+done
+
+ID_RE='^ur_[A-Za-z0-9_-]{22}$'
+
+if [ -n "$STATUS" ]; then
+  [[ "$STATUS" =~ $ID_RE ]] || error_exit "--status needs a request id like ur_…"
+  RESULT=$(call GET "/apps/upload-requests/${STATUS}") || { printf '%s\n' "$RESULT"; exit 1; }
+  printf '%s' "$RESULT" | jq -c '{success: true} + (.data | {requestId, status, purpose, expiresAt, files})'
+  exit 0
+fi
+
+if [ -n "$CANCEL" ]; then
+  [[ "$CANCEL" =~ $ID_RE ]] || error_exit "--cancel needs a request id like ur_…"
+  RESULT=$(call DELETE "/apps/upload-requests/${CANCEL}") || { printf '%s\n' "$RESULT"; exit 1; }
+  jq -cn --arg id "$CANCEL" '{success: true, requestId: $id, cancelled: true}'
+  exit 0
+fi
+
+[ -n "$PURPOSE" ] || error_exit "--purpose is required: say what you need the file for"
+if [ -n "$MAX_FILES" ]; then
+  [[ "$MAX_FILES" =~ ^[0-9]+$ ]] && [ "$MAX_FILES" -ge 1 ] && [ "$MAX_FILES" -le 10 ] || error_exit "--max-files must be 1 to 10"
+fi
+
+BODY=$(jq -cn --arg p "$PURPOSE" --arg n "$AGENT_NAME" --arg m "$MAX_FILES" \
+  '{purpose: $p} + (if $n != "" then {agentName: $n} else {} end) + (if $m != "" then {maxFiles: ($m | tonumber)} else {} end)')
+CREATED=$(call POST "/apps/upload-requests" "$BODY") || { printf '%s\n' "$CREATED"; exit 1; }
+URL=$(printf '%s' "$CREATED" | jq -r '.data.url // empty')
+[ -n "$URL" ] || error_exit "Cloud answered without an upload link"
+
+printf '%s' "$CREATED" | jq -c '{success: true} + (.data | {requestId, url, expiresAt, limits, upgradeHint})
+  + {instruction: "Post the link to the owner in your own words (what you need and why; open it on the phone, pick the file from the camera roll). You will get a message with the receive-file command when the upload is done. Do not ask the owner to compress the file or use Drive."}'

package/config/skills/agent/core/request-file/execute.test.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Tests for request-file — run with: bash execute.test.sh
+# A Python stub plays the Crewly backend.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXEC="$HERE/execute.sh"
+PASS=0; FAIL=0
+check() { if [ "$2" = "$3" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); echo "FAIL: $1"; echo "  want: $3"; echo "  got:  $2"; fi; }
+
+PORT=18862
+STUB_LOG="$(mktemp)"; export STUB_LOG 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'])
+ID = 'ur_AbCdEfGhIjKlMnOpQrStUv'
+def note(**kw):
+    with open(LOG, 'a') as f: f.write(json.dumps(kw) + '\n')
+class H(BaseHTTPRequestHandler):
+    def send(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 body(self):
+        n = int(self.headers.get('Content-Length') or 0); return self.rfile.read(n)
+    def do_POST(self):
+        b = self.body()
+        if self.path == '/api/apps/upload-requests':
+            req = json.loads(b); note(op='create', req=req, session=self.headers.get('X-Agent-Session'))
+            if req['purpose'] == 'refuse':
+                return self.send(402, {'success': False, 'error': 'quota_exceeded', 'message': 'Too many open links.'})
+            return self.send(201, {'success': True, 'data': {'requestId': ID, 'url': 'https://crewlyai.com/portal/upload/' + ID, 'expiresAt': '2026-10-13T00:00:00.000Z', 'limits': {'maxFileBytes': 2147483648, 'maxFiles': 10}}})
+        self.send(404, {'success': False})
+    def do_GET(self):
+        note(op='status', path=self.path)
+        self.send(200, {'success': True, 'data': {'requestId': ID, 'status': 'open', 'purpose': 'p', 'expiresAt': 'x', 'files': [], 'limits': {}}})
+    def do_DELETE(self):
+        note(op='cancel', path=self.path); self.send(200, {'success': True, 'data': {'cancelled': True}})
+    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
+WORK="$(mktemp -d)"
+trap 'kill "$STUB_PID" >/dev/null 2>&1; rm -rf "$STUB_LOG" "$WORK"' 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
+mkdir -p "$WORK/home/.crewly"
+ENVS=(CREWLY_API_URL="http://127.0.0.1:${PORT}" CREWLY_SESSION_NAME=pia HOME="$WORK/home" CREWLY_HOME="$WORK/home/.crewly")
+run() { env "${ENVS[@]}" bash "$EXEC" "$@" 2>/dev/null; }
+run_err() { env "${ENVS[@]}" bash "$EXEC" "$@" 2>&1 >/dev/null; }
+
+: > "$STUB_LOG"
+OUT=$(run --purpose "the raw footage" --agent-name Pia --max-files 2)
+check "result" "$(printf '%s' "$OUT" | jq -c '{success, requestId, url}')" '{"success":true,"requestId":"ur_AbCdEfGhIjKlMnOpQrStUv","url":"https://crewlyai.com/portal/upload/ur_AbCdEfGhIjKlMnOpQrStUv"}'
+check "instruction tells the agent not to ask for compression" "$(printf '%s' "$OUT" | jq -r .instruction | grep -c 'compress')" "1"
+check "create request" "$(sed -n 1p "$STUB_LOG" | jq -c '{req, session}')" '{"req":{"purpose":"the raw footage","agentName":"Pia","maxFiles":2},"session":"pia"}'
+
+: > "$STUB_LOG"
+run --purpose "plain" >/dev/null
+check "optional fields are left out" "$(sed -n 1p "$STUB_LOG" | jq -c .req)" '{"purpose":"plain"}'
+
+OUT=$(run --purpose refuse; true)
+check "cloud refusal passed through" "$(printf '%s' "$OUT" | jq -c '{success, reason}')" '{"success":false,"reason":"quota_exceeded"}'
+
+: > "$STUB_LOG"
+OUT=$(run --status ur_AbCdEfGhIjKlMnOpQrStUv)
+check "status" "$(printf '%s' "$OUT" | jq -r .status)" "open"
+check "status path" "$(jq -r .path "$STUB_LOG")" "/api/apps/upload-requests/ur_AbCdEfGhIjKlMnOpQrStUv"
+
+: > "$STUB_LOG"
+run --cancel ur_AbCdEfGhIjKlMnOpQrStUv >/dev/null
+check "cancel path" "$(jq -r .path "$STUB_LOG")" "/api/apps/upload-requests/ur_AbCdEfGhIjKlMnOpQrStUv"
+
+check "purpose required" "$(run_err | grep -c -- '--purpose is required')" "1"
+check "bad max-files refused" "$(run_err --purpose x --max-files 99 | grep -c -- '--max-files must be 1 to 10')" "1"
+check "bad id refused" "$(run_err --cancel nope | grep -c 'request id like ur_')" "1"
+
+echo "request-file: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/config/skills/agent/core/slack-file/SKILL.md

@@ -49,5 +49,5 @@ the full file at `path`.
 | `not_visible` | No bot of your account is in the file's channel. Ask the owner to invite you (or the Crewly app) there. |
 | `foreign_workspace` | The link is from a Slack workspace your account has not connected. |
 | `file_deleted` | The file was deleted. |
-| `too_large` | Over 25 MB. |
+| `too_large` | Over 25 MB for this command. A file the owner attached to a message is downloaded for you up to 1 GB; if it is still too big, or not on Slack, get it with the `request-file` skill (an upload link for the owner's phone). **Do not ask the owner to compress it or use Drive.** |
 | `no_file_in_message` | The message link has no file attached. |

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'