@littlebearapps/platform-admin-sdk 1.2.0 → 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,45 +73,63 @@ 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
 
@@ -156,11 +208,24 @@ 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.
 
-Starting with v1.1.0, the Admin SDK writes a `.platform-scaffold.json` manifest that tracks what was generated. This enables safe, incremental upgrades. **Commit this file to git** — it's how the upgrade command knows what to update.
+## 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.
+
+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
+
+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 an existing project
+### Upgrade (v1.1.0+)
 
 ```bash
 cd my-platform
@@ -169,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:
 
@@ -185,15 +250,22 @@ Upgrade to a higher tier:
 npx @littlebearapps/platform-admin-sdk upgrade --tier standard
 ```
 
-### Adopt a pre-v1.1.0 project
+### Upgrade vs Adopt
 
-Projects scaffolded before v1.1.0 don't have a manifest. Run `adopt` first:
-
-```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
 
@@ -210,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/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.2.0";
+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.2.0';
+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.2.0",
+  "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/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,
 

package/templates/shared/migrations/seed.sql.hbs

@@ -1,4 +1,4 @@
 -- Seed data: register your project in the platform
-INSERT INTO project_registry (project_id, display_name, status, tier, repository)
-VALUES ('{{projectSlug}}', '{{projectName}}', 'active', 'paid', '{{githubOrg}}/{{projectSlug}}')
+INSERT INTO project_registry (project_id, display_name, status, repo_path)
+VALUES ('{{projectSlug}}', '{{projectName}}', 'active', '{{githubOrg}}/{{projectSlug}}')
 ON CONFLICT (project_id) DO NOTHING;

package/templates/shared/scripts/sync-config.ts

@@ -36,10 +36,10 @@ const D1_DATABASE_NAME = 'YOUR_D1_DATABASE_NAME';
 
 interface FeatureDefinition {
   display_name: string;
-  feature_id?: string;
   circuit_breaker: boolean;
   description?: string;
   cost_tier: string;
+  sources?: string[];
 }
 
 interface FeatureCategory {
@@ -49,36 +49,90 @@ interface FeatureCategory {
 interface Project {
   display_name: string;
   status: string;
-  tier: string;
+  tier: number;
+  primary_resource?: string;
   repository?: string;
+  runbook?: string;
+  infrastructure?: unknown;
   features?: Record<string, FeatureCategory>;
 }
 
 interface Services {
-  metadata: { version: string };
+  metadata: {
+    version: string;
+    lastUpdated: string;
+  };
   projects: Record<string, Project>;
 }
 
 interface BudgetLimit {
   d1_writes?: number;
   d1_reads?: number;
+  d1_rows_read?: number;
+  d1_rows_written?: number;
   kv_reads?: number;
   kv_writes?: number;
+  kv_deletes?: number;
+  kv_lists?: number;
+  r2_class_a?: number;
+  r2_class_b?: number;
+  ai_requests?: number;
+  ai_neurons?: number;
+  vectorize_queries?: number;
+  vectorize_inserts?: number;
   queue_messages?: number;
+  do_requests?: number;
+  workflow_invocations?: number;
   requests?: number;
   cpu_ms?: number;
 }
 
+interface CircuitBreakerConfig {
+  enabled?: boolean;
+  auto_reset_seconds?: number;
+  cooldown_seconds?: number;
+  max_consecutive_trips?: number;
+  notes?: string;
+}
+
+interface FeatureOverride {
+  hourly?: BudgetLimit;
+  daily?: BudgetLimit;
+  monthly?: BudgetLimit;
+  circuit_breaker?: CircuitBreakerConfig;
+}
+
+interface GlobalLimits {
+  d1_write_limit?: number;
+  do_gb_seconds_daily_limit?: number;
+}
+
 interface Budgets {
+  metadata: {
+    version: string;
+    lastUpdated: string;
+  };
   defaults: {
+    global_limits?: GlobalLimits;
     daily: BudgetLimit;
     circuit_breaker: {
       auto_reset_seconds: number;
       cooldown_seconds: number;
+      max_consecutive_trips: number;
+    };
+    error_budget?: {
+      error_rate_threshold: number;
+      window_minutes: number;
+      min_requests: number;
+    };
+    thresholds: {
+      warning: number;
+      critical: number;
     };
-    thresholds: { warning: number; critical: number };
   };
-  feature_overrides: Record<string, BudgetLimit>;
+  cost_tiers: Record<string, { multiplier: number; description: string }>;
+  project_budgets: Record<string, { allocation_percent: number; notes: string }>;
+  feature_overrides: Record<string, FeatureOverride>;
 }
 
 // =============================================================================

package/templates/shared/workers/lib/platform-settings.ts

@@ -56,6 +56,9 @@ export interface PlatformSettings {
   // Resource limits (daily)
   d1WriteLimit: number;
   doGbSecondsDailyLimit: number;
+
+  // Gap detection
+  gapCoverageThresholdPct: number;
 }
 
 /**
@@ -104,6 +107,9 @@ export const DEFAULT_PLATFORM_SETTINGS: PlatformSettings = {
   // Resource limits (daily)
   d1WriteLimit: 1_000_000, // 1M writes per 24h (adaptive sampling trigger)
   doGbSecondsDailyLimit: 200_000, // 200K GB-seconds per 24h (~$2.50/day)
+
+  // Gap detection
+  gapCoverageThresholdPct: 90, // Per-project resource coverage threshold (percentage)
 };
 
 /**
@@ -128,6 +134,7 @@ export const SETTING_KEY_MAP: Record<string, keyof PlatformSettings> = {
   error_rate_min_requests: 'errorRateMinRequests',
   d1_write_limit: 'd1WriteLimit',
   do_gb_seconds_daily_limit: 'doGbSecondsDailyLimit',
+  gap_coverage_threshold_pct: 'gapCoverageThresholdPct',
 };
 
 /**
@@ -244,7 +251,13 @@ export async function getPlatformSettings(env: SettingsEnv): Promise<PlatformSet
       try {
         const parsed = JSON.parse(cached) as Partial<PlatformSettings>;
         // Merge with defaults to handle any missing keys
-        return { ...DEFAULT_PLATFORM_SETTINGS, ...parsed };
+        const merged = { ...DEFAULT_PLATFORM_SETTINGS, ...parsed };
+        // Defense-in-depth: floor critical limits to prevent stale/poisoned cache values
+        if (merged.d1WriteLimit < 1000)
+          merged.d1WriteLimit = DEFAULT_PLATFORM_SETTINGS.d1WriteLimit;
+        if (merged.doGbSecondsDailyLimit < 1000)
+          merged.doGbSecondsDailyLimit = DEFAULT_PLATFORM_SETTINGS.doGbSecondsDailyLimit;
+        return merged;
       } catch {
         // Invalid JSON, fall through to D1
       }
@@ -404,4 +417,6 @@ export const EXPECTED_SETTINGS_KEYS = [
   // Resource limits
   'd1_write_limit',
   'do_gb_seconds_daily_limit',
+  // Gap detection
+  'gap_coverage_threshold_pct',
 ];