create-flowdular 0.4.1 → 0.5.1

package/agent-template/.claude/skills/ux-design/SKILL.md

@@ -81,7 +81,7 @@ Read-only master-detail (runs, playground) keeps `ui-two-col` (+ `--wide-aside`)
 - `Alert`: `tone` danger (default), warning, info.
 - `Avatar`: `name`, `square` (organizations), `large`.
 - `Icon`: `name`, `size` (18 default, 16 in controls, 14 in `Button size="sm"`), `strokeWidth`.
-- `BrandMark`: `size`, `signature`, `tone`; brand moments only.
+- `BrandMark`: `size`, `tone`; three bars with a copper accent bar, brand moments only.
 
 Icon keys (`ICON_PATHS`, `packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog`, `user`, `users`, `shield`, `code`, `modules`, `file-text`, `play`, `bot`, `flask`, `activity`, `plug`, `search`, `chevron-down`, `chevron-left`, `chevron-right`, `chevrons-up-down`, `sort`, `calendar`, `plus`, `panel-left`, `check`, `filter`, `download`, `more`, `external`, `alert`, `x`, `sign-out`, `refresh`, `help`, `info`, `key`, `settings`, `braces`, `copy`. An unknown name renders `modules` silently, so check the list.
 
@@ -93,7 +93,28 @@ Layout `ui-view`, `ui-two-col` (+`--wide-aside`), `ui-grid-2`, `ui-kpi-grid`, `u
 
 User-facing copy lives in every declared `translations/*.json` bundle and is read with fully qualified `t()` keys. Eyebrow names the domain, title names the records, and description is one sentence. Table headers say what the value is. Buttons start with a verb. Loading text ends with `…`. Drawer footer states the constraint the user cannot see. Write natural copy in each locale, with no exclamation marks or database jargon.
 
-## 7. Inspect the rendered screen
+## 7. Design the screen as a preview first
+
+A design is a file, not a description: `modules/<dir>/design/<screen>.html`, beside the spec. It is markup only, dressed by the platform's own stylesheets, so it shows what the screen will look like before a component exists and long before the application boots. An implementation phase reads it the way it reads the spec.
+
+```bash
+pnpm ui:preview modules/<dir>/design/<screen>.html --scaffold   # the record recipe in all five states
+pnpm ui:preview modules/<dir>/design/<screen>.html              # renders it, prints a file:// address
+pnpm ui:preview modules/<dir>/design/<screen>.html --shot .flowdular/ui-preview/<screen>.png
+pnpm ui:preview modules/<dir>/design/<screen>.html --open           # shows it to the person asking
+```
+
+Rules that keep a preview honest:
+
+- Markup only. No `<style>`, no CSS rule, no `<html>` or `<body>`; the command refuses a fragment that carries one. Every visual decision comes from `packages/ui`, which is what stops a preview from becoming a second source of truth.
+- One `<section class="ui-view" data-state="...">` per state: `populated`, `loading`, `empty`, `error`, `denied`. The command labels each one, so a single page answers for all five.
+- Real content. The longest realistic name, a real identifier, the copy the screen will actually carry. A preview of `Lorem ipsum` proves nothing about overflow or alignment.
+- Only classes a stylesheet declares. `pnpm ui-classes:check` fails on a class nothing defines, in a preview and in a `.tsrx` alike, which is the one mistake that compiles, passes its tests and renders unstyled. A class a module needs and the design system lacks is declared in the module's own CSS, as rule 4 says.
+- `--shot` writes a PNG, which is how an agent with no browser looks at its own work. `--open` opens the preview in the person's browser, which is how a design is shown for approval; a correction loop renders without it rather than throwing a window at whoever is at the keyboard.
+
+Hand off the path, not a description. An implementation phase opens the preview, mirrors its structure with the components in section 4, and keeps the copy.
+
+## 8. Inspect the rendered screen
 
 A screen is not finished until it has been looked at. Typecheck and tests say nothing about overflow, alignment, a duplicate label or a column that collapses.
 
@@ -117,6 +138,7 @@ Check the drawer form in the same pass: one label per field, fields top-aligned,
 
 ## Pitfalls
 
+- A preview that renders unstyled is a class nothing declares, not a broken harness; run `pnpm ui-classes:check`.
 - `Kpi value={items.length}` does not typecheck; use `String(items.length)`.
 - A `Tag` for a lifecycle state uses `success` for active and `neutral` for archived, with `dot`.
 - An `Icon` inside `Button size="sm"` is 14, not 18.

package/agent-template/.codex/agents/module-executor.toml

@@ -0,0 +1,17 @@
+name = "module-executor"
+description = "Implement one Flowdular blueprint end to end at the repository root: scaffold from an approved spec, write the module, run the gates and join it to the platform through the CLI. Use once a spec is approved and the change is ready to be built."
+developer_instructions = '''
+Your role prompt is `.ai/agents/module-executor.md`. Read it with the blueprint
+under `.ai/blueprints/<id>/` and the one matching skill in
+`.ai/skills/<name>/SKILL.md` before changing anything.
+
+Implement only what the approved spec's acceptance scenarios describe, inside the
+blueprint's `allowed-paths.yaml`. Join the platform through
+`pnpm flowdular module enable <id> --apply` and `auth sync-scopes`; never edit
+`flowdular.json`, `platform/package.json`, `platform/src/generated/**` or
+`platform/octane.config.ts` by hand.
+
+Run the module gates and `pnpm verify` yourself and report their exact commands
+and results. Never waive a gate. End with `HANDOFF: reviewer - <what to review>`
+or `HANDOFF: none - <blocker>`.
+'''

package/agent-template/.codex/agents/reviewer.toml

@@ -0,0 +1,14 @@
+name = "reviewer"
+description = "Review a finished Flowdular change against its approved spec, the blueprint, the invariants and the executable evidence, and report findings by severity. Use as a separate phase before delivery or a pull request. Reports defects and fixes nothing."
+developer_instructions = '''
+Your role prompt is `.ai/agents/reviewer.md` and the one task skill for this
+phase is `.ai/skills/auto-review/SKILL.md`. Read both before reviewing.
+
+You write no production code. Review the complete requested change, its
+requirements, callers and tests; report concrete findings by severity with file,
+line and failure scenario. Never waive missing or failing verification, and never
+approve a change whose evidence you have not seen run.
+
+End with `HANDOFF: module-executor - <findings to fix>` or
+`HANDOFF: none - <review result and remaining verification>`.
+'''

package/agent-template/.codex/agents/spec-author.toml

@@ -0,0 +1,15 @@
+name = "spec-author"
+description = "Turn a business request into a schema-valid Flowdular module specification at the repository root. Use before any implementation, for a new module spec or a change to an existing one. Writes only modules/<dir>/spec/module.yaml and never approves it."
+developer_instructions = '''
+Your role prompt is `.ai/agents/spec-author.md` and the one task skill for this
+phase is `.ai/skills/spec-interview/SKILL.md`. Read both before writing.
+
+You write only `modules/<dir>/spec/module.yaml`. Propose a platform default for
+every decision and ask the user for what cannot be inferred; never guess a
+business fact. Never set `status: approved`: approval is the user's, recorded by
+the `spec-approval` skill.
+
+`pnpm flowdular spec validate --all --json` must report the file valid before you
+report. End with `HANDOFF: reviewer - spec ready for owner approval` or
+`HANDOFF: none - <open question>`.
+'''

package/agent-template/AGENTS.md

@@ -78,5 +78,6 @@ made in the Flowdular repository and released before this application uses it.
 The skills and examples use @flowdular/sdk subpath imports. For pnpm --filter,
 read the actual module package name from its package.json. Use pnpm verify and
 pnpm build for this application. Root .ai files are editable project guidance;
-run pnpm rules:generate after changing rules or skills, then pnpm rules:check.
-AGENTS.md, CLAUDE.md, .agents/skills and .claude/skills are generated copies.
+run pnpm rules:generate after changing rules, skills or subagents, then pnpm
+rules:check. AGENTS.md, CLAUDE.md, .agents/skills, .claude/skills, .claude/agents
+and .codex/agents are generated copies.

package/agent-template/CLAUDE.md

@@ -78,5 +78,6 @@ made in the Flowdular repository and released before this application uses it.
 The skills and examples use @flowdular/sdk subpath imports. For pnpm --filter,
 read the actual module package name from its package.json. Use pnpm verify and
 pnpm build for this application. Root .ai files are editable project guidance;
-run pnpm rules:generate after changing rules or skills, then pnpm rules:check.
-AGENTS.md, CLAUDE.md, .agents/skills and .claude/skills are generated copies.
+run pnpm rules:generate after changing rules, skills or subagents, then pnpm
+rules:check. AGENTS.md, CLAUDE.md, .agents/skills, .claude/skills, .claude/agents
+and .codex/agents are generated copies.

package/agent-template/docs/cli.md

@@ -33,6 +33,9 @@ flowdular module version <id>                      # version, platformApi range,
 flowdular module version bump <id> <level> [--apply] # patch|minor|major across module.json, package.json, specVersion and dependent ranges
 flowdular module new <id> --spec <path> [--apply]  # scaffold from an approved spec
 flowdular module enable|disable <id> [--apply]     # composition and scope grants
+flowdular web list                                 # the addresses this workspace serves module pages at
+flowdular web mount <module id> <surface id> --path <path> --tenant <id> [--id <mount id>] [--apply]
+flowdular web unmount <mount id> [--apply]         # stop serving that site
 flowdular migration status [--module <id>]         # migration ledger
 flowdular migration apply --module <id> [--apply]
 flowdular migration verify                         # checksum drift, row security, file and constant parity

package/agent-template/docs/configuration.md

@@ -18,6 +18,33 @@ 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                                 |
 
+## Branding
+
+The name, the document title, the description, the link preview image, the
+browser icon, the theme colour and the logo are not environment variables: they
+are `system.core` settings an owner with `system.settings.manage` changes under
+Administration, Branding, and every change is audited. One value serves the
+whole deployment, so the sign-in screen and a shared link carry it too, and a
+setting nobody changed renders the product's own.
+
+An address is stored only as a path on this deployment (`/brand/logo.svg`) or an
+https URL; `javascript:`, `data:` and protocol-relative values are refused when
+they are written. Every https branding image origin is added to `img-src` of the
+policy this deployment serves, including an `FD_CSP` of your own, so the browser
+loads it; an `FD_CSP` without an `img-src` directive is left alone and then has
+to name the origin itself. The label an authenticator lists an enrolled account
+under is the same name, decided by the server, so a member who enrols after a
+rename sees the new one.
+
+An application scaffolded before this release owns its own `platform/src/App.tsrx`
+and `platform/index.html`, so its head does not follow the settings until it
+adopts two changes the template now carries: `configureBrandingFromPage(props)`
+plus the `Seo`, `Link` and `Meta` block in the entry, and the removal of the
+static `<link rel="icon">` and `<meta name="theme-color">` from the page, which
+would otherwise compete with the rendered ones. `pnpm flowdular doctor` reports
+both as the `platform.branding` check. The navigation, the mobile header and the
+sign-in screen follow the settings without any change.
+
 ## Observability
 
 Spans are always recorded into a bounded in-process buffer and the logger always
@@ -583,6 +610,23 @@ deployment on the old names keeps working and the server logs one
 replacement. The platform name wins when both are set, and every refusal names
 the variable the deployment actually set.
 
+The relay is also five platform-scoped `auth.core` settings, edited under
+Administration, Modules: `mailTransport` (`environment`, `none` or `smtp`),
+`mailSmtpUrl` (secret, write only), `mailFrom`, `mailRequireTls` and
+`mailRejectUnauthorized`. `mailTransport` decides which source wins. It is
+`environment` by default, and while it stays there the `FD_MAIL_*`
+configuration above is in effect exactly as described, deprecation warnings
+included; storing `none` or `smtp` overrides the environment for every sender of
+the installation. `development` is reachable only through the environment and is
+never settable from the UI. A stored relay is resolved when a message is sent,
+so a change carries the next message without a restart, and the built transport
+is cached by a digest of the effective configuration. Storing `smtp` without a
+relay URL or without a sender is refused, as is a URL that is not `smtp://` or
+`smtps://` and a sender the sender rule rejects; the refusal names the setting
+and never carries its value. Administration, Settings states which source and
+which transport are in effect and sends a test message to the signed-in
+address.
+
 `none` refuses every message with `MAIL_NOT_CONFIGURED` and sends nothing.
 `development` keeps the last 100 messages in memory for a local run and a test
 and is refused at boot in production, where it would be silent data loss.

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

@@ -17,9 +17,15 @@ shared primitives, tokens, and the rules for using them.
 - Modules: compose screens from `@flowdular/sdk/ui`. Module CSS may only add
   module-specific composites built on the tokens (example:
   `modules/agents/src/client/agents.css`).
+- `modules/<dir>/design/*.html`: a screen as markup, rendered with the
+  stylesheets above by `pnpm ui:preview <path>` (`--scaffold` writes the record
+  recipe in all five states, `--shot <file.png>` captures it). It is where a
+  screen is designed and agreed before it is a component, and it carries no CSS
+  of its own, so it cannot drift from the platform. `pnpm ui-classes:check`
+  refuses a class no stylesheet declares, there and in every `.tsrx`.
 - `platform/public`: `favicon.svg`, `og.png` (1200x630 Open Graph image).
 - Brand mark geometry is generated: `node packages/ui/scripts/gen-mark.mjs`
-  rewrites `packages/ui/src/brand/mark.ts` from the weave parameters.
+  rewrites `packages/ui/src/brand/mark.ts` from the bar parameters.
 
 ## Rules
 
@@ -276,7 +282,7 @@ them; outside the shell the English defaults and the host locale apply.
 | `Switch`           | Boolean setting that applies on its own (no form submit): `checked`, `label` as the accessible name, `disabled`, `onChange`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `ConfirmDialog`    | One question before an irreversible action: `open`, `title`, children, `confirmLabel`, `tone` danger (default) or primary, `busy`, `onConfirm`, `onCancel`; traps Tab and restores focus to the opener                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `Icon`             | Stroke icon by `name` from `ICON_PATHS`; `size` 18 default, 16 in controls, 14 in `Button size="sm"`; `strokeWidth` 1.75 default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `BrandMark`        | The weave: `size`, `signature` (copper weft, large brand moments only), `tone` brand, current, inverse                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `BrandMark`        | Three bars, the short one copper: `size`, `tone` brand, current, inverse (`signature` is accepted and changes nothing)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 
 `Drawer` takes one child, a `ui-drawer__form` (fields in `ui-drawer__body`, actions in `ui-drawer__foot`) or a plain `ui-drawer__body`; it closes on Escape and on the scrim. `SearchField` carries no visible label, so pass `label` as its accessible name. `FormField` renders `error` in place of `help` and marks it `role="alert"`. `SettingRow` is presentation only: the caller owns the draft value, the save call, and passes the result back as `status`. `ScopeSummary` is the read side of `CheckGrid`; both keep the first-seen module order, and `summarizeScopes` is exported for callers that need the grouping without the markup.
 
@@ -407,7 +413,8 @@ Icon names (`packages/ui/src/icons/Icon.tsrx`): `dashboard`, `parties`, `catalog
 - Drawer: `ui-drawer__form` (scrolling body plus pinned footer),
   `ui-drawer__body`, `ui-drawer__foot`
 - Settings rows inside a `ui-card` or a drawer `ui-form__section`, rendered
-  by `SettingRow`: `ui-setting`
+  by `SettingRow`: `ui-setting`, grouped in a card by `ui-setting-group` with
+  `ui-setting-group__head` (the group's name on the rows' own inset)
   (+`__text` for title, scope tag, and help, `__control` for the one-line
   control cluster, `__status` (+`--error`) for the inline result)
 - Buttons: `ui-btn` with `--primary`, `--secondary`, `--ghost`, `--danger`,

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

@@ -63,7 +63,27 @@ runtime and the module's existing bundles when localization is needed.
 
 ## Operator configuration
 
-Add the optional `web` section in the installation's `flowdular.json`:
+One command writes the mount and regenerates the composition:
+
+```bash
+pnpm flowdular web mount example.core public --path /blog --tenant <tenant id>          # preview
+pnpm flowdular web mount example.core public --path /blog --tenant <tenant id> --apply
+pnpm flowdular web list
+pnpm flowdular web unmount acme-public --apply
+```
+
+It refuses before it writes what the platform would refuse at boot: a module
+this workspace has not enabled, a reserved address, the configured backoffice
+path, an address overlapping a site already mounted, and a mount naming no
+workspace. The mount id defaults to the module's first segment; `--id` names it
+when one module serves several addresses, and mounting the same id again moves
+that site rather than adding a second one.
+
+The tenant is the workspace whose pages are served, so it exists before the
+mount does: run `flowdular setup` first and use the id it reports.
+
+The same section can be written by hand in the installation's
+`flowdular.json`:
 
 ```json
 {
@@ -82,7 +102,8 @@ Add the optional `web` section in the installation's `flowdular.json`:
 }
 ```
 
-Run `pnpm flowdular module sync --apply`, then rebuild/redeploy production or
+A hand-written section needs `pnpm flowdular module sync --apply` afterwards;
+the `web` commands run it themselves. Then rebuild or redeploy production, or
 restart development. Configuration is generated into the server composition;
 changing it requires regeneration. It is not read from a process-local settings
 cache or an anonymous query parameter. Verify the tenant ID before publishing.
@@ -91,7 +112,14 @@ paths. `/records/:slug` above becomes `/blog/records/:slug`.
 
 The root `/` can host a public storefront, alongside more specific mounts such as
 `/blog`. Reserved platform prefixes such as `/app`, `/auth`, `/api`, `/setup` and
-the configured backoffice path cannot be claimed by modules. Other overlapping
+the configured backoffice path cannot be claimed by modules; the list is
+`RESERVED_WEB_SEGMENTS` in `@flowdular/sdk/contracts`, which the composition and the
+CLI both read. A segment may carry dots inside it, so a page answers at
+`/rss.xml`, `/sitemap.xml` or `/robots.txt` as a reader or a crawler expects;
+each dot separates two non-empty groups, which keeps `..`, a leading dot and a
+trailing dot out of every address. A mount naming a surface its module does not declare stops the
+composition with that sentence, rather than answering 404 at the address for the
+life of the deployment. Other overlapping
 mounts and equivalent route patterns are rejected. Custom paths such as `/blog`, `/portal` and `/forms/contact` work without a
 tenant ID in the URL. `/sites/` is an optional convention for multiple sites;
 unknown sites under that prefix return 404. A disabled binding

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

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/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

@@ -386,6 +386,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.1",
+	"version": "0.5.1",
 	"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

@@ -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/README.md

@@ -33,11 +33,13 @@ install. Data lives under `.flowdular/data`.
 ## Work with coding agents
 
 `AGENTS.md` and `CLAUDE.md` introduce the application contract. `.ai` contains the
-editable rules, skills, role prompts, policies, blueprints and reference module.
-Codex and Claude Code discover generated skills in `.agents/skills` and
-`.claude/skills`. Supporting guides are in `docs`.
+editable rules, skills, role prompts, subagents, policies, blueprints and
+reference module. Codex and Claude Code discover generated skills in
+`.agents/skills` and `.claude/skills`, and the spec author, module executor and
+reviewer as subagents in `.codex/agents` and `.claude/agents`. Supporting guides
+are in `docs`.
 
-After editing `.ai/rules` or `.ai/skills`, run `pnpm rules:generate`.
+After editing `.ai/rules`, `.ai/skills` or `.ai/subagents`, run `pnpm rules:generate`.
 `pnpm rules:check` detects drift and also runs as part of `pnpm verify`.
 Extend local modules using the published `@flowdular/sdk` imports. Installed
 SDK source is reference material and must not be edited in `node_modules`.

package/template/default/modules/example/module.json

@@ -14,7 +14,7 @@
 	"dependencies": [
 		{
 			"id": "auth.core",
-			"range": "^0.13.0"
+			"range": "^0.14.0"
 		}
 	],
 	"tenancy": "required",

package/template/default/modules/example/package.json

@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.1",
-		"@flowdular/sdk": "0.4.1"
+		"@flowdular/sdk": "0.5.1"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/template/default/modules/example/spec/module.yaml

@@ -12,7 +12,7 @@ capabilities:
   - translations
 dependencies:
   - id: auth.core
-    range: ^0.13.0
+    range: ^0.14.0
 tenancy: required
 locales:
   - en

package/template/default/package.json

@@ -9,7 +9,7 @@
 	},
 	"scripts": {
 		"dev": "node --env-file-if-exists=.env platform/scripts/dev.mjs",
-		"sandbox": "npx @flowdular/sandbox",
+		"sandbox": "flowdular-sandbox",
 		"typecheck": "pnpm -r --if-present typecheck",
 		"test": "pnpm -r --if-present test",
 		"format": "prettier --write .",
@@ -23,9 +23,10 @@
 		"build": "flowdular module sync --apply && pnpm --filter @app/platform build"
 	},
 	"devDependencies": {
+		"@flowdular/sandbox": "0.5.1",
 		"@tsrx/prettier-plugin": "0.3.120",
 		"prettier": "3.6.2",
-		"flowdular": "0.4.1",
+		"flowdular": "0.5.1",
 		"rulesync": "16.21.0"
 	}
 }