create-flowdular 0.4.3 → 0.6.0

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

@@ -65,6 +65,12 @@ at least one entity (`SPEC_ACTION_PERMISSION_UNKNOWN`, `SPEC_ENTITY_UNKNOWN`,
 `SPEC_DUPLICATE_ID`). A client without a list screen, or a stored entity with no
 tenant-unique field, is a warning.
 
+An action may not declare `risk: external`. A module never calls another system
+directly: the harness and the CLI runner both refuse an external action, so the
+specification catches it here instead of at delivery
+(`SPEC_ACTION_RISK_UNSUPPORTED`). Model the effect as a connector definition plus
+an adapter, or lower the risk.
+
 The three optional sections have checks of their own. `research.evidenceOwner`
 and `templates[].inputEntity` must name an entity (`SPEC_ENTITY_UNKNOWN`). An
 adapter id must start with the module id (`SPEC_ADAPTER_ID_NAMESPACE`); a source
@@ -216,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/docs/sandbox.md

@@ -12,12 +12,85 @@ Full documentation lives with the package:
 
 ```bash
 pnpm sandbox            # from this repository
-npx @flowdular/sandbox   # from any Flowdular workspace
+npx @flowdular/sandbox   # from any Flowdular workspace, or from an empty one
 ```
 
-The launcher walks up to `flowdular.json` to find the workspace and opens
-`http://127.0.0.1:4320`. `--port`, `--workspace`, `--host` and `--mode` override
-the defaults.
+In an empty directory, the command creates a standalone Flowdular application,
+installs its dependencies, starts it with a local embedded PostgreSQL database,
+prepares the sandbox credential and serves the dashboard on
+`http://127.0.0.1:4320`. You can then describe the module in the dashboard.
+
+## Start with nothing installed
+
+There is no checkout step.
+
+```bash
+mkdir acme-erp && cd acme-erp
+npx @flowdular/sandbox
+```
+
+The launcher uses `create-flowdular` at the sandbox package's exact version,
+installs the generated application and makes its first local Git commit. It
+reuses that workspace on later runs. The application lands in `./flowdular`
+unless `--workspace <path>` names another directory. No remote is created until
+you choose one.
+
+The repository dialog can create a private GitHub repository or connect an
+empty one after showing the initial push plan. If creation is interrupted, the
+same dialog shows the pending attempt. You can resume it or discard its local
+record after GitHub returns an authenticated 404. A private repository hidden
+from the current account may also return 404, so check GitHub if creation may
+have succeeded.
+
+To work on an existing platform repository, run
+`npx @flowdular/sandbox --connect <git-url>` and optionally `--branch <name>`.
+The launcher clones into a new directory, checks `flowdular.json` and the
+committed pnpm lockfile, then installs dependencies. Run from an existing
+Flowdular checkout to reuse it without cloning. `--no-bootstrap` refuses to
+create an application. The older `--repository` and pinned `--ref` options
+remain available when you deliberately want a checkout of the Flowdular core
+repository.
+
+The launcher refuses to create or clone into a directory containing unrelated
+files. For application generation, Git and pnpm are checked before files are
+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.
+
+## The credential is prepared, not pasted
+
+A business user used to sign in to the application, create an API token with
+three scopes, paste it into the sandbox and grant that account sandbox access
+before describing anything. None of those is a business decision, so the
+application does them during its own boot when the launcher asks, and the
+launcher collects the result.
+
+- It runs only when the launcher started the application, so an application
+  someone else owns is never asked to create an account.
+- It reuses an existing workspace and account rather than replacing them, and
+  mints exactly one token for the life of the deployment.
+- The token carries the four sandbox scopes and nothing else.
+- It is written to a `0600` file that the launcher seals into its own
+  configuration and deletes. It is never printed, so it reaches no terminal, log
+  or transcript.
+- Token management over HTTP is unchanged: `POST /api/auth/api-tokens` still
+  refuses a machine credential, and no route was added for this.
+
+The account is `sandbox-operator@example.com` in a `sandbox` workspace, with a
+password nobody has. It exists to hold the grant.
+
+**A failed provision never stops the application.** It is a convenience for a
+local operator, and an application that will not serve because a sandbox account
+could not be created is worse than one that serves and reports the problem.
+
+For a remote deployment, or a sandbox started some other way, the dashboard says
+what is missing. One command fixes it:
+
+```bash
+pnpm flowdular sandbox provision --apply
+```
 
 ## Connect it to a running application
 
@@ -29,6 +102,8 @@ security a deployment has, and it is thrown away with the session.
 1. In the application, open Administration, API tokens, and issue a token with
    `sandbox.access.use` plus the read scopes the preview should see. Add
    `sandbox.preview.data` for live data and `sandbox.modules.eject` for eject.
+   Enable token writes so the sandbox can record sessions, eject modules and
+   publish the application repository when you request it.
 2. Grant sandbox access to the account, in the app under Development, Sandbox,
    or from the CLI:
 
@@ -38,9 +113,11 @@ pnpm flowdular sandbox access --tenant operations-demo
 ```
 
 3. Paste the token and the application address into the sandbox connect screen.
+   The same screen asks for a model provider and key, unless the workspace
+   already carries one, in which case it names the variable it adopted.
 
-The token is encrypted at rest under `.flowdular/sandbox/secret.key` and is never
-returned to the browser. The application may run anywhere: locally on
+The token and the model key are encrypted at rest under
+`.flowdular/sandbox/secret.key` and are never returned to the browser. The application may run anywhere: locally on
 `http://127.0.0.1:4310` or a deployment.
 
 ## Modes
@@ -54,6 +131,25 @@ A non-loopback `--host` forces `self-hosted`. A sandbox that cannot prove it is
 loopback never offers a local binary, because a local binary carries the
 operator's own login.
 
+The bring-your-own-key driver takes its credential from the sandbox model
+settings, or, when none is saved there, from `ANTHROPIC_API_KEY`,
+`OPENAI_API_KEY`, `AZURE_API_KEY` or `AI_GATEWAY_API_KEY` in the environment or
+the workspace `.env`. A scaffolded application ships the first of those as an
+empty placeholder, so pasting a key is the whole setup.
+
+## Typed decisions
+
+The brief classification the planner performs (which module, spans several,
+which specialist starts) can be answered by a decision provider instead of a
+coding-agent turn. It is off by default, turned on per sandbox with
+`decisionsEnabled` through `POST /sandbox/api/config`, and takes its credential
+from the sandbox configuration or `TYPESAFE_API_KEY` in the environment or the
+workspace `.env`. Answers below their confidence thresholds, a brief that spans
+modules, and any provider failure all fall back to the workspace rules and the
+planner turn. Implementation writing stays with the coding agent: a decision
+provider generates no text and drives no tools. See
+[`packages/sandbox/README.md`](https://github.com/flowdular/flowdular/blob/main/packages/sandbox/README.md) for the settings.
+
 ## How a session works
 
 A planner names the modules the brief touches and the first specialist role.
@@ -147,6 +243,21 @@ commits the same change on a branch and opens a pull request; the operator's
 working tree and index stay untouched because the work happens in a detached
 worktree under `.flowdular/sandbox/worktrees/<session id>`, removed afterwards.
 
+For an application generated by the sandbox, open **GitHub settings** and then
+**Set up repository**. Choose an existing empty GitHub repository or
+create a new private one. The sandbox shows the repository, local commit and
+target branch for review before the operator confirms the first push. It then
+adds a local `app` remote, pushes `main` without rewriting remote history and
+configures GitHub delivery to use that remote. A repository that already has
+commits should be opened with `--connect` when launching the sandbox. GitHub
+CLI authentication or a token saved in GitHub settings is needed for creating
+and pushing; the setup action also requires `sandbox.modules.eject`.
+
+After the module specification is approved and the gates pass, choose the
+`git-pr` delivery target to push a branch and open its review. The sandbox does
+not approve a specification or push module code merely because a repository
+was connected.
+
 ### Configuration
 
 Project settings live in `flowdular.json` under `sandbox.delivery`, read at

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/agent-template/rulesync.jsonc

@@ -3,7 +3,7 @@
 	"inputRoots": [".ai"],
 	"outputRoots": ["."],
 	"targets": ["codexcli", "claudecode"],
-	"features": ["rules", "skills"],
+	"features": ["rules", "skills", "subagents"],
 	"delete": true,
 	"verbose": false,
 	"silent": false,

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");
 }
@@ -386,6 +383,15 @@ function renderEnvironmentFile(secrets) {
     "",
     "# 32 byte keys, generated once for this app; MFA uses base64url.",
     ...SECRET_KEYS.map((key) => `${key}=${secrets[key]}`),
+    "",
+    "# Model key for the chat-first sandbox (pnpm sandbox). Paste one here and",
+    "# the sandbox offers that model on the next start, with no further setup.",
+    "# OPENAI_API_KEY, AZURE_API_KEY and AI_GATEWAY_API_KEY are read the same",
+    "# way, with the model chosen in the sandbox model settings. A variable",
+    "# exported in the shell wins over this file. The application's own agents",
+    "# keep their credentials in the workspace vault instead: open",
+    "# Administration, AI providers.",
+    "ANTHROPIC_API_KEY=",
     ""
   ].join("\n");
 }

package/package.json

@@ -1,12 +1,12 @@
 {
 	"name": "create-flowdular",
-	"version": "0.4.3",
+	"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",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/flowdular/flowdular.git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
 		"directory": "packages/create-flowdular"
 	},
 	"homepage": "https://flowdular.com",

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
 
@@ -91,6 +91,13 @@ FD_DATABASE_MIGRATOR_PASSWORD=
 FD_DATABASE_RUNTIME_PASSWORD=
 FD_DATABASE_BACKGROUND_PASSWORD=
 
+# Model key for a self-hosted sandbox. The application itself never reads it:
+# agents.core keeps every provider credential sealed in the workspace vault,
+# configured in Administration, AI providers. The sandbox reads this name,
+# OPENAI_API_KEY, AZURE_API_KEY and AI_GATEWAY_API_KEY from the environment or
+# from the workspace .env, and an exported variable wins over the file.
+ANTHROPIC_API_KEY=
+
 # Prometheus exposition on GET /api/metrics. Leave FD_METRICS unset to keep it off.
 FD_METRICS=false
 FD_METRICS_TOKEN=

package/template/default/.prettierignore

@@ -6,4 +6,6 @@ AGENTS.md
 CLAUDE.md
 .agents/skills/
 .claude/skills/
+.claude/agents/
+.codex/agents/
 .ai/references/

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