The Trinity Beast — Kiro Command Center (KCC)

health

Checks all services — LPO health, LRS health, and cluster stats (3/3 nodes reporting). This is the first command run after every ECS deployment.

bash scripts/kcc.sh health

# Output:
# LPO:  ✅ [LPO] [us-east-2] [BeastMirror] [/health] [200]
# LRS:  ✅ [LRS] [us-east-2] [BeastLRS] [/health] [200]
# Cluster: Nodes: 3/3
#   BeastMain: published 2026-04-26T19:04:29Z
#   BeastMirror: published 2026-04-26T19:04:29Z
#   BeastLRS: published 2026-04-26T19:04:28Z

sync-check

Verifies the last nightly sync job ran successfully. Pulls the most recent log stream from CloudWatch (/aws/ecs/trinity-beast-sync) and displays run time (EST), completion status, duration, cache totals, and per-category sync counts (price logs, usage logs, API keys, app params, cleanup). Run this every morning right after health.

bash scripts/kcc.sh sync-check

# Output:
# Run Time:   April 28, 2026 at 01:00 AM EST
#
# Status:     ✅ Sync complete
# Duration:   186.909018ms
# Cache:      3285260 logs in Cache
#
# Sync Results:
#   Price logs:    72 new logs loaded
#   Usage logs:    19 entries written to Cache
#   API keys:      2 keys written to Cache
#   App params:    60 params written to Cache
#   Cleanup:       🟢 Pruned 0 old logs (>93 days)

verify

Hits 16 key endpoints (6 public + 10 admin) and reports the HTTP status code for each. Used after major changes to confirm nothing is broken.

bash scripts/kcc.sh verify

# Output:
# Public Endpoints:
#   ✅ GET /health (LPO) — 200
#   ✅ GET /health (LRS) — 200
#   ✅ GET /exchanges — 200
#   ✅ GET /asset-categories — 200
#   ...
# Admin Endpoints:
#   ✅ GET /admin/config — 200
#   ✅ GET /admin/cluster-stats — 200
#   ...

cluster-stats

Returns the full cluster-wide metrics snapshot — all 24 counters aggregated across all 4 containers via ElastiCache pipeline read.

bash scripts/kcc.sh cluster-stats

payment-links

Shows all 16 payment links with their enabled status, click counts, and Stripe URLs. Used to verify link configuration before and after Stripe setup.

bash scripts/kcc.sh payment-links

# Output:
# Total: 16 links
# Type            Tier                 Enabled    Clicks   URL
# subscription    pro                  ✅          42       https://buy.stripe.com/xxx...

feed-status

Shows the connection status of all 6 exchange WebSocket feeds with subscription counts and stale asset counts.

bash scripts/kcc.sh feed-status

# Output:
# coinbase_ws     ✅ Connected          Subs: 12  Stale: 0
# gemini_ws       ✅ Connected          Subs: 12  Stale: 0
# kraken_ws       ✅ Connected          Subs: 12  Stale: 0
# gateio_ws       ✅ Connected          Subs: 12  Stale: 0
# cryptocom_ws        ✅ Connected          Subs: 12  Stale: 0
# okx_ws          ✅ Connected          Subs: 12  Stale: 0

deploy-ecs

Full ECS deployment pipeline — Docker build (no-cache), ECR tag, ECR push, force deploy all 4 services. The most common deployment command.

bash scripts/kcc.sh deploy-ecs

# Builds → Tags → Pushes → Force deploys main, mirror, LRS
# Then: bash scripts/kcc.sh health (after ~40s)

deploy-site <file(s)>

Uploads HTML files to S3 and invalidates CloudFront. Automatically strips the cpmp-redesign/ prefix to determine the S3 path.

bash scripts/kcc.sh deploy-site cpmp-redesign/docs/Trinity-Beast-API-Reference.html
bash scripts/kcc.sh deploy-site cpmp-redesign/subscribe-listener.html cpmp-redesign/docs/index.html

profiles

Lists all 16 system profiles with their key parameters (QPS, burst, TTL, DB pool size).

bash scripts/kcc.sh profiles

config

Shows the current application parameters — cache TTL, prewarm intervals, pool sizes, demo key, etc.

bash scripts/kcc.sh config

daily-collect

Collects all infrastructure metrics (endpoints, feeds, cluster, Valkey, Lambda, sync, SQS queue, website analytics) and stores them as a single JSON blob in Valkey (kcc:daily key, 24h TTL). This is the data source for both the CLI daily command and the KCC Live Dashboard.

bash scripts/kcc.sh daily-collect

daily

Renders the compact daily status dashboard from the Valkey cache. If no cached data exists, it auto-runs daily-collect first. Shows services, ECS nodes, Valkey health, Lambda, nightly sync, SQS queue depth, and 7-day website analytics.

bash scripts/kcc.sh daily

# Output:
# ════════════════════
#  KCC — May 02 02:11PM EDT
# ════════════════════
# ─── Services ───
# ✅ LPO  ✅ LRS  ✅ Web
# Cluster: 3/3
# ─── SQS Usage Queue ───
# ✅ Pending: 0  In-flight: 0
# ─── Website (7d) ───
# Total 14,250 2.2GB  Avg 2,035/day

security

Security dashboard — CloudFront WAF (24h blocks), API WAF (per-rule breakdown), GuardDuty threat detection, CloudWatch security alarms, and application rate limiting stats.

bash scripts/kcc.sh security

force-deploy

Reloads all application parameters from Aurora → local cache + ElastiCache, re-parses prewarm asset lists, flushes prices, and resets all timers across all containers. Use after changing application_parameters in the database.

bash scripts/kcc.sh force-deploy

prewarm-audit

Validates all 169 prewarm assets across 6 exchanges against their live APIs. Reports any dead/delisted assets that need replacement. Run periodically — exchanges delist and rebrand assets more often than expected.

bash scripts/kcc.sh prewarm-audit

# Output:
# ✅ COINBASE   26/26 OK
# ✅ CRYPTOCOM  24/24 OK
# ✅ GATEIO     24/24 OK
# ✅ GEMINI     25/25 OK
# ✅ KRAKEN     26/26 OK
# ✅ OKX        36/36 OK

sync-icons

Fetches the top 750 coins by market cap from CoinGecko's free API, matches by symbol against enabled EAM assets, and populates icon_url for any asset missing one. Icons are served to subscribers via the /asset-categories response and displayed in the demo dropdown.

bash scripts/kcc.sh sync-icons

# Output:
#   Mode: Fill missing icons only
#   Assets needing icons: 37
#   Fetching CoinGecko market data...
#     Page 1/3... 250 coins
#     Page 2/3... 250 coins
#     Page 3/3... 250 coins
#   CoinGecko unique symbols: 712
#   Matched: 28 | Still missing: 9
#   Writing 28 icon URLs to Aurora... ✅ 28 rows updated (42ms)

# Use --force to overwrite all existing icon URLs:
bash scripts/kcc.sh sync-icons --force

build-search

Rebuilds the multi-lingual full-text search index from all 32 documents across 12 languages (384 total) plus daily operations reports (English only, 30-day rolling archive). Fetches each doc from CloudFront, parses HTML into sections, and stores per-language indexes in Valkey. Run after deploying new or updated documents. The nightly sync also triggers this automatically.

Search features: Paginated results (9 per page), multi-lingual scoring, daily report indexing, and an interactive Search Demo showing the English → Japanese flow.

bash scripts/kcc.sh build-search

push-langs

Pushes all 12 language JSON files from cpmp-redesign/lang/ to Valkey (lang:{code} keys). The i18n system's primary source is the API (/public/lang/{code}), which reads from Valkey. If language files are edited locally and deployed to S3 but NOT pushed to Valkey, the API serves stale data and new i18n keys won't appear on the website. Run after any edit to language JSON files.

bash scripts/kcc.sh push-langs

delta-validate <doc>

Validates that TBI-CHUNK markers are preserved through the translation reassembly pipeline for a given document. Checks that chunk count in the source matches chunk count in the reassembled output. Run before submitting a document to the translation engine to confirm chunk integrity.

bash scripts/kcc.sh delta-validate Trinity-Beast-API-Reference.html

# Output:
# Source chunks:  12
# Output chunks:  12
# ✅ Chunk markers preserved — safe to submit

chunk-size <doc>

Scans a document and reports the size of each chunk between TBI-CHUNK markers. Flags any chunks that exceed the translation engine's size policy (15 KB baseline, 18 KB max, 12 KB for dense/code-heavy sections). Also suggests where to add new markers if any chunk is over-limit. Run before submitting large or recently updated documents to the translation engine.

bash scripts/kcc.sh chunk-size cpmp-redesign/docs/Trinity-Beast-API-Reference.html

# Output:
# Chunk 1:  11.2 KB  ✅
# Chunk 2:  14.8 KB  ✅
# Chunk 3:  17.1 KB  ⚠️  approaching limit
# Chunk 4:   9.3 KB  ✅
# Chunk 5:  19.4 KB  🛑  OVER LIMIT — add TBI-CHUNK near line 412

trace-ip <ip_address>

Forensic trace of an IP address — WAF blocks (last 24h sampled requests) and usage logs from Aurora. Shows what the IP was doing and whether WAF caught it.

bash scripts/kcc.sh trace-ip 45.148.10.247

trace-key <api_key_id>

Forensic trace of an API key — owner details (email, name, tier), recent activity (last 50 calls), and unique IPs used.

bash scripts/kcc.sh trace-key demo-public-2026-03-01-abc123

trace-email <email>

Full account trace — user account, API keys, transactions, and support tickets for an email address.

bash scripts/kcc.sh trace-email user@example.com

threat-log

Shows WAF blocks by rule (last 24h) and GuardDuty findings (severity ≥ MEDIUM). Quick threat visibility without the full security dashboard.

bash scripts/kcc.sh threat-log

threat-status

Current defense posture — manually blocked IPs (WAF IP set) and any firing CloudWatch alarms.

bash scripts/kcc.sh threat-status

block-ip <ip_address>

Adds an IP to the WAF block list (trinity-beast-blocked-ips IP set). Creates the IP set if it doesn't exist. Immediate effect — all requests from this IP get 403.

bash scripts/kcc.sh block-ip 1.2.3.4

unblock-ip <ip_address>

Removes an IP from the WAF block list.

bash scripts/kcc.sh unblock-ip 1.2.3.4

kill-key <api_key_id>

Immediately revokes an API key — sets status to 'revoked' in Aurora and deletes the cached key from ElastiCache. All subsequent requests with this key get 403 Forbidden.

bash scripts/kcc.sh kill-key abc123-compromised-key

warn-subscriber <api_key_id> "reason"

Sends a threat warning email to the subscriber who owns the specified API key. Uses the ThreatWarning SES template. Does not revoke the key — this is a first-strike warning.

bash scripts/kcc.sh warn-subscriber abc123-key "Unusual request patterns detected from your API key"

terminate-subscriber <api_key_id> "reason"

Full subscriber termination — revokes key, cancels Stripe subscription (prorated refund), blocks all source IPs, and sends termination notice via SES. Irreversible. Generates a violation ID for audit trail.

bash scripts/kcc.sh terminate-subscriber abc123-key "Repeated abuse after warning"

rotate-admin-key

Generates a new admin key, updates Aurora application_parameters, flushes the old key from Valkey, force-deploys params to all containers, and self-updates the KCC script. The old key is immediately invalid. Use when the admin key may be compromised.

After rotation, only 2 files need manual update: ume.py (Python canonical source) and the steering file. All 14 helpers and legacy scripts inherit automatically. See Section 3 — Credential Centralization for the full propagation map.

bash scripts/kcc.sh rotate-admin-key

# Output:
# Old key: tbcc-admin-ec...e380
# New key: tbcc-admin-7f3a...b291
# [1/4] Updating Aurora application_parameters...
# [2/4] Flushing old key from Valkey...
# [3/4] Force deploying params to all containers...
# [4/4] Updating KCC script with new key...
# ✅ Admin key rotated successfully
#
# Post-rotation (manual):
#   1. Update ume.py fallback value
#   2. Update kiro-command-center.md steering
#   3. Update 6 Lambda env vars (aws lambda update-function-configuration)
#   4. Update 2 ECS task definitions (sync job + translate worker)

lockdown-admin <your_ip>

Creates a WAF rule (priority 0 — highest) that blocks ALL /admin/* requests unless they originate from the specified IP. Emergency use — locks out everyone except you. To find your IP: curl -s ifconfig.me

bash scripts/kcc.sh lockdown-admin 73.42.156.89

# Only 73.42.156.89 can now reach /admin/* endpoints
# All other IPs get blocked at WAF before reaching the server

unlock-admin

Removes the admin lockdown WAF rule, restoring normal admin access for all authenticated requests.

bash scripts/kcc.sh unlock-admin

block-country "<country_codes>"

Adds a geo-match WAF rule to the ALB that blocks ALL traffic from specified countries (ISO 3166-1 alpha-2 codes). Idempotent — running again replaces the previous list. Use during sustained regional attacks.

bash scripts/kcc.sh block-country "RU CN"
bash scripts/kcc.sh block-country "RU CN IR KP"

unblock-country

Removes the country geo-block rule entirely, allowing all geographic traffic.

bash scripts/kcc.sh unblock-country

release-notes "<note>"

Appends a release note to the weekly accumulator in Valkey (autoops:release-notes:week). These notes are read by the digest Lambda on Monday morning and included as a "What's New" section in the weekly subscriber newsletter. Run at the end of each session to capture subscriber-facing improvements.

bash scripts/kcc.sh release-notes "Branded HTML email notifications for all AutoOps alerts"

# Output:
# ✅ Release note added (#3 this week)
#    Branded HTML email notifications for all AutoOps alerts

release-notes-show

Shows all accumulated release notes for the current week. Use to review what will appear in Monday's newsletter.

bash scripts/kcc.sh release-notes-show

# Output:
# 1. [2026-05-10] Branded HTML email notifications via SES
# 2. [2026-05-10] SNS-to-Lambda notification pipeline
# 3. [2026-05-10] Weekly newsletter Gmail-compatible dark theme
#
# Total: 3 notes

release-notes-clear

Clears all accumulated release notes. Done automatically after the weekly newsletter sends successfully. Manual use only needed if you want to start fresh mid-week.

bash scripts/kcc.sh release-notes-clear

doc-publish <file> --reason "what changed"

Deploys an English document to S3, invalidates CloudFront, updates the doc registry in Valkey, queues for translation, and triggers a search index rebuild. One command handles the entire publish pipeline.

bash scripts/kcc.sh doc-publish Trinity-Beast-API-Reference.html --reason "Added EAM endpoints"

session-close <N> "<summary>"

Finalizes a session report — uploads to S3, appends to the session log in Valkey (docs:session:log), and writes the plain-text version for the weekly newsletter (report:text:YYYY-MM-DD).

bash scripts/kcc.sh session-close 2 "UME helper migration, doc updates, steering cleanup"

translate-pending [--list]

Without flags: validates all queued docs' Mermaid diagrams, then submits to the translation engine in batches of 6. With --list: shows the pending queue without submitting. Reads from docs:pending:translation sorted set.

bash scripts/kcc.sh translate-pending --list

# Output:
# 39 docs pending translation:
#   Trinity-Beast-API-Reference.html — "Added EAM endpoints" (2026-06-11)
#   Trinity-Beast-Go-Application-Features.html — "Multi-provider Bedrock" (2026-06-07)
#   ...

doc-registry [--pending | --status <file>]

Shows the full document registry (44 docs: ✓ current / ⏳ pending / ★ new). Use --pending to see only docs queued for translation, or --status <file> for a single doc's entry.

bash scripts/kcc.sh doc-registry --pending

POST /admin/translate — Submit a Translation Job

Enqueues a translation job. The engine handles everything: sentinel preprocessing, Bedrock translation, S3 deployment, CloudFront invalidation, search index rebuild, and email notification. Fire and forget — one API call does it all.

# Single document, all 11 languages
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"docs":["Trinity-Beast-API-Reference.html"],"langs":"all"}' \
  "$LPO_BASE/admin/translate" | jq .

# Multiple documents, specific languages
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"docs":["Trinity-Beast-API-Reference.html","Trinity-Beast-Architecture-Guide.html"],"langs":["es","pt","fr"]}' \
  "$LPO_BASE/admin/translate" | jq .

# Delta mode — skip pairs where translated S3 file is newer than source (saves up to 90%)
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"docs":["Trinity-Beast-API-Reference.html"],"langs":"all","options":{"delta":true}}' \
  "$LPO_BASE/admin/translate" | jq .

# With idempotency key (safe to retry)
curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" -H "X-Idempotency-Key: api-ref-2026-05-27" \
  -H "Content-Type: application/json" \
  -d '{"docs":["Trinity-Beast-API-Reference.html"],"langs":"all"}' \
  "$LPO_BASE/admin/translate" | jq .

Limits: Max 6 docs per request (multiples-of-3 convention). Max 3 active jobs (additional queue in SQS, depth 12). Max 12 languages per request. Typical cost: ~$1.65 per doc-language pair, ~$18 for 1 doc × 11 langs.

GET /admin/translate/status/{job_id} — Monitor Progress

Real-time per-pair progress from Valkey. Shows each language pair's status (pending, in_progress, completed, failed), token counts, and cost.

curl -s -H "X-Admin-Key: $ADMIN_KEY" "$LPO_BASE/admin/translate/status/{job_id}" | jq .

GET /admin/translate/queue — Active Queue

Shows all active and queued jobs with their current state.

curl -s -H "X-Admin-Key: $ADMIN_KEY" "$LPO_BASE/admin/translate/queue" | jq .

GET /admin/translate/health — System Health

Translation engine health snapshot — daily spend, token usage (input + output vs 50M limit), active job count, queue depth. The KCC Live Dashboard also shows this data in the Translation Engine card.

curl -s -H "X-Admin-Key: $ADMIN_KEY" "$LPO_BASE/admin/translate/health" | jq .

# Key fields in response:
# daily_spend_usd        — dollars spent today
# daily_input_tokens     — input tokens consumed today
# daily_output_tokens    — output tokens consumed today
# daily_token_limit      — 50,000,000 (50M combined cap)
# active_jobs            — currently running Step Functions
# queue_depth            — jobs waiting in SQS

GET /admin/translate/history — Job History

Last 50 completed jobs from Aurora — the permanent ledger. Includes job ID, docs, languages, total cost, duration, and completion time.

curl -s -H "X-Admin-Key: $ADMIN_KEY" "$LPO_BASE/admin/translate/history" | jq .

POST /admin/translate/cancel/{job_id} — Cancel a Job

Stops the Step Function immediately. Already-completed pairs are not rolled back — S3 files written before cancellation remain.

curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" "$LPO_BASE/admin/translate/cancel/{job_id}"

POST /admin/translate/retry-failed/{job_id} — Retry Failed Pairs

Retries only the failed language pairs from a partial job. Successful pairs are not re-translated. Cost-efficient recovery from partial failures.

curl -s -X POST -H "X-Admin-Key: $ADMIN_KEY" "$LPO_BASE/admin/translate/retry-failed/{job_id}"

chunk-size <doc> — Verify Chunk Sizes

Reports the size of each chunk between TBI-CHUNK markers. Policy: 15 KB baseline, 18 KB max, 12 KB for dense/code-heavy sections. Flags over-limit chunks and suggests where to add markers. Do not submit and hope — verify first.

bash scripts/kcc.sh chunk-size cpmp-redesign/docs/Trinity-Beast-API-Reference.html

delta-validate <doc> — Verify Chunk Marker Integrity

Confirms that TBI-CHUNK markers survive the translation reassembly pipeline. Chunk count in source must match chunk count in output. Run before submitting documents that have been recently edited.

bash scripts/kcc.sh delta-validate Trinity-Beast-API-Reference.html