create-astrale-domain 0.3.0-beta.17 → 0.3.0-beta.170

package/README.md

@@ -11,12 +11,63 @@ npx -y create-astrale-domain@beta my-domain --yes
 The generated project must resolve the SDK and deployment adapters from npm; it must not retain
 workspace links or repository-only source paths.
 
+Every generated Environment is canonical: each `astrale-domain deploy <environment>` makes one
+immutable deployment of the release, at its own URL, with a signing key generated for it, or reuses
+the deployment of the same release, whose changed secrets are then rewritten in place on that
+deployment only. A generated project names no instance, keeps no signing key file
+(`.astrale/identity.json`), and has no watch script: each change is deployed.
+
+- Managed generation (the default `astrale` adapter) deploys on Admin's Services. It writes
+  `development` and `production`, both using the authenticated Astrale CLI identity. There is no
+  organisation placeholder to configure before deploying.
+- Cloudflare generation (`--adapter cloudflare`) deploys into the platform's dispatch namespace,
+  where only the platform deploys (Shell, Services and the other platform Domains). It writes
+  `development` and `production` in namespace mode; replace the generated namespace placeholders
+  with the platform's namespace name and routing domain. A deploy on the placeholders is refused
+  before anything is uploaded. Every other Domain uses the default `astrale` adapter.
+
+No active instance, local Worker, Vite server, or tunnel is part of the standard Domain-author
+journey. A deploy never installs: install the URL it prints with
+`astrale domain install <url> --direct -i <instance>`. `--instance` was removed: which instance runs
+a deployment is chosen when its URL is installed.
+
 Generated projects have one package journey:
 
 ```bash
 pnpm pack
 ```
 
-The existing `astrale-domain package` command compiles the public Schema and independently loadable
-Runtime, normalizes emitted declarations to semantic SDK facades, and verifies the archive boundary.
-Deployment adapters remain development dependencies and are not part of the published Domain runtime.
+The existing `astrale-domain package` command compiles only the public Schema contract, normalizes
+emitted declarations to semantic SDK facades, and verifies the package boundary. Runtime, handlers,
+Providers, frontend code, and deployment adapters remain implementation inputs and are not part of
+the published Domain contract package.
+
+## Versions
+
+The version lives in the generated `package.json` and follows standard SemVer. A new Domain starts
+at the pre-release `0.1.0-alpha.0`: it has no stable version yet, so there is nothing for its first
+versions to stay compatible with. In `0.x`, a breaking change raises the minor (`^0.1` does not
+accept `0.2`) and a feature or fix raises the patch. Advance or leave the pre-release with the usual
+tools:
+
+- npm: `npm version prerelease --preid alpha` gives `0.1.0-alpha.1`; `npm version minor` (or
+  `patch`) leaves alpha at `0.1.0`.
+- Release Please: set `"versioning": "prerelease"`, `"prerelease": true`,
+  `"prerelease-type": "alpha"`, `"bump-minor-pre-major": true`, and
+  `"bump-patch-for-minor-pre-major": true` in `release-please-config.json`, plus
+  `"initial-version": "0.1.0-alpha.0"` while `.release-please-manifest.json` has no version for the
+  package (otherwise its first version is `1.0.0`). The two `bump-*-pre-major` flags apply the `0.x`
+  rule above, as in the SDK's own configuration. Each release PR then proposes the next pre-release
+  number (`0.1.0-alpha.1`, `0.1.0-alpha.2`, ...), whether its commits are fixes, features, or
+  breaking changes. To leave alpha, remove `"prerelease": true` and keep the other settings: the next
+  version is `0.1.0`, even with a breaking change pending. After that, a fix or a feature gives `0.1.1` and
+  a breaking change gives `0.2.0`.
+
+Keep both `bump-*-pre-major` flags: without them, a breaking change moves the project to
+`1.0.0-alpha.0` while in alpha, or to `1.0.0` when it leaves alpha or later. Do not leave Release
+Please on its default versioning while the version is a pre-release either: it bumps the numbers and
+copies the suffix unchanged (with the flags above, `0.1.0-alpha.0` becomes `0.1.1-alpha.0` after a
+fix or feature), so the project never leaves alpha.
+
+npm refuses to publish a pre-release without a dist-tag: pass one explicitly, for example
+`npm publish --tag alpha`.