create-flowdular 0.5.1 → 0.6.0

package/agent-template/docs/configuration.md

@@ -11,6 +11,7 @@ deployments must set the secret keys.
 | `FD_ENV`             | `NODE_ENV`, else `development`    | Environment the CLI and destructive guards check                           |
 | `FD_PORT`            | `3000`                            | Host port published by the container                                       |
 | `FD_TRUST_PROXY`     | `false`                           | Trust `X-Forwarded-*` behind a reverse proxy                               |
+| `FD_RUNTIME_ROLE`    | `combined`                        | `combined` serves HTTP and runs module workers; `web` or `tick`, see below |
 | `FD_CSP`             | built-in policy                   | Override the Content Security Policy                                       |
 | `FD_CSP_REPORT_ONLY` | `true` outside production         | Report CSP violations instead of enforcing them                            |
 | `FD_LOG_FORMAT`      | `json` in production, else `text` | `json` (one object per line) or `text`; see [operations.md](operations.md) |
@@ -18,6 +19,16 @@ deployments must set the secret keys.
 | `FD_METRICS`         | `false`                           | Expose `GET /api/metrics`; see [operations.md](operations.md)              |
 | `FD_METRICS_TOKEN`   | none                              | Bearer token a metrics scrape must present                                 |
 
+A `web` process serves HTTP only: it never starts a module worker and never
+claims queued work from a request, so a deployment of `web` processes also needs
+a `combined` or a `tick` process on the same database, object storage and keys.
+A `tick` process runs the module workers only inside a tick request that
+presents `FD_WORKER_TICK_SECRET` (at least 32 characters) as a bearer token, for
+at most `FD_WORKER_TICK_WINDOW_MS` (default 50000), and drains them before it
+answers.
+A Vercel deployment works this way; see
+[infra/vercel/README.md](../infra/vercel/README.md).
+
 ## Branding
 
 The name, the document title, the description, the link preview image, the
@@ -289,6 +300,7 @@ message was not delivered.
 | `FD_AGENT_RUN_GRANT_KEY`           | generated dev key | Base64 32-byte key signing run grants                |
 | `FD_AGENT_WORKER_CONCURRENCY`      | `2` (1 to 16)     | Parallel run workers                                 |
 | `FD_AGENT_WORKER_LEASE_MS`         | `30000`           | Run lease before recovery reclaims it                |
+| `FD_AGENT_WORKER_DRAIN_MS`         | `0` (0 to 720000) | Time a stopping worker lets claimed runs finish      |
 | `FD_AGENT_PROVIDER_HOST_ALLOWLIST` | empty             | Hostnames an external provider may be called on      |
 
 Outside production the keys are generated once under `.flowdular/data`. The
@@ -658,7 +670,7 @@ an object moved into another tenant's prefix does not open.
 
 | Variable                             | Default                             | Purpose                                                                      |
 | ------------------------------------ | ----------------------------------- | ---------------------------------------------------------------------------- |
-| `FD_STORAGE_ADAPTER`                 | `s3` in production, else `local`    | `local` or `s3`; `local` is refused in production                            |
+| `FD_STORAGE_ADAPTER`                 | `s3` in production, else `local`    | `local`, `s3` or `vercel-blob`; `local` is refused in production             |
 | `FD_STORAGE_LOCAL_DIRECTORY`         | `.flowdular/data/storage`           | Object directory of the local adapter                                        |
 | `FD_STORAGE_S3_BUCKET`               | none                                | Bucket name; required by the S3 adapter                                      |
 | `FD_STORAGE_S3_REGION`               | none                                | Signing region; required by the S3 adapter                                   |
@@ -666,10 +678,23 @@ an object moved into another tenant's prefix does not open.
 | `FD_STORAGE_S3_ACCESS_KEY_ID`        | none                                | Access key id; required by the S3 adapter                                    |
 | `FD_STORAGE_S3_SECRET_ACCESS_KEY`    | none                                | Secret access key; required by the S3 adapter                                |
 | `FD_STORAGE_S3_FORCE_PATH_STYLE`     | `false`                             | `<endpoint>/<bucket>/<key>` instead of a bucket subdomain                    |
+| `BLOB_STORE_ID`                      | set by Vercel                       | Blob store of the `vercel-blob` adapter, authenticated with Vercel OIDC      |
+| `BLOB_READ_WRITE_TOKEN`              | none                                | Blob read-write token for the `vercel-blob` adapter outside Vercel           |
 | `FD_STORAGE_MAX_OBJECT_BYTES`        | `26214400` (25 MiB)                 | Per-object limit, 1024 to 268435456; a stream is cut off at it               |
 | `FD_STORAGE_ENCRYPTION_KEY`          | derived dev key                     | Base64 32-byte key sealing every object and read URL; required in production |
 | `FD_STORAGE_ENCRYPTION_KEY_PREVIOUS` | empty                               | Retired object keys, comma separated, read only                              |
 
+`vercel-blob` keeps the encrypted objects in a private Vercel Blob store, so a
+Vercel deployment needs no separate bucket. Connecting a Blob store to the
+Vercel project sets `BLOB_STORE_ID`, and the SDK authenticates with the
+deployment's OIDC token, so nothing else is configured there. Outside Vercel,
+set `BLOB_READ_WRITE_TOKEN`. The platform refuses to start when neither is
+present. Reads bypass the Blob cache, so a re-sealed or deleted object is never
+served from an older copy. A Vercel Function accepts at most 4.5 MB of request
+or response body, so set `FD_STORAGE_MAX_OBJECT_BYTES` to at most `4194304`
+there. Lowering the limit makes an existing larger object unreadable through
+this adapter, and a key rotation leaves it sealed under its old key.
+
 A module writes through `context.storage` and never sees an adapter, a bucket or
 a path. Only these content types are stored, and the bytes are verified against
 the declared type before the write: PDF, PNG, JPEG, GIF, WebP, plain text, CSV,
@@ -746,7 +771,9 @@ acquires a lease from the platform provider configured above, so the
 openssl rand -base64 32
 ```
 
-For containers, copy `infra/docker/.env.example` to `infra/docker/.env` and fill
-in every empty value: every encryption key above, including the connectors
-and audit anchor keys, the object store settings and the four PostgreSQL role
-passwords. See [../infra/README.md](../infra/README.md).
+For a local Docker installation, run `node infra/docker/start.mjs`. It creates
+`infra/docker/.env` with missing secrets, starts PostgreSQL and the bundled
+object store, then opens the first-run web setup. Keep that file with database
+and object-store backups; changing its keys or passwords later does not rotate
+existing data or PostgreSQL roles. Other deployments supply these values through
+their own secret manager. See [../infra/README.md](../infra/README.md).

package/agent-template/docs/database-adapters.md

@@ -79,11 +79,11 @@ memory.
 The embedded adapter creates the same roles a deployment configures, so a local
 run enforces the isolation a deployment enforces instead of approximating it.
 
-| Role                  | Owns                                        | Constraints                                                                                 |
-| --------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `coreloom_migrator`   | The schema. Serves the `migration` purpose. | Owns every table the migrations create.                                                     |
-| `coreloom_runtime`    | Request-time reads and writes.              | No `SUPERUSER`, no `BYPASSRLS`, and every handle it lends requires a transaction tenant id. |
-| `coreloom_background` | Cross-tenant polls.                         | Read-only, and no blanket table grant.                                                      |
+| Role                   | Owns                                        | Constraints                                                                                 |
+| ---------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `flowdular_migrator`   | The schema. Serves the `migration` purpose. | Owns every table the migrations create.                                                     |
+| `flowdular_runtime`    | Request-time reads and writes.              | No `SUPERUSER`, no `BYPASSRLS`, and every handle it lends requires a transaction tenant id. |
+| `flowdular_background` | Cross-tenant polls.                         | Read-only, and no blanket table grant.                                                      |
 
 ## Leases
 
@@ -100,13 +100,13 @@ const lease = await context.databases.acquire({
 });
 ```
 
-| Purpose      | Role                  | Used for                                            |
-| ------------ | --------------------- | --------------------------------------------------- |
-| `migration`  | `coreloom_migrator`   | Applying migrations and resetting a database        |
-| `runtime`    | `coreloom_runtime`    | The deployed application                            |
-| `preview`    | `coreloom_runtime`    | A local run and the sandbox preview                 |
-| `test`       | `coreloom_runtime`    | A test suite                                        |
-| `background` | `coreloom_background` | A scheduler poll or recovery that precedes a tenant |
+| Purpose      | Role                   | Used for                                            |
+| ------------ | ---------------------- | --------------------------------------------------- |
+| `migration`  | `flowdular_migrator`   | Applying migrations and resetting a database        |
+| `runtime`    | `flowdular_runtime`    | The deployed application                            |
+| `preview`    | `flowdular_runtime`    | A local run and the sandbox preview                 |
+| `test`       | `flowdular_runtime`    | A test suite                                        |
+| `background` | `flowdular_background` | A scheduler poll or recovery that precedes a tenant |
 
 A runtime acquires its leases lazily, one per runtime, and releases them from
 composition `dispose()`. `modules/profile/src/server/runtime.ts` is the shape:
@@ -164,14 +164,14 @@ codes.
 
 Every tenant table enables and forces row-level security and carries a policy
 whose `USING` and `WITH CHECK` compare `tenant_id` with the transaction-local
-`coreloom.tenant_id` setting:
+`flowdular.tenant_id` setting:
 
 ```sql
 ALTER TABLE profile_records ENABLE ROW LEVEL SECURITY;
 ALTER TABLE profile_records FORCE ROW LEVEL SECURITY;
 CREATE POLICY profile_records_tenant_policy ON profile_records
-  USING (tenant_id = current_setting('coreloom.tenant_id', true))
-  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+  USING (tenant_id = current_setting('flowdular.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('flowdular.tenant_id', true));
 ```
 
 `database.transaction(body, { tenantId, access })` sets that value for the
@@ -201,7 +201,7 @@ repository.
 
 ## Migrations
 
-The ledger is `_coreloom_migrations_v2`. It carries the module namespace because
+The ledger is `_flowdular_migrations_v2`. It carries the module namespace because
 every module shares one database. Checksums cover the exact SQL, and a mismatch
 is checked before any outstanding migration runs.
 
@@ -257,7 +257,7 @@ schema.
 `migration verify` checks that every applied ledger checksum still matches, that
 every tenant table a migration leaves behind has `ENABLE ROW LEVEL SECURITY`,
 `FORCE ROW LEVEL SECURITY` and a tenant policy declared after the last statement
-that puts the table in place, that a `coreloom_background` policy grants no more
+that puts the table in place, that a `flowdular_background` policy grants no more
 than `FOR SELECT`, and that every `migrations/*.up.sql` file has a matching id in
 `databaseMigrations` and the other way round.
 
@@ -272,10 +272,10 @@ A table it may poll says so itself, in its own migration:
 
 ```sql
 CREATE POLICY <table>_background_policy ON <table>
-  FOR SELECT TO coreloom_background
+  FOR SELECT TO flowdular_background
   USING (<the narrowest predicate that still finds the work>);
-REVOKE SELECT ON <table> FROM coreloom_background;
-GRANT SELECT (<only the columns the poll reads>) ON <table> TO coreloom_background;
+REVOKE SELECT ON <table> FROM flowdular_background;
+GRANT SELECT (<only the columns the poll reads>) ON <table> TO flowdular_background;
 ```
 
 A table that forgets to is invisible to that role, and every column outside the

package/agent-template/docs/design-system.md

@@ -270,7 +270,7 @@ them; outside the shell the English defaults and the host locale apply.
 | `Tabs`             | Accessible tablist: required `id`, `items` (`id`, `label`, `disabled`), `active`, `onChange`, `label`; arrows, Home and End move roving focus, an `active` that names no enabled tab selects the first enabled one, and the caller renders the panel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `SortableList`     | Reorderable list: required `id`, `label`, `items` (`id`, `label`), `onReorder(ids)`, `handleLabel(item)`, `instructions`, `announce(event)`, `renderItem(item, index)`, `disabled`; a grip per item drags with a pointer or picks up, moves and drops from the keyboard, with a polite live region                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `ToastHost`        | Renders the toast queue: `label`, `closeLabel`, optional `store`. Raise toasts with `toasts.success/error/info(message)`; `createToastStore` makes a scoped queue                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `PageHeader`       | Every view starts with it: `eyebrow`, `title`, `description`; children render as right-side actions                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `PageHeader`       | Every view starts with it: `eyebrow`, `title`, `description`; children render as right-side actions, which move under the title and wrap onto more rows when the header is too narrow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `EmptyState`       | `icon`, `title`, children, optional `code`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | `Alert`            | Inline message: `tone` danger (default), warning, info                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `Drawer`           | Editor panel over the records: `open`, `title`, `subtitle`, `width` md/lg, `onClose`; traps Tab and restores focus to the opener                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

package/agent-template/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting started
 
-Run Flowdular on your machine, seed a demo workspace, and sign in.
+Run Flowdular on your machine, create a workspace, and sign in.
 
 ## Requirements
 
@@ -19,48 +19,40 @@ pnpm flowdular doctor
 `doctor` reports workspace health (configuration, enabled modules, generated
 composition, guardrail files). Add `--json` for a machine-readable envelope.
 
-## Seed a local demo
-
-`pnpm flowdular setup` opens an interactive wizard. Choose a local demo, configure PostgreSQL, or check the existing configuration. Local initialization requires confirmation and a stopped application.
-
-For scripts and CI, `setup quick` is a destructive local reset. It prints its full plan first and
-writes only after a typed confirmation:
+## Run the platform
 
 ```bash
-pnpm flowdular setup quick                                     # dry run, prints the plan
-pnpm flowdular setup quick --apply --confirm reset-local-auth  # resets and seeds
+pnpm dev
 ```
 
-Stop `pnpm dev` before applying it. Quick setup is blocked outside development
-and test, and must never point at a deployed database.
+On the first run, open [localhost:4310/setup](http://localhost:4310/setup).
+Enter the one-time token from the terminal, then create your
+workspace and owner account. Embedded PostgreSQL is already configured. Restart
+`pnpm dev` after setup and sign in with that account.
 
-It creates two demo tenants (Operations Demo, Finance Demo) and two logins:
+Vite HMR covers TSRX, TypeScript and styles. The launcher keeps tool warnings
+quiet; use `pnpm dev -- --verbose` for full diagnostics. `pnpm dev` runs
+`module sync` first, so a composition change is picked up without a manual
+step. The session lives in an HttpOnly cookie and carries the scopes of the
+selected tenant membership. A bookmark pointing at another workspace you
+belong to switches the session on load.
 
-| Account             | Password         | Role                       |
-| ------------------- | ---------------- | -------------------------- |
-| `admin@example.com` | `Owner!23456789` | Owner of both demo tenants |
-| `user@example.com`  | `Member!2345678` | Reduced scope member       |
+`Development` navigation is visible only to tenant owners; server permissions
+stay authoritative either way.
 
-## Run the platform
+## Optional local demo reset
+
+`pnpm flowdular setup quick` resets local authentication data and seeds two
+demo workspaces. It is for development or test databases only. Stop `pnpm dev`
+and review the dry-run plan before applying it:
 
 ```bash
-pnpm dev
+pnpm flowdular setup quick                                     # dry run, prints the plan
+pnpm flowdular setup quick --apply --confirm reset-local-auth  # resets and seeds
 ```
 
-Open `http://localhost:4310`. Vite HMR covers TSRX, TypeScript and styles. The
-launcher keeps tool warnings quiet; use `pnpm dev -- --verbose` for full
-diagnostics. `pnpm dev` runs `module sync` first, so a composition change is
-picked up without a manual step.
-
-The first visit opens the `auth.core` sign-in flow. The session lives in an
-HttpOnly cookie and carries the scopes of the selected tenant membership. On a
-clean database the sign-up wizard is available: workspace name plus a unique
-workspace id (the first URL segment, `/{workspace}/{view}`), then the
-administrator account, then an optional email confirmation step. A bookmark
-pointing at another workspace you belong to switches the session on load.
-
-`Development` navigation is visible only to tenant owners; server permissions
-stay authoritative either way.
+The demo logins are `admin@example.com` / `Owner!23456789` (owner) and
+`user@example.com` / `Member!2345678` (member).
 
 ## Where local state lives
 
@@ -69,6 +61,7 @@ module shares one embedded PostgreSQL in `.flowdular/data/pglite`, which
 `FD_DATABASE_PGLITE_DIRECTORY` can redirect. Point `FD_DATABASE_ADAPTER` at
 `postgresql` and give it `FD_DATABASE_URL` to run against a real server instead.
 See [configuration.md](configuration.md).
+Workspaces from Flowdular 0.5 or earlier: see [flowdular-rename.md](https://github.com/flowdular/flowdular/blob/main/docs/flowdular-rename.md).
 
 ## Migrating preserved state from `.octane-erp`
 

package/agent-template/docs/module-distribution.md

@@ -1,103 +1,96 @@
-# Installing official modules
+# Module Studio
 
-Core is maintained in [Flowdular/flowdular](https://github.com/Flowdular/flowdular).
-[Flowdular/official-modules](https://github.com/Flowdular/official-modules) owns
-expenses, parties and catalog, including their source, reviews and immutable
-release artifacts. The landing is in [Flowdular/landing](https://github.com/Flowdular/landing).
+Module Studio uses one reviewable plan for a module source change. A platform
+checkout owns its sources in `flowdular.module-sources.json`, its exact plans in
+`module-plans/<sha256>.json`, and installed source hashes in
+`flowdular.modules.lock.json`. Commit these files with the application when
+they change. A catalog can be a local JSON file or an HTTPS URL. A Git source
+names a repository and a full commit, and may itself be local or HTTPS. No
+publisher or repository name is built into the installer.
 
 ```sh
-pnpm flowdular module search expenses
-pnpm flowdular module info expenses.core
-pnpm flowdular module install expenses.core@0.8.1
-pnpm flowdular module install expenses.core@0.8.1 --apply
+pnpm flowdular module source add community https://modules.example/registry/index.json --apply
+pnpm flowdular module source add team https://github.com/acme/modules.git \
+  --git-commit <40-character-commit> --catalog-path registry/index.json --apply
+pnpm flowdular module source add local ./registry/index.json --apply
+pnpm flowdular module source list
+pnpm flowdular module search expenses --source community
+pnpm flowdular module plan expenses.core@1.2.0 --source community --apply
+pnpm flowdular module plan show <plan-id>
+pnpm flowdular module apply <plan-id> --apply
 pnpm flowdular module enable expenses.core --apply
-pnpm flowdular module validate --locked
+pnpm build
 ```
 
-Without `--apply`, installation and updates return a plan and write nothing.
-Installation downloads source into the first configured module root and writes
-`flowdular.modules.lock.json`. It does not install npm dependencies, run downloaded
-scripts, activate modules, grant scopes or touch a database. Enablement links npm
-packages with install lifecycle scripts disabled, generates composition and runs
-its existing scope-grant flow. Review the source before enabling it.
-
-`module update <id[@version]> [--apply]` requires an installer-managed module and
-refuses local source changes, removed or edited historical migrations, incompatible
-versions and downgrades. Additional source files count as local edits. Generated
-`dist`, `node_modules` and Git metadata do not. `module validate --locked` requires
-a lock and checks source hashes as well as ordinary manifest/dependency validation.
-
-The installer resolves a consistent dependency closure, including diamond
-constraints, within a bounded search budget. Existing workspace/package versions
-are preserved. Registry and runtime validation share semver semantics, including
-pre-1.0 caret ranges. Every module declares `platformApi` as a range
-(`^0.1.0`); the current platform API is `PLATFORM_API_VERSION` in `packages/contracts/src/index.ts` and `module search --compatible`
-filters releases by it. A release that declares `requires` is resolved together
-with the newest compatible release providing each required capability.
+`source add`, `plan`, and `apply` preview their work unless `--apply` is present.
+With exactly one configured source, `--source` may be omitted. `module plan
+list` shows saved plans; `module plan remove <plan-id> --apply` deletes an
+obsolete plan. At most 32 plans may exist at once, with 4 MiB per plan and
+8 MiB in total. A plan records the selected
+releases, artifact SHA-256, Git commit where applicable, dependency closure,
+requested permissions, migration file hashes, and server/client build impact.
+Its ID hashes the plan content. Applying it refuses changed workspace module
+manifests or a changed install lock and verifies every artifact again. If the
+source is no longer available, regenerate or provide it again; the plan does
+not contain executable source bytes.
+
+Installation copies reviewed source into a configured module root and writes
+the install lock. It does not run downloaded scripts, npm install, migrations,
+or permission grants. `module enable --apply` links the package, regenerates
+composition and follows the platform's scope grant process. Rebuild and
+restart the application to serve new code. A deployed container shows plans
+and module state in Administration, Module Studio; it never writes its own code.
+For creating or changing your own module, the same view links to Sandbox when
+`sandbox.core` is active. Sandbox keeps the approved spec hash, gate and PR
+checks, and delivers to the workspace or its configured Git repository.
 
 ## Trust and recovery
 
-The default catalog is the official repository's `registry/index.json`. HTTPS
-artifact URLs must point to the declared immutable commit in that same repository.
-Downloads have time and size limits. Source bundles are bounded JSON records of
-regular files, validated for path escapes, duplicate names, digest mismatches,
-identity, portable dependencies and stale/missing review evidence. No archive
-extraction or install lifecycle scripts execute during source installation.
-
-A checksum does not authenticate an arbitrary publisher. The trust root is the
-configured official repository over HTTPS. An operator can explicitly supply
-`--registry /absolute/path/index.json` for an offline catalog; artifacts must stay
-inside that catalog directory. Third-party remote registries are not supported.
-A review report is an assessment, not a guarantee or a defense against a malicious
-publisher. Official release CI also executes the checks independently.
-
-Concurrent installs share an exclusive transaction directory. Recover an
-interrupted operation with `module recover` and `module recover --apply` after
-its owner process has exited. Recovery restores the previous source and module
-lock and refuses to discard conflicting edits. Keep the transaction directory
-when a conflict is reported. Source recovery never rolls back database migrations.
-Installation and updates are host/operator capabilities and do not expand sandbox
-agents' network, filesystem or tool permissions.
+Only a configured host CLI resolves sources. Sandbox specialists do not gain
+network, Git, database or filesystem permissions from a source entry. HTTPS
+downloads reject redirects and have time and size limits. HTTPS artifacts must
+use the catalog origin and a path containing their declared source commit.
+The artifact digest is verified after download. Git checkouts verify their full
+commit. Catalogs and artifacts are bounded; paths, manifests, package scripts,
+review evidence and approved specs are checked before a plan is saved. A
+checksum identifies bytes but does not certify a publisher, so review the
+source and permissions before `module apply` and `module enable`.
+
+Updates use `module plan <id[@version]> --source <name> --update --apply`.
+The installer refuses local changes, changed historical migrations and
+downgrades. `module validate --locked` checks installed file hashes. Installs
+use an exclusive transaction directory; after a process crash, run `module
+recover` and then `module recover --apply`. Recovery restores source and lock
+state, not database migrations. Source-list edits use a separate
+`flowdular.module-sources.json.lock` directory. If a host process crashes
+during that short write, confirm no other source command is running and remove
+that stale directory before retrying.
+Plan writes use the same atomic pattern and a `module-plans.lock` directory.
+After a crash, confirm the writer has stopped and remove a stale plan lock
+before retrying; no partial plan is published.
+
+Scripts that called `module install` or `module update` with `--registry` must
+add that catalog as a named source, save a plan, and apply its ID. An existing
+`flowdular.modules.lock.json` remains the installed-source record, so an
+already managed module can use `module plan <id> --update --apply` for its next
+release. No direct registry installation path remains.
+Automation that imported `installModule` from `flowdular/distribution` must use
+the host CLI plan and apply commands; that direct install export was removed.
+
+The old `official-modules` Sandbox delivery target was removed. Change
+`sandbox.delivery.targets` to `workspace` or `git-pr`; `git-pr` points to the
+platform repository configured in `flowdular.json`. A catalog publisher can
+use any Git repository and publish immutable artifacts independently. Historical
+review and RFC documents retain the old project name as provenance.
 
 ## SDK publication and consumer checks
 
 ```sh
 pnpm release:pack
 pnpm release:smoke
-# Also install and test actual source artifacts from the official repo:
-node scripts/smoke-sdk.mjs release-artifacts/sdk /path/to/official-modules/registry/local-index.json
 ```
 
-`release-artifacts/sdk/sdk.json` lists exactly `@flowdular/sdk`, `flowdular`, `create-flowdular` and `@flowdular/sandbox`, with versions, tarballs
-and SHA-256 digests. Publish those tarballs with `npm publish <tarball> --access public`.
-Publish all SDK dependencies before consumers install the starter. The three
-business modules and the landing are not in this npm publication set. Keep release
-artifacts outside runtime state directories; creating both `.flowdular` and legacy
-`.coreloom` state would correctly stop the application.
-
-The smoke test creates a separate project and resolves SDK dependencies from
-packed artifacts, without aliases or symlinks into core sources. With a module
-catalog it installs all module source artifacts, enables their source composition,
-checks the lock, typechecks and executes the consumer's tests. Its composition
-check does not grant tenant scopes; auth CLI tests cover that separate boundary.
-
-Sandbox examples use `.ai/references/catalog`, generated from a reviewed official
-artifact. `pnpm reference:check` verifies every file against the pinned provenance
-record. Do not edit the generated reference. To update it, build the CLI and run
-`scripts/module-reference.mjs` with `--artifact`, `--sha256`, `--source-commit` and
-`--apply`. Skills and sandbox preparation refer to that offline snapshot.
-
-`pnpm release:publish` previews the exact publication set after validating every
-artifact digest. The operator can then use `pnpm release:publish --apply` after npm
-authentication. It skips already-published identical tarballs and stops if a
-version exists with different bytes. No npm publication is performed by packing,
-smoke testing or the default publication preview.
-
-The `SDK consumer smoke` workflow (`.github/workflows/sdk-release.yml`, job
-`consumer`) runs the pack and the smoke on every pull request and push to main
-that touches `packages`, `modules` or `scripts`. It never publishes: its token
-can only read the repository, and the packed tarballs are kept as an Actions
-artifact only after a merge to main. `pnpm verify` is not repeated there, the
-CI workflow owns it.
-
-The SDK is assembled from private internal workspaces. Import UI from `@flowdular/sdk/ui` and styles from `@flowdular/sdk/ui/styles`; use `@flowdular/sdk/server`, `client`, `contracts` or `modules/<name>` for other surfaces. There is no root SDK barrel, so browser imports do not load server entrypoints. See [npm publication](https://github.com/flowdular/flowdular/blob/main/docs/npm-publication.md).
+`release-artifacts/sdk/sdk.json` lists the SDK, CLI, project generator and
+Sandbox tarballs with SHA-256 digests. Publication is separate from packing
+and smoke tests. The project generator and SDK must be released together so a
+new application's module tooling sees the same contracts.

package/agent-template/docs/module-web-surfaces.md

@@ -140,13 +140,15 @@ in front of it, as the bundled Node server does.
 ### Backoffice address
 
 The first-run setup includes **Backoffice address**, defaulting to `/app` (or the
-installation's configured default). Choose `/backoffice` to leave `/` available
-for a storefront. Setup validates the address, includes it in the review, and
-writes `FD_APPLICATION_PATH=/backoffice` alongside the database settings. Restart
-after setup; no client rebuild is needed for this environment setting. On a
-read-only deployment setup provides the environment block to paste into the
-hosting service. If `FD_APPLICATION_PATH` already exists in the environment, it
-is authoritative; setup cannot silently replace it.
+installation's configured default). When choosing a database in the wizard, an
+operator can choose `/backoffice` to leave `/` available for a storefront. Setup
+validates the address, includes it in the review, and writes
+`FD_APPLICATION_PATH=/backoffice` alongside the database settings. Restart after
+setup; no client rebuild is needed. When the database is already configured by
+the deployment, the wizard skips that step and the deployment's
+`FD_APPLICATION_PATH` controls the address. A read-only deployment must store
+new settings in its environment before restart. Setup never echoes connection
+secrets back to the browser.
 
 For configuration managed in source control, add:
 

package/agent-template/docs/modules.md

@@ -222,7 +222,9 @@ dependents, which the bump command does. `module validate` reports
 `PLATFORM_API_MISSING` when a manifest lacks `platformApi`.
 
 `platformApi` is the range of the platform contract the module compiles against
-(`^0.1.0`). The contract surface is pinned in
+(`^0.2.0`). Module sync and install refuse a manifest without one, and a range
+that also admits a version before the platform's current minor line, such as
+`*` or `>=0.1.0`. The contract surface is pinned in
 `packages/kernel/platform-api.snapshot.d.ts`; a change to it without a
 `PLATFORM_API_VERSION` bump fails `pnpm verify`. `module search --compatible`
 lists only releases whose range accepts the running platform.

package/agent-template/platform/scripts/build.mjs

@@ -7,6 +7,13 @@ import { join } from 'node:path';
 const stateDirectory = mkdtempSync(join(tmpdir(), 'flowdular-build-'));
 const buildSecret = () => randomBytes(32).toString('base64');
 
+/* Vite clears its output trees, but can leave hidden runtime state at the
+   dist root. A prior preview must never become part of the next bundle. */
+rmSync(join(import.meta.dirname, '..', 'dist'), {
+	recursive: true,
+	force: true,
+});
+
 /* The Octane plugin evaluates the server composition while bundling it. Give
    that build-time process isolated state and ephemeral keys, without using deployment database settings or encryption keys. The emitted server still reads its real
    production environment when it starts. */

package/dist/bin.js

@@ -294,7 +294,6 @@ function nextSteps(input) {
   return [
     `cd ${input.directory}`,
     ...input.installed ? [] : [`${input.packageManager} install`],
-    runScript(input.packageManager, "flowdular", "setup"),
     runScript(input.packageManager, "dev")
   ];
 }
@@ -303,8 +302,7 @@ function renderNextSteps(input, color = false) {
   const labels = [
     "Open your project",
     ...input.installed ? [] : ["Install dependencies"],
-    "Choose local demo or PostgreSQL",
-    "Start your app"
+    "Start your app and first-run setup"
   ];
   return [
     "",
@@ -322,9 +320,8 @@ function renderNextSteps(input, color = false) {
     `  ${paint("Build a module by chat", "dim")}  ${paint(runScript(input.packageManager, "sandbox"), "bold")}`,
     `  ${paint("Agent guidance", "dim")}          AGENTS.md, CLAUDE.md, .ai/skills`,
     "",
-    `  ${paint("Local URL", "dim")}   ${paint(DEV_URL, "cyan")}`,
-    `  ${paint("Demo login", "dim")}  admin@example.com`,
-    `  ${paint("Demo account is created only with local demo setup.", "dim")}`,
+    `  ${paint("Setup URL", "dim")}  ${paint(`${DEV_URL}/setup`, "cyan")}`,
+    `  ${paint("Setup opens in a browser when available. Use the printed token, then choose your workspace owner.", "dim")}`,
     ""
   ].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-flowdular",
-	"version": "0.5.1",
+	"version": "0.6.0",
 	"type": "module",
 	"description": "Scaffold a Flowdular application: the platform, one example module and the secrets a fresh install needs.",
 	"license": "MIT",

package/template/default/.env.example

@@ -13,9 +13,9 @@ FD_PORT=3000
 # every tenant table forces actually binds the app, and the background role
 # serves the cross-tenant scheduler poll. pglite is refused in production.
 FD_DATABASE_ADAPTER=postgresql
-FD_DATABASE_URL=postgresql://coreloom_runtime:REPLACE_ME@postgres:5432/flowdular
-FD_DATABASE_MIGRATOR_URL=postgresql://coreloom_migrator:REPLACE_ME@postgres:5432/flowdular
-FD_DATABASE_BACKGROUND_URL=postgresql://coreloom_background:REPLACE_ME@postgres:5432/flowdular
+FD_DATABASE_URL=postgresql://flowdular_runtime:REPLACE_ME@postgres:5432/flowdular
+FD_DATABASE_MIGRATOR_URL=postgresql://flowdular_migrator:REPLACE_ME@postgres:5432/flowdular
+FD_DATABASE_BACKGROUND_URL=postgresql://flowdular_background:REPLACE_ME@postgres:5432/flowdular
 FD_DATABASE_TLS=verify-full
 FD_DATABASE_TLS_CA_FILE=/tls/server.crt
 

package/template/default/.vercelignore

@@ -0,0 +1,8 @@
+# vercel deploy uploads whatever its built-in list and this file leave in.
+# The built-in list keeps neither .env files nor local state out, and
+# .flowdular/deploy holds the production keys.
+.env
+.env.*
+!.env.example
+.flowdular
+.octane-erp