@smilintux/skcapstone 0.10.0 → 0.12.5

package/scripts/refresh-anthropic-token.sh

@@ -0,0 +1,172 @@
+#!/usr/bin/env bash
+# Proactive Anthropic OAuth token refresh + sync to OpenClaw gateway.
+#
+# Two-phase approach (prb-021b489e):
+#   Phase 1: If token is expiring (<2h) or expired, refresh it:
+#     a) Try `claude auth status` (lightweight, no interactive session)
+#     b) If that fails, spin up ephemeral Claude Code in tmux → triggers internal refresh → kill it
+#   Phase 2: Sync the (possibly refreshed) token to OpenClaw config + restart gateway if changed.
+#
+# Run via systemd timer every 4 hours.
+set -euo pipefail
+
+_sed_i() { if [[ "$OSTYPE" == "darwin"* ]]; then sed -i '' "$@"; else sed -i "$@"; fi; }
+
+CREDS="$HOME/.claude/.credentials.json"
+OPENCLAW_JSON="$HOME/.openclaw/openclaw.json"
+OPENCLAW_ENV="$HOME/.openclaw/.env"
+OVERRIDE_CONF="$HOME/.config/systemd/user/openclaw-gateway.service.d/override.conf"
+LOG_TAG="anthropic-token-refresh"
+TMUX_SESSION="token-refresh-ephemeral"
+
+log() { echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] [$LOG_TAG] $*"; }
+
+if [ ! -f "$CREDS" ]; then
+    log "ERROR: Claude credentials not found at $CREDS"
+    exit 1
+fi
+
+get_remaining_ms() {
+    python3 -c "
+import json, time
+creds = json.load(open('$CREDS'))
+exp = creds.get('claudeAiOauth',{}).get('expiresAt', 0)
+print(int(exp - time.time() * 1000))
+" 2>/dev/null || echo "0"
+}
+
+get_remaining_h() {
+    python3 -c "
+import json, time
+creds = json.load(open('$CREDS'))
+exp = creds.get('claudeAiOauth',{}).get('expiresAt', 0)
+print(f'{(exp/1000 - time.time())/3600:.1f}')
+" 2>/dev/null || echo "0"
+}
+
+token_needs_refresh() {
+    local remaining_ms
+    remaining_ms=$(get_remaining_ms)
+    # Refresh if less than 4 hours remaining (was 2h — too tight with 3h timer)
+    [ "$remaining_ms" -le 14400000 ]
+}
+
+token_is_healthy() {
+    local remaining_ms
+    remaining_ms=$(get_remaining_ms)
+    [ "$remaining_ms" -gt 14400000 ]
+}
+
+# ─── Phase 1: Refresh token if needed ───────────────────────────────
+
+if token_needs_refresh; then
+    log "Token needs refresh ($(get_remaining_h)h remaining)"
+
+    # Step 1a: Try lightweight refresh
+    log "Attempting lightweight refresh via 'claude auth status'..."
+    claude auth status > /dev/null 2>&1 || true
+    sleep 2
+
+    if token_is_healthy; then
+        log "Lightweight refresh succeeded! ($(get_remaining_h)h remaining)"
+    else
+        # Step 1b: Ephemeral Claude Code session in tmux
+        log "Lightweight refresh didn't cut it — spinning up ephemeral Claude Code session..."
+        tmux kill-session -t "$TMUX_SESSION" 2>/dev/null || true
+
+        tmux new-session -d -s "$TMUX_SESSION" \
+            "claude -p 'respond with just OK' --output-format stream-json 2>/dev/null; exit"
+
+        refreshed=false
+        for i in $(seq 1 12); do
+            sleep 5
+            if token_is_healthy; then
+                log "Ephemeral session refreshed the token! ($(get_remaining_h)h remaining)"
+                refreshed=true
+                break
+            fi
+        done
+
+        tmux kill-session -t "$TMUX_SESSION" 2>/dev/null || true
+
+        if [ "$refreshed" = "false" ]; then
+            log "ERROR: All refresh attempts failed ($(get_remaining_h)h remaining)"
+            log "Manual intervention may be needed: claude auth login"
+            # Continue to sync phase anyway — sync whatever token we have
+        fi
+    fi
+else
+    log "Token is healthy ($(get_remaining_h)h remaining), no refresh needed"
+fi
+
+# ─── Phase 2: Sync token to OpenClaw ────────────────────────────────
+
+ACCESS_TOKEN=$(python3 -c "import json; print(json.load(open('$CREDS'))['claudeAiOauth']['accessToken'])")
+REMAINING=$(get_remaining_h)
+
+# Check what's currently in the systemd override
+OLD_TOKEN=""
+if [ -f "$OVERRIDE_CONF" ]; then
+    OLD_TOKEN=$(grep "ANTHROPIC_API_KEY=" "$OVERRIDE_CONF" 2>/dev/null | sed 's/.*ANTHROPIC_API_KEY=//' || true)
+fi
+
+if [ "$OLD_TOKEN" = "$ACCESS_TOKEN" ]; then
+    log "Token already synced (expires in ${REMAINING}h)"
+    exit 0
+fi
+
+log "Token changed, syncing to OpenClaw..."
+
+# 1. Update openclaw.json
+if [ -f "$OPENCLAW_JSON" ]; then
+    python3 -c "
+import json
+with open('$OPENCLAW_JSON') as f:
+    cfg = json.load(f)
+if 'providers' in cfg.get('models', {}):
+    if 'anthropic' in cfg['models']['providers']:
+        cfg['models']['providers']['anthropic']['apiKey'] = '$ACCESS_TOKEN'
+        with open('$OPENCLAW_JSON', 'w') as f:
+            json.dump(cfg, f, indent=2)
+            f.write('\n')
+        print('[sync] Updated openclaw.json')
+    else:
+        print('[sync] No anthropic provider in openclaw.json')
+else:
+    print('[sync] No providers section in openclaw.json')
+"
+fi
+
+# 2. Update .env
+if grep -q "^ANTHROPIC_API_KEY=" "$OPENCLAW_ENV" 2>/dev/null; then
+    _sed_i "s|^ANTHROPIC_API_KEY=.*|ANTHROPIC_API_KEY=$ACCESS_TOKEN|" "$OPENCLAW_ENV"
+else
+    echo "ANTHROPIC_API_KEY=$ACCESS_TOKEN" >> "$OPENCLAW_ENV"
+fi
+log "Updated .env"
+
+# 3. Update systemd override
+NVIDIA_KEY=$(grep "NVIDIA_API_KEY=" "$OVERRIDE_CONF" 2>/dev/null | sed 's/.*NVIDIA_API_KEY=//' || true)
+cat > "$OVERRIDE_CONF" << EOF
+[Unit]
+StartLimitIntervalSec=60
+StartLimitBurst=10
+
+[Service]
+RestartSec=10
+Environment=NVIDIA_API_KEY=${NVIDIA_KEY}
+Environment=ANTHROPIC_API_KEY=${ACCESS_TOKEN}
+EOF
+log "Updated systemd override"
+
+# 4. Reload systemd (for env vars) but DO NOT restart the gateway.
+#    OpenClaw uses chokidar to watch openclaw.json — updating the file above
+#    triggers a hot reload automatically.  Restarting the gateway kills all
+#    active sessions (the root cause of the 0-turn session cascade on 2026-04-07).
+systemctl --user daemon-reload
+
+# Touch the config to ensure chokidar picks up the change (write already did,
+# but belt-and-suspenders in case the mtime didn't change fast enough).
+touch "$OPENCLAW_JSON"
+
+log "Token synced via hot reload (expires in ${REMAINING}h) — gateway NOT restarted, active sessions preserved"

package/scripts/release.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# Usage: ./scripts/release.sh [patch|minor|major|X.Y.Z]
+#
+# Bumps version in pyproject.toml AND package.json, commits, tags, and pushes.
+# Pushing the tag triggers the publish workflow (PyPI + npm).
+#
+# IMPORTANT: pyproject.toml version MUST match the tag — the workflow enforces this.
+#
+# Examples:
+#   ./scripts/release.sh patch        # 0.6.2 → 0.6.3
+#   ./scripts/release.sh minor        # 0.6.2 → 0.7.0
+#   ./scripts/release.sh 1.0.0        # set explicit version
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BUMP="${1:-patch}"
+
+# ── use existing bump_version.py for the actual bump ─────────────────────────
+
+BUMP_SCRIPT="$REPO_ROOT/scripts/bump_version.py"
+
+if [[ ! -f "$BUMP_SCRIPT" ]]; then
+    echo "ERROR: $BUMP_SCRIPT not found" >&2
+    exit 1
+fi
+
+# Dry-run first to show what will happen
+echo "Preview:"
+python3 "$BUMP_SCRIPT" "$BUMP" --pkg "$REPO_ROOT" --dry-run
+echo ""
+
+# Confirm
+read -rp "Proceed? [y/N] " confirm
+if [[ "$confirm" != "y" && "$confirm" != "Y" ]]; then
+    echo "Aborted."
+    exit 0
+fi
+
+# Get new version (run bump to get the number, without committing yet)
+NEW_VERSION=$(python3 -c "
+import re, sys
+sys.path.insert(0, '$REPO_ROOT/scripts')
+# Parse manually — same logic as bump_version.py
+text = open('$REPO_ROOT/pyproject.toml').read()
+m = re.search(r'^version\s*=\s*\"([^\"]+)\"', text, re.MULTILINE)
+current = m.group(1)
+part = '$BUMP'
+major, minor, patch = map(int, current.split('.'))
+if part == 'major':
+    print(f'{major+1}.0.0')
+elif part == 'minor':
+    print(f'{major}.{minor+1}.0')
+elif part == 'patch':
+    print(f'{major}.{minor}.{patch+1}')
+else:
+    parts = part.split('.')
+    if len(parts) != 3 or not all(p.isdigit() for p in parts):
+        raise ValueError(f'Invalid version: {part!r}')
+    print(part)
+")
+
+# Bump pyproject.toml and commit via bump_version.py
+python3 "$BUMP_SCRIPT" "$BUMP" --pkg "$REPO_ROOT"
+
+# Sync package.json to same version (workflow also does this, but keep file in sync)
+PACKAGE_JSON="$REPO_ROOT/package.json"
+python3 -c "
+import json
+with open('$PACKAGE_JSON') as f:
+    pkg = json.load(f)
+pkg['version'] = '$NEW_VERSION'
+with open('$PACKAGE_JSON', 'w') as f:
+    json.dump(pkg, f, indent=2)
+    f.write('\n')
+print(f'  Updated package.json to $NEW_VERSION')
+"
+
+cd "$REPO_ROOT"
+git add package.json
+git commit --amend --no-edit
+echo "  Amended commit to include package.json"
+
+TAG="v$NEW_VERSION"
+git tag -a "$TAG" -m "Release $TAG"
+echo "  Tagged: $TAG"
+
+echo ""
+echo "Pushing commit and tag to origin..."
+git push
+git push --tags
+
+echo ""
+echo "Done. GitHub Actions will now:"
+echo "  1. Run tests"
+echo "  2. Verify pyproject.toml version matches tag ($TAG)"
+echo "  3. Publish skcapstone $NEW_VERSION to PyPI"
+echo "  4. Publish @smilintux/skcapstone $NEW_VERSION to npm"

package/scripts/session-to-memory.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+session-to-memory.py — Extract an OpenClaw session jsonl and save a digest to skmemory.
+
+Usage:
+  python3 session-to-memory.py <session.jsonl> [--agent lumina] [--dry-run]
+
+Called by archive-sessions.sh before archiving each session file.
+Also useful to run manually against any archived session.
+"""
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+
+SKIP_PREFIXES = (
+    "[SKMemory",
+    "[System",
+    "[skmemory",
+    "--- SKMEMORY",
+    "--- SKWHISPER",
+)
+
+MAX_CONTENT_CHARS = 12000  # ~3k tokens — enough for a solid digest without blowing budget
+CLAUDE_MODEL = "claude-haiku-4-5"  # fast + cheap for digest work
+
+
+def extract_turns(path: Path) -> list[tuple[str, str]]:
+    """Parse a session jsonl and return real (role, text) turns, skipping injections."""
+    turns = []
+    with open(path, encoding="utf-8", errors="replace") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            if obj.get("type") != "message":
+                continue
+
+            # Handle both top-level message fields and nested .message
+            m = obj.get("message", obj)
+            role = m.get("role", "?")
+            content = m.get("content", "")
+
+            if isinstance(content, list):
+                text = " ".join(
+                    c.get("text", "")
+                    for c in content
+                    if isinstance(c, dict) and c.get("type") == "text"
+                )
+            else:
+                text = str(content)
+
+            text = text.strip()
+            if not text or len(text) < 5:
+                continue
+            if any(text.startswith(p) for p in SKIP_PREFIXES):
+                continue
+
+            turns.append((role, text))
+
+    return turns
+
+
+def turns_to_prompt(turns: list[tuple[str, str]], max_chars: int = MAX_CONTENT_CHARS) -> str:
+    """Format turns as a conversation snippet, truncated to max_chars."""
+    lines = []
+    for role, text in turns:
+        prefix = "Chef" if role == "user" else "Lumina"
+        lines.append(f"{prefix}: {text[:600]}")
+    full = "\n\n".join(lines)
+    if len(full) > max_chars:
+        full = full[:max_chars] + "\n\n[... truncated ...]"
+    return full
+
+
+def generate_digest(conversation: str, session_id: str) -> str:
+    """Use claude CLI to generate a session digest."""
+    prompt = f"""You are summarizing an OpenClaw AI agent session for the skmemory system.
+Session ID: {session_id}
+
+Conversation:
+{conversation}
+
+Write a concise session digest (3-6 sentences) covering:
+- Key topics discussed
+- Decisions made or actions taken
+- Any notable moments or outcomes
+
+Be specific. Use past tense. No preamble."""
+
+    try:
+        result = subprocess.run(
+            [
+                "claude", "--print",
+                "--dangerously-skip-permissions",
+                "--model", CLAUDE_MODEL,
+                "--output-format", "json",
+                "--no-session-persistence",
+            ],
+            input=prompt.encode(),
+            capture_output=True,
+            timeout=120,
+        )
+        if result.returncode != 0:
+            return f"[digest failed: {result.stderr.decode()[:200]}]"
+        parsed = json.loads(result.stdout.decode())
+        return parsed.get("result", "").strip()
+    except Exception as e:
+        return f"[digest error: {e}]"
+
+
+def save_to_skmemory(title: str, content: str, agent: str, tags: list[str]) -> bool:
+    """Save a memory snapshot via skmemory CLI."""
+    tag_str = ",".join(tags)
+    try:
+        result = subprocess.run(
+            [
+                "skmemory", "snapshot",
+                title, content,
+                "--layer", "mid-term",
+                "--tags", tag_str,
+            ],
+            capture_output=True,
+            timeout=30,
+            env={**os.environ, "SKAGENT": agent, "SKCAPSTONE_AGENT": agent},
+        )
+        if result.returncode != 0:
+            print(f"  [skmemory error] {result.stderr.decode()[:200]}", file=sys.stderr)
+            return False
+        return True
+    except Exception as e:
+        print(f"  [skmemory exception] {e}", file=sys.stderr)
+        return False
+
+
+def process_session(path: Path, agent: str = "lumina", dry_run: bool = False) -> bool:
+    session_id = path.stem[:8]
+
+    # Infer date from jsonl (first session entry)
+    session_date = None
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                obj = json.loads(line)
+                if obj.get("type") == "session":
+                    ts = obj.get("timestamp", "")
+                    if ts:
+                        session_date = ts[:10]
+                    break
+    except Exception:
+        pass
+
+    turns = extract_turns(path)
+    if not turns:
+        print(f"  No usable turns in {path.name} — skipping.")
+        return False
+
+    print(f"  {len(turns)} turns extracted from {path.name}")
+
+    date_str = session_date or datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    title = f"Session Digest — {date_str} ({session_id})"
+
+    if dry_run:
+        conv = turns_to_prompt(turns)
+        print(f"  [dry-run] Would save: {title}")
+        print(f"  Conversation preview ({len(conv)} chars):")
+        print(conv[:400])
+        return True
+
+    conversation = turns_to_prompt(turns)
+    print(f"  Generating digest via claude ({CLAUDE_MODEL})...")
+    digest = generate_digest(conversation, session_id)
+
+    if not digest or digest.startswith("[digest"):
+        print(f"  Digest generation failed: {digest}")
+        return False
+
+    content = f"**Session:** `{session_id}`  \n**Date:** {date_str}  \n**Turns:** {len(turns)}\n\n{digest}"
+    tags = ["auto-digest", "session-archive", f"session:{session_id}", f"agent:{agent}"]
+
+    print(f"  Saving memory: {title}")
+    ok = save_to_skmemory(title, content, agent, tags)
+    if ok:
+        print(f"  Saved to skmemory (mid-term).")
+    return ok
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract session to skmemory digest")
+    parser.add_argument("session_file", help="Path to session .jsonl file")
+    parser.add_argument("--agent", default="lumina", help="Agent name (default: lumina)")
+    parser.add_argument("--dry-run", action="store_true", help="Preview without saving")
+    args = parser.parse_args()
+
+    path = Path(args.session_file)
+    if not path.exists():
+        print(f"File not found: {path}", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Processing: {path.name}")
+    ok = process_session(path, agent=args.agent, dry_run=args.dry_run)
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/skgateway.mjs

@@ -404,7 +404,7 @@ const TOOL_GROUPS = {
   "chat|inbox|dm|group chat|peer|send message|who.s online|thread": [
     "skchat_send", "skchat_inbox", "skchat_history", "skchat_search",
     "skchat_who", "skchat_group_send", "skchat_group_list", "skchat_send_file",
-    "skchat_status", "skcomm_send", "skcomm_status",
+    "skchat_status", "skcomms_send", "skcomms_status",
   ],
   // Security
   "security|scan|secret|vulnerab|audit|injection|phishing|threat": [
@@ -429,7 +429,7 @@ const TOOL_GROUPS = {
   // Status & Health
   "status|health|doctor|diagnos": [
     "skcapstone_status", "skcapstone_doctor", "skmemory_health",
-    "skchat_daemon_status", "skcomm_status",
+    "skchat_daemon_status", "skcomms_status",
   ],
   // Projects & Notion (Lumina delegates to project-ops via sessions_spawn)
   "notion|project|brother john|swapseat|swap seat|chiro|davidrich|board|kanban|milestone": [
@@ -455,7 +455,7 @@ const PRIORITY_TOOLS = [
   // Web tools
   "web_search", "web_fetch",
   // Communication (other channels)
-  "skchat_send", "skcomm_send",
+  "skchat_send", "skcomms_send",
   // SKCapstone
   "skcapstone_status", "skcapstone_whoami", "skcapstone_mood",
   // Cloud 9

package/scripts/telegram-catchup-all.sh

@@ -22,7 +22,8 @@ set -uo pipefail  # no -e: individual group failures shouldn't stop the batch
 SKENV="${HOME}/.skenv/bin"
 SKCAPSTONE="${SKENV}/skcapstone"
 CONFIG="${HOME}/.skcapstone/agents/lumina/config/telegram.yaml"
-export SKCAPSTONE_AGENT="${SKCAPSTONE_AGENT:-lumina}"
+export SKAGENT="${SKAGENT:-lumina}"
+export SKCAPSTONE_AGENT="${SKAGENT}"
 export PATH="${SKENV}:${PATH}"
 
 # Parse args
@@ -39,6 +40,16 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+# Resolve relative date keywords (downstream CLI only accepts YYYY-MM-DD).
+# Anything else is passed through untouched so explicit dates still work.
+if [[ -n "$SINCE" ]]; then
+  case "$SINCE" in
+    yesterday) SINCE="$(date -u -d 'yesterday' +%Y-%m-%d)" ;;
+    today)     SINCE="$(date -u +%Y-%m-%d)" ;;
+    [0-9]*d)   SINCE="$(date -u -d "${SINCE%d} days ago" +%Y-%m-%d)" ;;
+  esac
+fi
+
 # Check prerequisites
 if [[ -z "${TELEGRAM_API_ID:-}" || -z "${TELEGRAM_API_HASH:-}" ]]; then
   echo "ERROR: TELEGRAM_API_ID and TELEGRAM_API_HASH must be set."

package/scripts/verify_install.sh

@@ -130,10 +130,10 @@ else
   fail "pip install skcapstone[dev]"
 fi
 
-# ── 5. Local sibling packages (skseed, skcomm) ─────────────────────────────
+# ── 5. Local sibling packages (skseed, skcomms) ─────────────────────────────
 echo
 echo "Step 5: local sibling packages (if present)"
-for pkg_dir in "$REPO_ROOT/../skseed" "$REPO_ROOT/../skcomm" "$REPO_ROOT/../skmemory" "$REPO_ROOT/../skskills"; do
+for pkg_dir in "$REPO_ROOT/../skseed" "$REPO_ROOT/../skcomms" "$REPO_ROOT/../skmemory" "$REPO_ROOT/../skskills"; do
   pkg_name=$(basename "$pkg_dir")
   if [[ -f "$pkg_dir/pyproject.toml" ]] || [[ -f "$pkg_dir/setup.py" ]]; then
     if "$PIP" install "${PIP_OPTS[@]}" -e "$pkg_dir" 2>&1; then

package/scripts/wargov-ufo-capture/README.md

@@ -0,0 +1,43 @@
+# war.gov/UFO/ PURSUE capture scripts
+
+Lumina-built CDP scripts for capturing war.gov/UFO/ PURSUE releases via the Lumina Chrome browser harness (port 9222). Akamai TLS-fingerprint gates direct curl, so capture has to drive a real browser session.
+
+## Quick reference
+
+| Script | What it does |
+|---|---|
+| `cdp_probe.py` | Open a tab on `war.gov/UFO/`, inspect the page meta + inline scripts to find the current CSV URL and any new release ZIP bundle. Run this first when a new release lands. |
+| `cdp_capture_release2.py` | Reference implementation of a full-release capture. Pulls the new CSV, downloads the ZIP bundle, and saves the press-release HTML. Per-release: edit `ZIP_URL`, `CSV_URL`, `PRESS_URL`, `DOC_DIR` constants. |
+| `parse_csv.py` | Parses the merged `uap-data.csv`, splits records by `Release Date`, produces `release-02-records.json` + `release-02-urls.json`. Run after CSV fetch. |
+| `pull_dvids.sh` | xargs-parallel-4 batch DVIDS puller. Reads `release-02-records.json`, fetches each DVIDS page, greps mp4 CDN URL, downloads. **Note:** DVIDS classifies UAP audio records as `/video/<id>` pages — always use `/video/` prefix, NOT `/audio/`. |
+| `cdp_finish.py` | Tail-end CDP script: re-extract press release `innerText`, page-context-fetch the 6 thumbnails (Akamai-gated to curl), and grab FBI Vault Part 15. |
+
+## Capture flow for a new release (Release 03 etc.)
+
+1. Confirm Lumina Chrome is up at :9222 (`~/bin/lumina-x-browser` to start).
+2. `python3 cdp_probe.py` — confirms the data source URL and looks for a ZIP-bundle path.
+3. Edit `cdp_capture_release2.py` constants for the new release: `ZIP_URL`, `CSV_URL`, `PRESS_URL`, `DOC_DIR`.
+4. `python3 cdp_capture_release2.py` — pulls CSV + ZIP + press-release HTML.
+5. `python3 parse_csv.py` — generates per-record inventory + URL set + DVIDS-only list.
+6. `bash pull_dvids.sh` — pulls all DVIDS media in parallel-4.
+7. `python3 cdp_finish.py` — re-extract press text (it picks the wrong selector on first pass), thumbnails, and any FBI Vault references.
+8. Update README.md at `~/nextcloud/cbrd21-share/reference/war-gov-UFO-PURSUE-2026/`.
+
+## Gotchas
+
+- **DVIDS audio → use `/video/` URL.** "Audio" UAP records are served from `dvidshub.net/video/<id>` with a static image. The `/audio/` path returns 404 for these IDs.
+- **Some DVIDS IDs are shared across records.** E.g., Release 02 ID `1007720` covers both DOW-UAP-PR057a and DOW-UAP-PR057b. Inventory may show N records but only N-1 unique IDs.
+- **Akamai bm tokens are per-session.** Cookies extracted from the browser will NOT work with curl — Akamai checks TLS fingerprint, not cookies. Stay in the browser.
+- **CSV name can change.** Release 01 used `uap-csv.csv`; when Release 02 shipped, it was renamed to `uap-data.csv`. Re-probe the inline scripts to find the current name.
+- **The ZIP bundle is PDFs only.** Don't skip DVIDS pulls just because you got the ZIP — videos/audio are not in the bundle.
+
+## Naming convention
+
+Match Release 01: `dvids-<id>-<UAP-PR-code>.mp4` (e.g. `dvids-1007706-DOW-UAP-PR050.mp4`). Cleaner than verbose slugs and matches existing on-disk corpus.
+
+## Output location
+
+`~/nextcloud/cbrd21-share/reference/war-gov-UFO-PURSUE-2026/`
+- `release-NN/` for media
+- `docs/release-NN/` for press release + CSV + manifest + thumbnails
+- `release-NN-zip/` for the official ZIP bundle if provided