@littlebearapps/platform-admin-sdk 1.1.1 → 1.4.0

package/README.md

@@ -4,6 +4,16 @@
 
 Generates workers, D1 migrations, and config files. Run once, then you own the code.
 
+> **Using Claude Code?** Install the [Platform SDK Plugin](https://github.com/littlebearapps/platform-sdk-plugin) for automated SDK convention enforcement — it validates wrangler bindings, budget wrappers, and cost safety patterns in real time.
+
+## Prerequisites
+
+- **Node.js 20+** and npm
+- **wrangler CLI** installed and authenticated (`npx wrangler whoami`)
+- **Cloudflare Workers Paid plan** (required for KV, Queues, and D1)
+- **GitHub organisation** (Standard/Full tiers — for error collection GitHub issues)
+- **Gatus instance** (optional — for heartbeat monitoring)
+
 ## Usage
 
 ```bash
@@ -17,9 +27,12 @@ The CLI prompts for:
 - **Gatus URL** (optional) — for heartbeat monitoring
 - **Default assignee** — GitHub username for error issues
 
-### CLI Flags (non-interactive)
+### CLI Commands
+
+#### `scaffold` (default)
 
 ```bash
+npx @littlebearapps/platform-admin-sdk my-platform
 npx @littlebearapps/platform-admin-sdk my-platform --tier full --github-org myorg --skip-prompts
 ```
 
@@ -31,6 +44,27 @@ npx @littlebearapps/platform-admin-sdk my-platform --tier full --github-org myor
 | `--default-assignee <user>` | Default GitHub issue assignee |
 | `--skip-prompts` | Fail if required flags missing (for CI/automation) |
 
+#### `upgrade`
+
+```bash
+npx @littlebearapps/platform-admin-sdk upgrade
+npx @littlebearapps/platform-admin-sdk upgrade --dry-run
+npx @littlebearapps/platform-admin-sdk upgrade --tier standard
+```
+
+| Flag | Description |
+|------|------------|
+| `--dry-run` | Preview changes without writing files |
+| `--tier <tier>` | Upgrade to a higher tier |
+
+#### `adopt`
+
+```bash
+npx @littlebearapps/platform-admin-sdk adopt . --tier minimal --project-name my-platform --skip-prompts
+```
+
+Creates a `.platform-scaffold.json` manifest for projects scaffolded before v1.1.0. See [Upgrade vs Adopt](#upgrade-vs-adopt).
+
 ## Tiers
 
 | Tier | Workers | What You Get | Est. Cost |
@@ -39,69 +73,159 @@ npx @littlebearapps/platform-admin-sdk my-platform --tier full --github-org myor
 | **Standard** | 3 | + Error collector (auto GitHub issues), gap detection sentinel | ~$0/mo |
 | **Full** | 8 | + AI pattern discovery, alert router, notifications, search, settings | ~$5/mo |
 
+See [Tier Comparison](../../docs/admin-sdk/tiers.md) for a detailed breakdown of what each tier generates.
+
 ## What Gets Generated
 
 ### All tiers
 
 ```
 my-platform/
-+-- platform/config/
-|   +-- services.yaml          # Project registry, feature definitions
-|   +-- budgets.yaml           # Daily limits, circuit breaker thresholds
-+-- storage/d1/migrations/     # D1 schema (4 core migrations + seed)
-+-- workers/
-|   +-- platform-usage.ts      # Data warehouse worker (cron + queue consumer)
-|   +-- lib/                   # Shared libraries (billing, analytics, budgets)
-+-- scripts/
-|   +-- sync-config.ts         # Sync YAML config to D1/KV
-+-- wrangler.*.jsonc           # Worker configs with binding placeholders
-+-- package.json
-+-- tsconfig.json
-+-- README.md
+├── platform/config/
+│   ├── services.yaml          # Project registry, feature definitions
+│   └── budgets.yaml           # Daily limits, circuit breaker thresholds
+├── storage/d1/migrations/     # D1 schema (4 core migrations + seed)
+├── workers/
+│   ├── platform-usage.ts      # Data warehouse worker (cron + queue consumer)
+│   └── lib/                   # Shared libraries (billing, analytics, budgets)
+├── docs/
+│   └── kv-key-patterns.md     # KV key prefix reference
+├── scripts/
+│   └── sync-config.ts         # Sync YAML config to D1/KV
+├── wrangler.*.jsonc           # Worker configs with binding placeholders
+├── package.json
+├── tsconfig.json
+└── README.md
 ```
 
+### Key generated files
+
+| File | Purpose |
+|------|---------|
+| `platform/config/services.yaml` | Project registry — feature definitions, connections, metadata |
+| `platform/config/budgets.yaml` | Daily limits, circuit breaker thresholds, warning percentages |
+| `storage/d1/migrations/001_*.sql` | Core tables: project registry, resource snapshots, daily rollups |
+| `workers/platform-usage.ts` | Central data warehouse — receives queue telemetry, stores in D1 |
+| `scripts/sync-config.ts` | Syncs YAML config to D1 + KV (run after config changes) |
+
 ### Standard tier adds
 
-- `workers/error-collector.ts` — Tail worker that creates GitHub issues from errors
-- `workers/platform-sentinel.ts` — Gap detection, cost monitoring, alerts
-- `workers/lib/error-collector/` — Fingerprinting, deduplication, digest
-- `workers/lib/sentinel/` — Project gap detection
-- `storage/d1/migrations/005_error_collection.sql`
+| File | Purpose |
+|------|---------|
+| `workers/error-collector.ts` | Tail worker — creates GitHub issues from worker errors |
+| `workers/platform-sentinel.ts` | Gap detection, cost monitoring, alerts |
+| `workers/lib/error-collector/` | Fingerprinting, deduplication, digest generation |
+| `workers/lib/sentinel/` | Per-project gap detection |
+| `storage/d1/migrations/005_error_collection.sql` | Error tables: occurrences, fingerprint decisions, digests |
 
 ### Full tier adds
 
-- `workers/pattern-discovery.ts` — AI-assisted transient error pattern discovery
-- `workers/platform-alert-router.ts` — Unified alert normalisation and routing
-- `workers/platform-notifications.ts` — In-app notification API
-- `workers/platform-search.ts` — Full-text search (FTS5)
-- `workers/platform-settings.ts` — Settings management API
-- `workers/lib/pattern-discovery/` — Clustering, AI prompts, validation, shadow eval
-- `storage/d1/migrations/006_pattern_discovery.sql`
-- `storage/d1/migrations/007_notifications_search.sql`
+| File | Purpose |
+|------|---------|
+| `workers/pattern-discovery.ts` | AI-assisted transient error pattern discovery |
+| `workers/platform-alert-router.ts` | Unified alert normalisation and routing |
+| `workers/platform-notifications.ts` | In-app notification API |
+| `workers/platform-search.ts` | Full-text search (FTS5) |
+| `workers/platform-settings.ts` | Settings management API |
+| `workers/lib/pattern-discovery/` | Types, clustering, AI prompts, validation, shadow evaluation |
+| `storage/d1/migrations/006_pattern_discovery.sql` | Pattern tables |
+| `storage/d1/migrations/007_notifications_search.sql` | Notification and search tables |
 
 ## Post-Scaffold Steps
 
+### 1. Install dependencies
+
 ```bash
 cd my-platform
 npm install
+```
 
-# Create Cloudflare resources
+### 2. Create Cloudflare resources
+
+**All tiers:**
+
+```bash
 npx wrangler d1 create my-platform-metrics
 npx wrangler kv namespace create PLATFORM_CACHE
 npx wrangler queues create my-platform-telemetry
 npx wrangler queues create my-platform-telemetry-dlq
+```
+
+**Standard tier** — also create:
+
+```bash
+npx wrangler kv namespace create PLATFORM_ALERTS
+```
 
-# Update resource IDs in wrangler.*.jsonc, then:
+**Full tier** — also create:
+
+```bash
+npx wrangler kv namespace create SERVICE_REGISTRY
+```
+
+Update the resource IDs in each `wrangler.*.jsonc` file.
+
+### 3. Configure secrets
+
+```bash
+# Standard tier — error-collector (GitHub App for auto-issue creation)
+npx wrangler secret put GITHUB_APP_ID -c wrangler.my-platform-error-collector.jsonc
+npx wrangler secret put GITHUB_APP_PRIVATE_KEY -c wrangler.my-platform-error-collector.jsonc
+npx wrangler secret put GITHUB_APP_INSTALLATION_ID -c wrangler.my-platform-error-collector.jsonc
+
+# Standard tier — sentinel (Cloudflare API for cost monitoring)
+npx wrangler secret put CLOUDFLARE_API_TOKEN -c wrangler.my-platform-sentinel.jsonc
+
+# Optional — Slack alerts (any worker with SLACK_WEBHOOK_URL)
+npx wrangler secret put SLACK_WEBHOOK_URL -c wrangler.my-platform-sentinel.jsonc
+
+# Full tier — alert-router (GitHub token for issue creation)
+npx wrangler secret put GITHUB_TOKEN -c wrangler.my-platform-alert-router.jsonc
+npx wrangler secret put SLACK_WEBHOOK_URL -c wrangler.my-platform-alert-router.jsonc
+```
+
+### 4. Apply migrations and deploy
+
+```bash
+# Sync config to D1/KV
 npm run sync:config
+
+# Apply D1 migrations
 npx wrangler d1 migrations apply my-platform-metrics --remote
+
+# Deploy workers (order matters — deploy usage first, then tail consumers)
 npx wrangler deploy -c wrangler.my-platform-usage.jsonc
+
+# Standard tier
+npx wrangler deploy -c wrangler.my-platform-error-collector.jsonc
+npx wrangler deploy -c wrangler.my-platform-sentinel.jsonc
+
+# Full tier
+npx wrangler deploy -c wrangler.my-platform-notifications.jsonc
+npx wrangler deploy -c wrangler.my-platform-search.jsonc
+npx wrangler deploy -c wrangler.my-platform-settings.jsonc
+npx wrangler deploy -c wrangler.my-platform-pattern-discovery.jsonc
+npx wrangler deploy -c wrangler.my-platform-alert-router.jsonc
 ```
 
-## Updating Your Platform
+See [Quickstart Guide](../../docs/admin-sdk/quickstart.md) for a detailed walkthrough.
+
+## The Manifest File
+
+When you scaffold or upgrade, the SDK writes a `.platform-scaffold.json` file. **Commit this to git** — it's how `upgrade` knows what to update.
 
-Starting with v1.1.0, the Admin SDK writes a `.platform-scaffold.json` manifest that tracks what was generated. This enables safe, incremental upgrades.
+The manifest contains:
+- **`sdkVersion`** — Version of the Admin SDK that generated the files
+- **`tier`** — Infrastructure tier (minimal/standard/full)
+- **`context`** — Project name, slug, organisation, and other scaffold-time settings
+- **`files`** — SHA-256 hash of each generated file as originally written
+- **`highestScaffoldMigration`** — Highest D1 migration number generated
 
-### Upgrade an existing project
+The `files` hash map is the basis for the three-way merge during `upgrade`: if your current disk content matches the original hash, the file is "unmodified" and can be safely updated. If the disk content differs, you've customised it and `upgrade` skips it with a warning.
+
+## Updating Your Platform
+
+### Upgrade (v1.1.0+)
 
 ```bash
 cd my-platform
@@ -110,9 +234,9 @@ npx @littlebearapps/platform-admin-sdk upgrade
 
 The upgrade command:
 - **Creates** new files added in the SDK update
-- **Updates** files you haven't modified (compares content hashes)
-- **Skips** files you've customised (with a warning)
-- **Renumbers** new migrations to avoid conflicts with your own
+- **Updates** files you haven't modified (compares content hashes from manifest)
+- **Skips** files you've customised (with a warning showing which files were skipped)
+- **Renumbers** new D1 migrations above your highest existing migration
 
 Preview changes without writing:
 
@@ -126,15 +250,22 @@ Upgrade to a higher tier:
 npx @littlebearapps/platform-admin-sdk upgrade --tier standard
 ```
 
-### Adopt a pre-v1.1.0 project
-
-Projects scaffolded before v1.1.0 don't have a manifest. Run `adopt` first:
+### Upgrade vs Adopt
 
-```bash
-npx @littlebearapps/platform-admin-sdk adopt . --tier minimal --project-name my-platform --skip-prompts
 ```
+Do you have .platform-scaffold.json in your project?
+│
+├── YES → Run: npx @littlebearapps/platform-admin-sdk upgrade
+│         (three-way merge using manifest hashes)
+│
+└── NO  → Run: npx @littlebearapps/platform-admin-sdk adopt . --tier <your-tier>
+          (creates manifest by hashing existing files as baseline)
+          Then run: npx @littlebearapps/platform-admin-sdk upgrade
+```
+
+Projects scaffolded before v1.1.0 don't have a manifest. The `adopt` command hashes your existing SDK-generated files as the "original" state, creating a baseline for future upgrades.
 
-This hashes your existing files as a baseline and writes `.platform-scaffold.json`. You can then run `upgrade` normally.
+See [Upgrade Guide](../../docs/admin-sdk/upgrade-guide.md) for detailed instructions.
 
 ## Data Safety
 
@@ -151,20 +282,43 @@ The scaffolder generates core infrastructure only. It does **not** create:
 - Email workers or notification templates
 - Data connectors (Stripe, GA4, Plausible, etc.)
 - Test suites
-- CI/CD workflows
+- CI/CD workflows (use the [consumer-check.yml](../../docs/admin-sdk/ci-workflow.md) reusable workflow)
 
 These are project-specific — build them as you need them.
 
-## Consumer SDK
+## Consumer SDK Integration
 
-The generated workers use `@littlebearapps/platform-consumer-sdk` — the Consumer SDK. Install it in your application workers to send telemetry to the platform backend:
+The generated backend workers use `@littlebearapps/platform-consumer-sdk` internally. To connect your application workers, install the Consumer SDK and add the required bindings:
 
 ```bash
 npm install @littlebearapps/platform-consumer-sdk
 ```
 
-See the [Consumer SDK README](../consumer-sdk/README.md) for integration details.
+Add to each application worker's `wrangler.jsonc`:
+
+```jsonc
+{
+  "kv_namespaces": [
+    { "binding": "PLATFORM_CACHE", "id": "YOUR_KV_NAMESPACE_ID" }
+  ],
+  "queues": {
+    "producers": [
+      { "binding": "TELEMETRY_QUEUE", "queue": "my-platform-telemetry" }
+    ]
+  },
+  // Standard/Full tier — route errors to error-collector
+  "tail_consumers": [
+    { "service": "my-platform-error-collector" }
+  ]
+}
+```
+
+See the [Consumer SDK README](../consumer-sdk/README.md) for integration details and the [First Worker tutorial](../../docs/guides/first-worker.md) for a complete walkthrough.
+
+## Multi-Account Support
+
+The Admin SDK's programmatic API accepts `accountId` and `apiToken` per call, enabling cross-account monitoring and emergency control from a single script or worker. See the [Multi-Account Setup guide](../../docs/guides/multi-account.md) for architecture patterns.
 
-## License
+## Licence
 
-MIT
+MIT — Made with ❤️ by [Little Bear Apps](https://littlebearapps.com) 🐶

package/dist/scaffold.js

@@ -45,6 +45,9 @@ export async function scaffold(options, outputDir) {
         gatusUrl: options.gatusUrl,
         defaultAssignee: options.defaultAssignee,
         sdkVersion: SDK_VERSION,
+        // Computed flags for Handlebars conditionals in templates
+        isStandard: (options.tier === 'standard' || options.tier === 'full') ? 'true' : '',
+        isFull: options.tier === 'full' ? 'true' : '',
     };
     mkdirSync(outputDir, { recursive: true });
     const fileHashes = {};

package/dist/templates.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Tier } from './prompts.js';
 /** Single source of truth for the SDK version. */
-export declare const SDK_VERSION = "1.1.1";
+export declare const SDK_VERSION = "1.4.0";
 /** Returns true if `to` is the same or higher tier than `from`. */
 export declare function isTierUpgradeOrSame(from: Tier, to: Tier): boolean;
 /** Check if a template file is a numbered migration (not seed.sql). */

package/dist/templates.js

@@ -5,7 +5,7 @@
  * All other files are copied verbatim.
  */
 /** Single source of truth for the SDK version. */
-export const SDK_VERSION = '1.1.1';
+export const SDK_VERSION = '1.4.0';
 /** Tier ordering for upgrade validation. */
 const TIER_ORDER = { minimal: 0, standard: 1, full: 2 };
 /** Returns true if `to` is the same or higher tier than `from`. */
@@ -82,6 +82,8 @@ const SHARED_FILES = [
     // Workers — lib/usage/collectors (pluggable interface + example)
     { src: 'shared/workers/lib/usage/collectors/index.ts', dest: 'workers/lib/usage/collectors/index.ts', template: false },
     { src: 'shared/workers/lib/usage/collectors/example.ts', dest: 'workers/lib/usage/collectors/example.ts', template: false },
+    // Documentation
+    { src: 'shared/docs/kv-key-patterns.md', dest: 'docs/kv-key-patterns.md', template: false },
 ];
 const STANDARD_FILES = [
     // Additional migrations
@@ -116,6 +118,7 @@ const FULL_FILES = [
     { src: 'full/wrangler.settings.jsonc.hbs', dest: 'wrangler.{{projectSlug}}-settings.jsonc', template: true },
     // Workers — pattern-discovery (AI-assisted transient error patterns)
     { src: 'full/workers/pattern-discovery.ts', dest: 'workers/pattern-discovery.ts', template: false },
+    { src: 'full/workers/lib/pattern-discovery/index.ts', dest: 'workers/lib/pattern-discovery/index.ts', template: false },
     { src: 'full/workers/lib/pattern-discovery/types.ts', dest: 'workers/lib/pattern-discovery/types.ts', template: false },
     { src: 'full/workers/lib/pattern-discovery/clustering.ts', dest: 'workers/lib/pattern-discovery/clustering.ts', template: false },
     { src: 'full/workers/lib/pattern-discovery/ai-prompt.ts', dest: 'workers/lib/pattern-discovery/ai-prompt.ts', template: false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebearapps/platform-admin-sdk",
-  "version": "1.1.1",
+  "version": "1.4.0",
   "description": "Platform Admin SDK — scaffold backend infrastructure with workers, circuit breakers, and cost protection for Cloudflare",
   "type": "module",
   "bin": {
@@ -35,12 +35,22 @@
     "directory": "packages/admin-sdk"
   },
   "keywords": [
+    "cloudflare",
     "cloudflare-workers",
-    "platform-admin-sdk",
     "scaffold",
     "cost-protection",
-    "circuit-breaker"
+    "circuit-breaker",
+    "billing-safety",
+    "observability",
+    "telemetry",
+    "budget-enforcement",
+    "error-collection",
+    "usage-monitoring"
   ],
+  "homepage": "https://github.com/littlebearapps/platform-sdks#readme",
+  "bugs": {
+    "url": "https://github.com/littlebearapps/platform-sdks/issues"
+  },
   "author": "Little Bear Apps",
   "license": "MIT"
 }

package/templates/full/workers/lib/pattern-discovery/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Pattern Discovery Module
+ *
+ * AI-assisted discovery of transient error patterns.
+ *
+ * @module workers/lib/pattern-discovery
+ */
+
+export * from './types';
+export * from './clustering';
+export * from './ai-prompt';
+export * from './validation';
+export * from './storage';

package/templates/full/workers/lib/pattern-discovery/storage.ts

@@ -329,6 +329,7 @@ export async function refreshDynamicPatternsCache(
       FROM transient_pattern_suggestions
       WHERE status = 'approved'
       ORDER BY created_at ASC
+      LIMIT 500
     `
       )
       .all<PatternRule & { id: string }>();

package/templates/shared/config/services.yaml.hbs

@@ -20,6 +20,50 @@ projects:
           script_name: {{projectSlug}}-usage
           status: active
           schedule: "0 * * * *"
+{{#if isStandard}}
+
+        - id: {{projectSlug}}-error-collector
+          name: "Error Collector"
+          script_name: {{projectSlug}}-error-collector
+          status: active
+          schedule: "*/15 * * * *"
+          metadata:
+            type: tail-worker
+
+        - id: {{projectSlug}}-sentinel
+          name: "Platform Sentinel"
+          script_name: {{projectSlug}}-sentinel
+          status: active
+          schedule: "*/15 * * * *"
+{{/if}}
+{{#if isFull}}
+
+        - id: {{projectSlug}}-pattern-discovery
+          name: "Pattern Discovery"
+          script_name: {{projectSlug}}-pattern-discovery
+          status: active
+          schedule: "0 2 * * *"
+
+        - id: {{projectSlug}}-alert-router
+          name: "Alert Router"
+          script_name: {{projectSlug}}-alert-router
+          status: active
+
+        - id: {{projectSlug}}-notifications
+          name: "Notifications"
+          script_name: {{projectSlug}}-notifications
+          status: active
+
+        - id: {{projectSlug}}-search
+          name: "Search"
+          script_name: {{projectSlug}}-search
+          status: active
+
+        - id: {{projectSlug}}-settings
+          name: "Settings"
+          script_name: {{projectSlug}}-settings
+          status: active
+{{/if}}
       storage:
         d1:
           - database_name: {{projectSlug}}-metrics
@@ -43,3 +87,58 @@ projects:
           feature_id: "{{projectSlug}}:queue:telemetry"
           circuit_breaker: true
           cost_tier: low
+{{#if isStandard}}
+      error-collection:
+        tail-processing:
+          display_name: "Error Tail Processing"
+          feature_id: "{{projectSlug}}:error-collection:tail"
+          circuit_breaker: true
+          cost_tier: medium
+        daily-digest:
+          display_name: "Error Daily Digest"
+          feature_id: "{{projectSlug}}:error-collection:digest"
+          circuit_breaker: true
+          cost_tier: low
+        gap-alerts:
+          display_name: "Gap Alert Processing"
+          feature_id: "{{projectSlug}}:error-collection:gap-alerts"
+          circuit_breaker: false
+          cost_tier: low
+      monitor:
+        sentinel:
+          display_name: "Platform Sentinel"
+          feature_id: "{{projectSlug}}:monitor:sentinel"
+          circuit_breaker: true
+          cost_tier: low
+{{/if}}
+{{#if isFull}}
+      pattern-discovery:
+        ai-discovery:
+          display_name: "AI Pattern Discovery"
+          feature_id: "{{projectSlug}}:pattern-discovery:ai"
+          circuit_breaker: true
+          cost_tier: high
+        shadow-evaluation:
+          display_name: "Shadow Evaluation"
+          feature_id: "{{projectSlug}}:pattern-discovery:shadow"
+          circuit_breaker: true
+          cost_tier: medium
+      notifications:
+        api:
+          display_name: "Notifications API"
+          feature_id: "{{projectSlug}}:notifications:api"
+          circuit_breaker: true
+          cost_tier: low
+      search:
+        api:
+          display_name: "Search API"
+          feature_id: "{{projectSlug}}:search:api"
+          circuit_breaker: true
+          cost_tier: low
+      settings:
+        api:
+          display_name: "Settings API"
+          feature_id: "{{projectSlug}}:settings:api"
+          circuit_breaker: true
+          cost_tier: low
+{{/if}}

package/templates/shared/docs/kv-key-patterns.md

@@ -0,0 +1,101 @@
+# KV Key Patterns Reference
+
+All keys stored in the `PLATFORM_CACHE` KV namespace, grouped by subsystem.
+
+> Generated by `@littlebearapps/platform-admin-sdk`. Keep this up to date as you add features.
+
+---
+
+## Circuit Breaker State
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `GLOBAL_STOP_ALL` | `GLOBAL_STOP_ALL` | None | platform-usage | Emergency kill switch — pauses all operations |
+| `PROJECT:{slug}:STATUS` | `PROJECT:MY-APP:STATUS` | None | platform-usage | Per-project circuit breaker state (`active`/`warning`/`paused`) |
+| `FEATURE:{key}:enabled` | `FEATURE:my-app:scanner:enabled` | None | platform-usage | Feature-level on/off flag |
+| `FEATURE:{key}:disabled_reason` | `FEATURE:my-app:scanner:disabled_reason` | None | platform-usage | Why feature was disabled |
+| `FEATURE:{key}:disabled_at` | `FEATURE:my-app:scanner:disabled_at` | None | platform-usage | Timestamp of disable |
+| `FEATURE:{key}:auto_reset_at` | `FEATURE:my-app:scanner:auto_reset_at` | None | platform-usage | Auto-reset timestamp |
+
+## Budget Enforcement
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `CONFIG:BUDGETS` | `CONFIG:BUDGETS` | None (synced) | sync-config | Budget JSON from budgets.yaml |
+| `CONFIG:FEATURE:{key}:BUDGET_MONTHLY` | `CONFIG:FEATURE:my-app:scanner:BUDGET_MONTHLY` | None | sync-config | Monthly budget limit for feature |
+| `BUDGET_WARN:{feature}:{metric}:{threshold}` | `BUDGET_WARN:my-app:scanner:d1_writes:70` | 1hr | platform-usage | Budget warning dedup (prevents duplicate Slack alerts) |
+| `BUDGET_WARN_MONTHLY:{feature}:{limit}:exceeded` | `BUDGET_WARN_MONTHLY:my-app:scanner:d1_writes:exceeded` | 24hr | platform-usage | Monthly budget exceeded dedup |
+| `BUDGET_WARN_MONTHLY:{feature}:{limit}:{threshold}` | `BUDGET_WARN_MONTHLY:my-app:scanner:d1_writes:70` | 24hr | platform-usage | Monthly warning threshold dedup |
+
+## Usage & Sampling State
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `platform-usage:sampling-mode` | `platform-usage:sampling-mode` | None | platform-usage | Current sampling mode enum |
+| `platform-usage:d1-writes-24h` | `platform-usage:d1-writes-24h` | None | platform-usage | Rolling 24h D1 write counter |
+| `platform-usage:d1-writes-timestamp` | `platform-usage:d1-writes-timestamp` | None | platform-usage | Timestamp for write counter reset |
+| `platform-usage:do-gb-seconds-24h:{project}` | `platform-usage:do-gb-seconds-24h:my-app` | None | platform-usage | DO GB-seconds per project |
+| `platform-usage:pricing:v1` | `platform-usage:pricing:v1` | None | platform-usage | Cached pricing config |
+| `platform-usage:prev-hour:account` | `platform-usage:prev-hour:account` | None | platform-usage | Delta calculation state |
+| `platform-usage:prev-hour:timestamp` | `platform-usage:prev-hour:timestamp` | None | platform-usage | Last collection hour |
+
+## Settings Cache
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `CONFIG:SETTINGS:ALL` | `CONFIG:SETTINGS:ALL` | 1hr | platform-usage | Full PlatformSettings JSON cache |
+| `CONFIG:SETTINGS:{key}` | `CONFIG:SETTINGS:budget_soft_limit` | 1hr | platform-usage | Individual setting value cache |
+
+## Error Collection (Standard+ tier)
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `SCRIPT_MAP:{scriptName}` | `SCRIPT_MAP:my-worker` | None | error-collector | Worker name to project mapping |
+| `ERROR_FINGERPRINT:{hash}` | `ERROR_FINGERPRINT:a1b2c3` | None | error-collector | Cached known error state |
+| `ISSUE_LOCK:{hash}` | `ISSUE_LOCK:a1b2c3` | 60s | error-collector | Race-condition dedup for GitHub issue creation |
+| `TRANSIENT:{script}:{category}:{date}` | `TRANSIENT:my-worker:quota-exhausted:2026-03-02` | 24hr | error-collector | Transient error dedup window (1 issue/category/day) |
+| `ERROR_RATE:{script}:{hour}` | `ERROR_RATE:my-worker:2026-03-02T14` | 2hr | error-collector | Hourly error rate counter |
+
+## Sentinel (Standard+ tier)
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `sentinel:project-gaps:result` | `sentinel:project-gaps:result` | 1hr | platform-sentinel | Cached gap detection results |
+| `alert-thresholds:config` | `alert-thresholds:config` | None | platform-sentinel | Alert threshold configuration |
+
+## Gap Alerts (Standard+ tier)
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `GAP_ALERT:{project}:{date}` | `GAP_ALERT:my-app:2026-03-02` | 24hr | error-collector | Gap alert dedup (1 issue/project/day) |
+
+## Pattern Discovery (Full tier)
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `PATTERNS:DYNAMIC:APPROVED` | `PATTERNS:DYNAMIC:APPROVED` | None (refreshed) | pattern-discovery | Approved patterns JSON cache for error-collector runtime |
+
+## Notifications (Full tier)
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `NOTIFICATION_COUNT:{userId}` | `NOTIFICATION_COUNT:admin` | None | platform-notifications | Unread notification count |
+| `NOTIFICATION_PREFS:{userId}` | `NOTIFICATION_PREFS:admin` | None | platform-notifications | User notification preferences |
+| `NOTIFICATION_READ:{userId}:{notifId}` | `NOTIFICATION_READ:admin:abc123` | None | platform-notifications | Per-notification read state |
+
+## Alert Dedup
+
+| Key Pattern | Example | TTL | Worker | Purpose |
+|---|---|---|---|---|
+| `ALERT:{key}:last_sent` | `ALERT:my-app:scanner:last_sent` | None | platform-usage | Alert send dedup |
+| `SLACK_ALERT:{type}:{key}` | `SLACK_ALERT:budget:my-app:scanner` | 1hr | shared/slack-alerts | Slack message dedup |
+
+---
+
+## Key Conventions
+
+- **Uppercase prefixes** (`CONFIG:`, `FEATURE:`, `BUDGET_WARN:`) = system state
+- **Lowercase prefixes** (`platform-usage:`, `sentinel:`) = operational cache
+- **TTL = None** means the key persists until explicitly deleted or overwritten
+- **Dedup keys** use short TTLs (60s-24hr) to prevent duplicate actions
+- All keys use `:` as separator (never `/` or `.`)

package/templates/shared/migrations/002_usage_warehouse.sql

@@ -193,6 +193,7 @@ CREATE TABLE IF NOT EXISTS daily_usage_rollups (
 
   -- Vectorize metrics
   vectorize_queries INTEGER DEFAULT 0,
+  vectorize_inserts INTEGER DEFAULT 0,
   vectorize_vectors_stored_max INTEGER DEFAULT 0,
   vectorize_cost_usd REAL DEFAULT 0,