feat(skills): insforge.toml config-as-code + compute scale-to-zero docs

skills/insforge-cli/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: insforge-cli
 description: >-
-  Use this skill when managing InsForge infrastructure with the CLI: projects, SQL, migrations, RLS policies, functions, storage buckets, frontend deployments, compute services, secrets/env vars, Stripe payment keys/catalog/products/prices/webhooks, schedules, logs, diagnostics, import/export, or **managing backend branches** (creating a branch project to test risky schema/auth/RLS changes, merging a branch back to prod, resolving merge conflicts). For app code with @insforge/sdk, use the insforge skill instead.
+  Use this skill when managing InsForge infrastructure with the CLI: projects, SQL, migrations, RLS policies, functions, storage buckets, frontend deployments, compute services, secrets/env vars, Stripe payment keys/catalog/products/prices/webhooks, schedules, logs, diagnostics, import/export, **declarative auth redirect URLs via `insforge.toml`** (applied with `config apply`), or **managing backend branches** (creating a branch project to test risky schema/auth/RLS changes, merging a branch back to prod, resolving merge conflicts). For app code with @insforge/sdk, use the insforge skill instead.
 license: MIT
 metadata:
   author: insforge
-  version: "1.4.0"
+  version: "1.5.0"
   organization: InsForge
   date: May 2026
 ---
@@ -173,6 +173,22 @@ For frontend hosting see **Frontend Deployments** above.
 - `npx @insforge/cli secrets update <key> [--value] [--active] [--reserved] [--expires]` — update secret
 - `npx @insforge/cli secrets delete <key>` — **soft delete** (marks inactive; restore with `--active true`)
 
+### Configuration — `npx @insforge/cli config`
+
+Manage `auth.allowed_redirect_urls` declaratively via `insforge.toml` (project root). For changing redirect URLs, prefer this over `PUT /api/auth/config` — the CLI gates on backend version and surfaces a clean skip if the backend predates the field, where the raw PUT may 200-and-silently-drop.
+
+- `npx @insforge/cli config export [--out insforge.toml] [--force]` — pull live config into TOML. Sections the backend doesn't expose are omitted.
+- `npx @insforge/cli config plan [--file insforge.toml]` — diff TOML vs. live state; shows which changes will apply vs. be skipped on the connected backend.
+- `npx @insforge/cli config apply [--file insforge.toml] [--dry-run] [--auto-approve]` — apply the TOML. Per-change capability gate: supported changes apply; unsupported go to `skipped[]` with an upgrade message and **no PUT is issued for them**. `--json` returns `{ plan, applied[], skipped[] }`.
+
+> **If `apply` returns `skipped: [...]`, surface verbatim.** The user's backend predates this section. Tell them which sections were skipped and to upgrade; do not retry, do not bypass with `curl` (silent drop). Sample message: _"I tried to set `auth.allowed_redirect_urls` but your backend is on an older version that doesn't support it yet. Upgrade your backend and re-run `npx @insforge/cli config apply`."_
+
+> **TOML is for knobs only — never embed programs.** SQL → `db migrations`. Function code → `functions deploy`. Compute → `compute deploy`. Frontend → `deployments deploy`. TOML carries booleans, strings, and arrays — anything bigger lives in its own file managed by a dedicated CLI command.
+
+**Scope today:** only `auth.allowed_redirect_urls`. Password policy, SMTP, OAuth providers, custom subdomain, and similar will land in TOML later. For other `auth.config` fields today, use the dashboard.
+
+See [references/config.md](references/config.md) for output shapes and a common-mistakes table.
+
 ### Schedules — `npx @insforge/cli schedules`
 - `npx @insforge/cli schedules list` — list all scheduled tasks (shows ID, name, cron, URL, method, active, next run)
 - `npx @insforge/cli schedules get <id>` — get schedule details
@@ -278,10 +294,29 @@ Run with no subcommand for a full health report across all checks.
 
 **Payments use Stripe as source of truth**: use `payments config set` for Stripe keys, `payments sync` before relying on existing catalog data, and create a new Stripe price instead of editing amount/currency. Runtime checkout and customer portal integration belongs in the `insforge` SDK skill.
 
+**`config apply` is version-aware**: per-project backends drift in version. The CLI probes `/api/metadata` and gates `auth.allowed_redirect_urls` on whether the backend exposes it; if not, the change lands in `skipped[]` with an upgrade message and **no PUT is issued**. Never bypass with `curl` to "force" a skipped field — older backends may 200-and-silently-drop. Surface skips to the user and ask them to upgrade.
+
 ---
 
 ## Common Workflows
 
+### Configure auth redirect URLs (insforge.toml)
+
+```bash
+# 1. Pull current config to insforge.toml (writes in project root)
+npx @insforge/cli --json config export
+
+# 2. Edit insforge.toml — add/remove entries under [auth] allowed_redirect_urls
+
+# 3. Preview the diff
+npx @insforge/cli --json config plan
+
+# 4. Apply (use --yes for non-interactive — required in --json mode)
+npx @insforge/cli --json --yes config apply
+```
+
+If `apply` returns a non-empty `skipped[]`, the user's backend predates this section — surface the entries verbatim with the upgrade ask. Don't retry, don't fall back to `curl` (older backends may 200-and-silently-drop). See [references/config.md](references/config.md).
+
 ### Set up database schema with migrations
 
 ```bash

skills/insforge-cli/references/compute-deploy.md

@@ -269,6 +269,9 @@ A: Use `compute update <service-id> --image <new-image-url>`. The machine is res
 **Q: What happens to my service if Fly.io has an outage?**
 A: It's down. InsForge runs your containers on Fly's infrastructure — Fly's uptime is your uptime. For HA, you'd typically deploy multiple services in different regions (future feature).
 
+**Q: Why is the first request after idle slow?**
+A: v1 services scale to zero when idle and wake on the next request (~1s cold start on `shared-1x`). No flag to disable in v1; contact support if you need always-on.
+
 **Q: I see `MANIFEST_UNKNOWN` in a stack trace. What is it?**
 A: After `flyctl` pushes your image, Fly asynchronously aliases the digest from the builder's namespace to your app's namespace. Until that propagates (usually < 8 s) the Machines API returns `400 MANIFEST_UNKNOWN` even though the digest is correct. The InsForge cloud silently retries 4 times with backoff `[2s, 4s, 8s]`, so you almost never see it. If retries exhaust, you get a structured `COMPUTE_IMAGE_NOT_AVAILABLE` 400 with `nextActions` telling you to re-run — re-runs are idempotent and typically succeed instantly because the alias has had time to propagate.
 

skills/insforge-cli/references/config.md

@@ -0,0 +1,74 @@
+# npx @insforge/cli config
+
+Deep reference for `config export | plan | apply`. The SKILL.md Configuration section has the principles and rules; this file has output shapes and the error table.
+
+**Scope today:** only `auth.allowed_redirect_urls`. Other auth knobs are dashboard-only.
+
+## Commands
+
+```bash
+npx @insforge/cli config export [--out insforge.toml] [--force]
+npx @insforge/cli config plan   [--file insforge.toml]
+npx @insforge/cli config apply  [--file insforge.toml] [--dry-run] [--auto-approve]
+```
+
+## File location
+
+`insforge.toml` lives at the project root, alongside `package.json` and `.insforge/project.json`. Safe to commit to git.
+
+## Output shapes (`--json` mode)
+
+`config export`:
+```json
+{
+  "written": "/abs/path/to/insforge.toml",
+  "config": { "auth": { "allowed_redirect_urls": ["https://app.com"] } },
+  "skipped": []
+}
+```
+
+`config plan`:
+```json
+{
+  "changes": [
+    {
+      "section": "auth",
+      "op": "modify",
+      "key": "allowed_redirect_urls",
+      "from": ["https://app.com"],
+      "to": ["https://app.com", "https://staging.app.com"]
+    }
+  ],
+  "summary": { "add": 0, "modify": 1, "remove": 0, "kept": 0 },
+  "skipped": []
+}
+```
+
+`config apply`:
+```json
+{
+  "plan": { /* same shape as plan output */ },
+  "applied": [ /* DiffChange objects that were applied */ ],
+  "skipped": [
+    {
+      "key": "auth.allowed_redirect_urls",
+      "reason": "your backend doesn't expose auth.allowed_redirect_urls — upgrade the project to apply this section"
+    }
+  ]
+}
+```
+
+## Common mistakes
+
+| Mistake | What to do instead |
+|---|---|
+| Calling `PUT /api/auth/config` directly to change `allowedRedirectUrls` | Use `config apply` — it's version-aware; direct PUTs can silently drop on older backends |
+| Treating `skipped[]` as an error to retry | It's intentional; surface verbatim with the upgrade ask and stop |
+| Running `config apply` in `--json` mode without `--yes` | Add `-y`/`--yes` (global) or `--auto-approve` (subcommand alias — same effect); otherwise fails fast with `CONFIRMATION_REQUIRED` |
+| Re-running with `--force` to "fix" a skip | `--force` is only for `export`'s overwrite gate; skips need a backend upgrade |
+| Setting password policy / OAuth providers / SMTP via TOML | Out of scope today — dashboard-only |
+
+## Related
+
+- `npx @insforge/cli metadata` — read-only view of all backend config slices
+- **insforge** SDK skill `auth/sdk-integration.md` — how SDK code reads auth config at runtime

skills/insforge/SKILL.md

@@ -261,9 +261,10 @@ These modules still require HTTP API calls because the CLI does not yet support
 
 | Module | Backend Configuration |
 |--------|----------------------|
-| **Auth** | [auth/backend-configuration.md](auth/backend-configuration.md) |
 | **AI** | [ai/backend-configuration.md](ai/backend-configuration.md) |
 
+> Auth redirect URL allowlist is now managed via the CLI — use `npx @insforge/cli config export/plan/apply`. Other auth settings (password policy, OAuth providers, verification methods) still live on the dashboard. See the **insforge-cli** skill's Configuration section.
+
 ### Risky backend changes? Use a branch first
 
 When a code change in this skill depends on a **schema migration**, **new RLS policy**, **OAuth provider config change**, or any other backend change that could brick prod, create a backend branch first instead of editing the live project. Branches share `JWT_SECRET` (existing user JWTs keep working) but get a fresh database + EC2 + `API_KEY` / `ANON_KEY`, so you can test the SDK + backend change end-to-end in isolation.

skills/insforge/auth/sdk-integration.md

@@ -362,8 +362,9 @@ Only render the reset form when `insforge_status=ready` and `token` is present.
 ## Best Practices
 
 1. **Always check auth config first** before implementing
-   - Run `insforge metadata --json` to get auth config, or see [backend-configuration.md](backend-configuration.md)
+   - Run `npx @insforge/cli metadata --json` to get auth config (`requireEmailVerification`, `verifyEmailMethod`, `resetPasswordMethod`, `oAuthProviders`, `allowedRedirectUrls`)
    - This tells you what features to implement
+   - To **add a redirect URL** to the allowlist, use `npx @insforge/cli config apply` — see the **insforge-cli** skill's Configuration section. Other auth settings (password policy, OAuth providers, etc.) are dashboard-only today.
 
 2. **The sign-up page must handle the full registration flow**
    - After calling `signUp()`, if `requireEmailVerification` is true, branch on `verifyEmailMethod`
@@ -450,7 +451,7 @@ if (enabledProviders.includes('github')) {
 ## Recommended Workflow
 
 ```
-1. Get auth config           → See backend-configuration.md
+1. Get auth config           → npx @insforge/cli metadata --json
 2. Check what's enabled      → Email verification? Which OAuth providers?
 3. Build appropriate UI      → Code input vs magic link, OAuth buttons
 4. Implement sign-up         → Handle requireEmailVerification response