create-flowdular 0.5.1 → 0.6.1

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,44 @@ 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.
+
+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. Ctrl+C, SIGTERM or a closed terminal stops the server after open requests
+finish and background work drains, within six seconds. A second Ctrl+C does not
+cut that short, because pnpm already delivers every Ctrl+C more than once;
+Ctrl+\ stops it at once.
+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.
 
-It creates two demo tenants (Operations Demo, Finance Demo) and two logins:
+`Development` navigation is visible only to tenant owners; server permissions
+stay authoritative either way.
 
-| Account             | Password         | Role                       |
-| ------------------- | ---------------- | -------------------------- |
-| `admin@example.com` | `Owner!23456789` | Owner of both demo tenants |
-| `user@example.com`  | `Member!2345678` | Reduced scope member       |
+## Optional local demo reset
 
-## Run the platform
+`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 +65,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

@@ -181,7 +181,9 @@ package is not linked yet, and regenerates
 grants the scopes declared by each newly enabled module to every workspace owner
 through `auth sync-scopes`; a failed grant is reported as
 `MODULE_SCOPES_SYNC_FAILED`, and when `auth.core` is unavailable the grant is
-skipped with a warning.
+skipped with a warning. That grant reaches only workspaces that already exist,
+so first-run setup grants the permissions of every enabled module to the owner
+it creates.
 
 `disable` refuses while another enabled module depends on the target, then
 removes it and regenerates. `system.core` and `auth.core` are protected.
@@ -222,7 +224,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/docs/sandbox.md

@@ -57,7 +57,18 @@ written.
 
 An application already serving on the platform port is left alone, and no
 credential is prepared for it. `--platform` and `--platform-port` say otherwise
-explicitly; `--no-platform` never starts one.
+explicitly; `--no-platform` never starts one. An application the launcher
+started stops with it, including when the terminal closes or the launcher is
+killed. It gets eight seconds to drain before it is killed, two more than the
+six the development server gives itself; both figures live in
+`@flowdular/sdk/dev-console/shutdown`. The installs, gates and Git commands the
+sandbox runs stop with it the same way.
+
+One sandbox runs per workspace. A second launcher, or `pnpm eval`, on a
+workspace whose sandbox is running exits with the PID of the process that holds
+it. The hold is the directory `.flowdular/sandbox/workspace.lock`; it goes away
+when that process ends, and one left by a process that was killed outright is
+taken over by the next start.
 
 ## The credential is prepared, not pasted
 
@@ -349,9 +360,17 @@ of 1 to 120 characters, and a recommendation that must be one of those options.
 `allowFreeText` defaults to false, and a question with neither an option nor
 free text cannot be answered, so it is refused. The block has to be the last
 thing in the reply apart from the mandatory handoff line, and a reply carries at
-most one. A block the sandbox cannot read is a warning on that turn, never a
-failed turn: the words of the reply still stand and the transcript says why the
-block was ignored.
+most one. A block the sandbox cannot read is never a failed turn and never
+dropped in silence: the transcript says why it was refused, and the specialist
+gets the reason and these limits for one repair turn. A second refusal in a row
+stops for the operator, who answers in words. A turn that asks stops for the
+answers, never for approval, and the approval route refuses a module with open
+questions (`409 QUESTIONS_PENDING`). A gate that failed in the same turn waits
+too: the handoff names it, the gates run again after the answering turn, and a
+failure that remains then goes back to the specialist. Such a session is in the
+`awaiting-answers` state, so `awaiting-approval` only ever means an approval.
+`sandbox.core` has no state for open questions, so the platform record keeps
+`awaiting-approval` for it.
 
 A readable block is stored on the session as `pendingQuestions`, with the
 transcript sequence of the message that asked, the role that asked and the

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.1",
 	"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
 
@@ -84,6 +84,11 @@ FD_AUTH_MAIL_TRANSPORT=none
 FD_AUTH_SMTP_URL=
 FD_AUTH_MAIL_FROM=
 
+# Tenant id that overrides the operator workspace, the one that changes platform
+# settings such as the branding and the mail relay. Empty, the workspace auth.core
+# recorded at first-run setup decides (pnpm flowdular auth operator shows it).
+FD_OPERATOR_TENANT=
+
 # Read by infra/docker/compose.yaml only. It builds the three URLs above from
 # these passwords and publishes the container port on FD_PORT.
 FD_POSTGRES_SUPERUSER_PASSWORD=

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

package/template/default/README.md

@@ -7,13 +7,15 @@ example module, and nothing else you have to configure.
 
 ```bash
 pnpm install
-pnpm flowdular setup
 pnpm dev
 ```
 
-Open <http://localhost:4310> and sign in as `admin@example.com`. Quick setup is
-a destructive local reset: stop `pnpm dev` first, and never point it at a
-deployed database.
+On the first run, the server starts the setup page and `pnpm dev` opens it in
+your browser. Enter the one-time token printed in the terminal, then choose
+your workspace and owner account. The embedded database is already selected.
+If a browser cannot open automatically, visit <http://localhost:4310/setup>.
+Restart `pnpm dev` after setup, then sign in with the account you chose. Use
+`pnpm dev -- --no-open` to leave the browser alone.
 
 Local development runs on embedded PostgreSQL, so there is no database server to
 install. Data lives under `.flowdular/data`.
@@ -25,7 +27,7 @@ install. Data lives under `.flowdular/data`.
 | `platform`        | The deployable composition root and the application shell    |
 | `modules/example` | A tenant-scoped record module: API, migration, screen, tests |
 | `specs`           | The platform spec of this application                        |
-| `infra`           | Dockerfile, compose stack and Kubernetes base                |
+| `infra`           | Docker, Kubernetes and Vercel deployment assets              |
 | `flowdular.json`  | Enabled modules and locales, owned by the CLI                |
 | `.env`            | The keys generated for this app. Never commit it             |
 | `.env.example`    | Every key a production deployment reads                      |
@@ -79,19 +81,26 @@ account access, then paste the token and the application address into the
 connect screen.
 
 ```bash
-pnpm flowdular sandbox grant --email admin@example.com --tenant operations-demo --apply
+pnpm flowdular sandbox grant --email <your-owner-email> --tenant <your-workspace-slug> --apply
 ```
 
 ## Deploy
 
 ```bash
-cp .env.example infra/docker/.env   # then fill in every value
-docker compose -f infra/docker/compose.yaml up --build
+node infra/docker/start.mjs
 ```
 
-`.env.example` lists every key the server reads in production. `infra/README.md`
-covers the container image, the PostgreSQL roles and TLS, migrations on rollout,
-and the Kubernetes base.
+The launcher creates `infra/docker/.env` with private database passwords and
+keys, starts PostgreSQL and MinIO, then opens the setup page. Enter the token
+shown in the terminal. The database step is already complete, so you start with
+the workspace owner. `infra/README.md` covers the stack and deployments.
+
+To deploy on Vercel, run `vercel login` and then
+`pnpm flowdular deploy start vercel --apply`. It provisions Neon PostgreSQL, a
+private Blob store and the stable keys, deploys, and prints a one-time token for
+creating the first workspace at `/setup`; `infra/vercel/README.md` walks through
+it and the manual path. Module workers run in a worker Function that Vercel Cron
+and state-changing requests tick.
 
 ## Commands
 

package/template/default/_gitignore

@@ -1,8 +1,9 @@
 node_modules/
 dist/
 .flowdular/
-.env
-.env.*
+# vercel link appends these two lines unless they are already here verbatim.
+.vercel
+.env*
 !.env.example
 *.log
 .DS_Store