postkitstack · Yasirunet · Aug 29, 2026 · Jul 23, 2026 · Jul 23, 2026 · Jul 24, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -144,6 +144,8 @@ PostKit files are split between committed (shared with team) and gitignored (use
 - `assertLocalConnection(session, spinner)` (`utils/session.ts`) - Tests local DB connection from session; throws if unreachable
 - `resolveApplyTarget(target?)` (`utils/apply-target.ts`) - Resolves `"local"` or `"remote"` apply target; used by infra and seed commands
 - `readJsonFile<T>(path)` / `writeJsonFile(path, data)` (`utils/json-file.ts`) - Typed JSON helpers used by remotes and committed migration tracking
+- `scaffoldDbInfra()` (`services/scaffold.ts`) - Scaffolds `db/infra/001_roles.sql`+`002_schemas.sql`; runs on both full `postkit init` and `init db`. `scaffoldStorageMigration()` scaffolds the `storage.migrations` bootstrap migration; full `postkit init` only. Both are idempotent (safe to call multiple times, never overwrite)
+- `getBlockingPendingCommittedMigrations()` (`utils/committed.ts`) - Like `getPendingCommittedMigrations()` but excludes entries with `blocksSessionStart: false` (e.g. the storage.migrations bootstrap). Used by `db start`'s pending-migrations guard so a brand-new project's first session isn't blocked by a migration nobody has deployed yet; `db deploy`/`db status` still use the unfiltered lookup so it's deployed and listed normally
 
 ### Stack Module Architecture
 
@@ -197,10 +199,13 @@ The `stack` module manages a local backend service stack (Postgres, Keycloak, Po
 - `importRealmTemplate(config, spinner?)` (`services/realm-init.ts`) — Cleans realm JSON and imports via `keycloak-config-cli` container
 - `cleanRealmTemplate(raw, realmName)` (`services/realm-init.ts`) — Strips builtins, injects JWT Role Mapper
 
-**`postkit init` scaffold additions:**
+**`postkit init [module]` scaffold additions:**
+- No `module` argument scaffolds everything (db + auth + stack), unchanged from before scoping existed. Passing `db`, `auth`, or `stack` scaffolds only that module — see `initCommand()`/`initModuleCommand()` in `cli/src/commands/init.ts`
+- Scoped runs never re-prompt for or overwrite an existing `postkit.config.json`/`postkit.secrets.json` — they create those files (always with the full db+auth+stack shape, since the db/auth config loaders throw on a missing section) only if missing, and otherwise reuse the existing project name
 - Prompts for project name → generates `<name>_<8hexchars>`, stored as `name` in `postkit.config.json`
 - Creates `db/infra/001_roles.sql` (anon, authenticated, service_role, app_user, authenticator roles)
 - Creates `db/infra/002_schemas.sql` (public, auth, storage schemas)
+- Full init only (not `init db`): scaffolds a `storage.migrations` bootstrap migration (`.postkit/db/migrations/00000000000001_create_storage_migrations_table.sql`, tracked in `committed.json`) — a migration-tracking table expected by a self-hosted storage service (e.g. Supabase storage-api) run against the `storage` schema; delete the file + its `committed.json` entry if you don't run one
 - Copies vendor provider JARs to `.postkit/auth/providers/`
 - Scaffolds realm template at `.postkit/auth/realm/postkit.json`
 
@@ -274,6 +279,15 @@ Remotes are managed via utilities in `modules/db/utils/remotes.ts`:
 - **tsx** for development mode (direct TS execution without building)
 - Output goes to `dist/` with a shebang banner for CLI execution
 
+## Project Init Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `postkit init` | Scaffold the entire project: db + auth + stack |
+| `postkit init db` | Scaffold only the db module (`.postkit/db/`, `db/infra/*.sql`) — does not scaffold the `storage.migrations` bootstrap migration, which is full-init only |
+| `postkit init auth` | Scaffold only the auth module (`.postkit/auth/`, Keycloak provider sync, realm template) |
+| `postkit init stack` | Scaffold only the stack module (`.postkit/stack/`) |
+
 ## Database Module Commands Reference
 
 | Command | Purpose |

diff --git a/README.md b/README.md
@@ -22,15 +22,15 @@ PostKit brings together the following components:
 
 ## PostKit CLI
 
-The PostKit CLI (`@appritech/postkit`) is the developer toolkit for working with the PostKit stack. It provides safe database migrations, auth management, and project scaffolding.
+The PostKit CLI (`@postkitstack/postkit`) is the developer toolkit for working with the PostKit stack. It provides safe database migrations, auth management, and project scaffolding.
 
 **Documentation:** [https://docs.postkitstack.com/](https://docs.postkitstack.com/)
 
 ### Quick Start
 
 ```bash
 # Install the CLI
-npm install -g @appritech/postkit
+npm install -g @postkitstack/postkit
 
 # Initialize a new project
 postkit init
@@ -86,7 +86,7 @@ For more help, see [Troubleshooting](https://docs.postkitstack.com/docs/modules/
 ## Links
 
 - **CLI Tool**: [cli/README.md](cli/README.md)
-- **npm Package**: https://www.npmjs.com/package/@appritech/postkit
+- **npm Package**: https://www.npmjs.com/package/@postkitstack/postkit
 - **Documentation**: https://docs.postkitstack.com/
 - **GitHub**: https://github.com/postkitstack/Postkit
 - **Issues**: https://github.com/postkitstack/Postkit/issues

diff --git a/cli/README.md b/cli/README.md
@@ -1,11 +1,11 @@
-# @appritech/postkit
+# @postkitstack/postkit
 
 > Developer toolkit for database migrations and backend automation
 
 **Note:** This tool is still under development and not recommended for production use. APIs may change between versions.
 
-[![npm version](https://badge.fury.io/js/@appritech/postkit.svg)](https://www.npmjs.com/package/@appritech/postkit)
-[![License](https://img.shields.io/npm/l/@appritech/postkit.svg)](LICENSE)
+[![npm version](https://badge.fury.io/js/%40postkitstack%2Fpostkit.svg)](https://www.npmjs.com/package/@postkitstack/postkit)
+[![License](https://img.shields.io/npm/l/@postkitstack/postkit.svg)](LICENSE)
 
 PostKit CLI is a modular toolkit for backend development with the Appri stack. It provides safe database migrations, auth management, and more.
 
@@ -16,7 +16,7 @@ PostKit CLI is a modular toolkit for backend development with the Appri stack. I
 ### Installation
 
 ```bash
-npm install -g @appritech/postkit
+npm install -g @postkitstack/postkit
 ```
 
 ### Requirements
@@ -190,7 +190,7 @@ For more help, see [Troubleshooting](https://docs.postkitstack.com/docs/modules/
 
 ## 🔗 Links
 
-- **npm Package**: https://www.npmjs.com/package/@appritech/postkit
+- **npm Package**: https://www.npmjs.com/package/@postkitstack/postkit
 - **Documentation**: https://docs.postkitstack.com/
 - **GitHub**: https://github.com/postkitstack/Postkit
 - **Issues**: https://github.com/postkitstack/Postkit/issues

diff --git a/cli/docs/architecture.md b/cli/docs/architecture.md
@@ -21,6 +21,8 @@ PostKit is a modular CLI toolkit built with **TypeScript** and **Node.js** that
 └───────────────────────────────────────────────────────────────────────┘
 ```
 
+**`postkit init [module]`** scaffolds the project. With no argument it scaffolds everything (db + auth + stack) in one pass — the original, unchanged behavior. Passing `db`, `auth`, or `stack` scopes the run to just that module (`cli/src/commands/init.ts`): scoped runs never re-prompt for or overwrite an existing `postkit.config.json`, only creating it — with the full db+auth+stack shape, since the db/auth config loaders throw on a missing section — if it doesn't exist yet, and reusing the existing project name otherwise.
+
 ---
 
 ## Module System
@@ -354,3 +356,5 @@ PostKit files in `.postkit/` are split between gitignored (ephemeral/user-specif
 - `.postkit/auth/providers/`
 - `.postkit/stack/`
 - `postkit.secrets.json`
+
+Full `postkit init` (not the scoped `init db`) also scaffolds a committed bootstrap migration at `.postkit/db/migrations/00000000000001_create_storage_migrations_table.sql`, creating a `storage.migrations` tracking table for a self-hosted storage service (e.g. Supabase storage-api) run against the `storage` schema. It's registered in `committed.json` like any other migration — delete both the file and its `committed.json` entry if you don't run one.
diff --git a/cli/docs/db.md b/cli/docs/db.md
@@ -222,12 +222,17 @@ PostKit files in `.postkit/db/` are split between gitignored (ephemeral) and com
     │   └── 20250131_*.sql
     ├── committed.json       # COMMITTED — migrations tracking index (shared)
     └── migrations/          # COMMITTED — committed migrations (for deploy)
+        ├── 00000000000001_create_storage_migrations_table.sql  # scaffolded by init — see below
         ├── 20250130_add_users.sql
         └── 20250131_add_posts.sql
 ```
 
 `postkit init` adds only the ephemeral paths to `.gitignore` (`.postkit/db/session.json`, `.postkit/db/plan.sql`, `.postkit/db/schema.sql`, `.postkit/db/session/`). The `migrations/` directory and `committed.json` are committed to git and shared across the team.
 
+Full `postkit init` (not the scoped `init db`) always scaffolds `00000000000001_create_storage_migrations_table.sql` — a committed migration creating a `storage.migrations` tracking table for a self-hosted storage service (e.g. Supabase storage-api) run against the `storage` schema. If your project doesn't run one, delete the file and its entry in `committed.json`.
+
+This migration is registered with `blocksSessionStart: false`, so it does **not** count toward `db start`'s "pending committed migrations" guard — a brand-new project can run `db start` immediately without deploying it first. `db deploy` and `db status` are unaffected and still treat it as a normal pending migration to deploy/list.
+
 ---
 
 ## 🚀 Commands

diff --git a/cli/docs/e2e-testing.md b/cli/docs/e2e-testing.md
@@ -246,6 +246,11 @@ Tests infrastructure SQL (roles) and seed data management. Grant permissions are
 | `db status` in empty dir | CLI prevents running before init |
 | `init --force` | Creates complete project scaffold |
 | `init --force` re-init | Force flag allows re-initialization |
+| `init bogus --force` | Unknown module name rejected cleanly, no files created |
+| `init db --force` | Scopes scaffold to `.postkit/db/`, `db/infra/*.sql` only (no storage.migrations — full-init only) |
+| `init auth --force` after `init db` | Adds only auth files; reuses the existing project name |
+| `init stack --force` | Scopes scaffold to `.postkit/stack/` only |
+| `init db --force` twice | Idempotent — no duplicate committed migrations or gitignore lines |
 
 ### Remote Management (`remote-management.test.ts`)
 

diff --git a/cli/docs/stack.md b/cli/docs/stack.md
@@ -94,15 +94,15 @@ Keycloak provider JARs are mounted at `/opt/keycloak/providers` inside the conta
 
 **Destination:** `.postkit/auth/providers/` — gitignored, rebuilt by `postkit init`.
 
-If you add or update a project provider, re-run `postkit init` to sync the new JAR, then restart the stack.
+If you add or update a project provider, re-run `postkit init` (or the auth-only `postkit init auth`) to sync the new JAR, then restart the stack.
 
 ---
 
 ## 🏰 Realm Template + JWT Role Mapper
 
 On the first `stack up` (when `is_initial=true`), PostKit imports a Keycloak realm template.
 
-The template path is configured via `stack.keycloak.realmTemplate` (default: `.postkit/auth/realm/postkit.json`). Scaffolded automatically by `postkit init`.
+The template path is configured via `stack.keycloak.realmTemplate` (default: `.postkit/auth/realm/postkit.json`). Scaffolded automatically by `postkit init` (or the auth-only `postkit init auth`).
 
 Before importing, `cleanRealmTemplate()` transforms the raw template JSON:
 

diff --git a/cli/package-lock.json b/cli/package-lock.json
diff --git a/cli/package.json b/cli/package.json
@@ -1,6 +1,6 @@
 {
-  "name": "@appritech/postkit",
-  "version": "1.3.1",
+  "name": "@postkitstack/postkit",
+  "version": "1.3.2",
   "description": "PostKit - Developer toolkit for database management and more",
   "type": "module",
   "main": "dist/index.js",