create-astrale-domain 0.3.0-beta.16 → 0.3.0-beta.161

package/README.md

@@ -5,18 +5,58 @@ Official scaffolder for a new Astrale Domain project.
 During the SDK beta program, generate a project from the beta package set explicitly:
 
 ```bash
-npx -y create-astrale-domain@beta my-domain --yes
+npx -y create-astrale-domain@beta my-domain --yes --instance development
 ```
 
 The generated project must resolve the SDK and deployment adapters from npm; it must not retain
 workspace links or repository-only source paths.
 
+Managed generation requires an explicit Astrale instance and writes one installed `development`
+Environment; authors add staging and production only when their distinct instances exist.
+Cloudflare generation does not accept `--instance` and creates deploy-only development and
+production Environments. In both cases `pnpm dev` watches and deploys `development` remotely; no
+active instance, local Worker, Vite server, or tunnel is part of the standard Domain-author journey.
+An installed frontend Environment still opens its default View through generic Project tooling;
+stopping development closes only that local View session and retains the remote deployment and
+installation.
+
 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`.