docs(validate,plan): an id the build phase refuses is a validate and plan warning (forge-cli#813)

docs/cli/apply.md

@@ -201,7 +201,7 @@ There is no flag to skip the check. Run `fluid validate <contract> --env <env>`
 
 *On forge-cli `main`, not yet in a release ([forge-cli #803](https://github.com/Agenticstiger/forge-cli/pull/803)).* Under `--mode amend-and-build` or `replace-and-build`, `fluid apply` also checks `id` and every `builds[].id` right after the schema check. This happens on both engines, before the apply hooks, `tofu` and any build.
 
-The build phase keeps each build's run records, cursors and watermarks under `.fluid/runs/<id>/<build id>/`, so its rule is narrower than the schema's. An id must start with a letter or `_`, use only letters, digits, `_`, `.` and `-`, and be at most 128 characters. The schema also accepts a leading digit and any length. So `fluid validate` and `fluid plan` pass an id such as `1orders`, and `fluid apply` refuses it:
+The build phase keeps each build's run records, cursors and watermarks under `.fluid/runs/<id>/<build id>/`, so its rule is narrower than the schema's. An id must start with a letter or `_`, use only letters, digits, `_`, `.` and `-`, and be at most 128 characters. The schema also accepts a leading digit and any length. So `fluid validate` and `fluid plan` pass an id such as `1orders`, though on forge-cli `main` both [warn about it](./validate.md#an-id-the-build-phase-refuses) ([forge-cli #813](https://github.com/Agenticstiger/forge-cli/pull/813)), and `fluid apply` refuses it:
 
 ```bash
 fluid apply contract.fluid.yaml --mode amend-and-build --yes
@@ -211,7 +211,7 @@ fluid apply contract.fluid.yaml --mode amend-and-build --yes
 ❌ apply_build_identifier_invalid  [ERR_APPLY_BUILD_IDENTIFIER_INVALID]
   field: contract.id
   value: '1orders'
-  hint: The build phase keeps each build's run records, cursors and watermarks under .fluid/runs/<contract.id>/<build.id>/, so both ids must start with a letter or underscore, use only letters, digits, '_', '.' and '-', and be at most 128 characters. The contract schema allows more, so fluid validate and fluid plan accept it. Nothing was applied.
+  hint: The build phase keeps each build's run records, cursors and watermarks under .fluid/runs/<contract.id>/<build.id>/, so both ids must start with a letter or underscore, use only letters, digits, '_', '.' and '-', and be at most 128 characters. The contract schema allows more, so fluid validate and fluid plan only warn about it. Nothing was applied.
 
 💡 Suggestions:
   • Rename the id to fit, for example orders_v1 instead of 1orders, and apply again

docs/cli/plan.md

@@ -174,6 +174,7 @@ fluid apply runtime/plan.json --mode amend --yes
 ## Notes
 
 - `plan` is the safest place to preview a provider override or environment overlay before you run `apply`.
+- *On forge-cli `main`, not yet in a release ([forge-cli #813](https://github.com/Agenticstiger/forge-cli/pull/813)).* For a contract with `builds`, `plan` prints the warning [`fluid validate` gives](./validate.md#an-id-the-build-phase-refuses) for an `id` or `builds[].id` the build phase refuses, and still writes the plan, whatever `--mode` says. `fluid apply` in a build mode refuses that id before it applies anything; see [Build ids](./apply.md#build-ids).
 - The generated plan can be passed to [`fluid apply`](./apply.md) — the digests pin the apply to exactly this plan.
 - When planning from a tgz bundle directly, `bundleDigest` is populated from `MANIFEST.json`. When planning from a raw YAML contract, `bundleDigest` is an empty string and only `planDigest` is verified.
 

docs/cli/validate.md

@@ -400,6 +400,24 @@ For a build of the last kind, `fluid apply --mode amend-and-build` prints:
 
 The check runs on the contract file and on a bundle's resolved contract, not in [workspace mode](#validating-without-a-contract-path).
 
+## An id the build phase refuses
+
+*On forge-cli `main`, not yet in a release ([forge-cli #813](https://github.com/Agenticstiger/forge-cli/pull/813)).* The build phase puts `id` and each `builds[].id` in directory names and generated code, so its rule is narrower than the schema's: an id must start with a letter or `_`, use only letters, digits, `_`, `.` and `-`, and be at most 128 characters. The schema also accepts a leading digit and any length. For a contract with `builds`, `fluid validate` warns about such an id:
+
+```text
+✅ Valid FLUID contract (schema v0.7.5)
+⚠️  1 warning(s)
+Validation completed in 0.003s
+
+Validation Warnings:
+====================
+ 1. contract.id '1orders' cannot be used by the build phase, which puts it in directory names and generated code, so it must start with a letter or underscore, use only letters, digits, '_', '.' and '-', and be at most 128 characters. fluid apply in a build mode (amend-and-build, replace-and-build) refuses this id before it applies anything. Rename it to fit.
+```
+
+Without `--strict` it exits `0`; with it, `1`. `--format json` lists it under `warnings`. The warning names the first id that fails, the one [`fluid apply` refuses](./apply.md#build-ids); after a rename, validate again for the next. A contract without `builds` is not checked. [`fluid plan`](./plan.md#notes) prints the same warning and still writes the plan.
+
+The check runs on the contract file and on a bundle's resolved contract, not in [workspace mode](#validating-without-a-contract-path).
+
 ## Validating a bundle (`.tgz`)
 
 Pass a bundle built with `fluid bundle --format tgz` and `fluid validate` checks the bundle itself and the contract inside it:

docs/upgrading.md

@@ -642,6 +642,12 @@ These changes are merged and in no release yet. Most fail closed where a contrac
   `apply_build_id_not_found`, which lists the contract's build ids. The exit code is still
   `1`. A Command Center run records the event `apply_build_id_not_found` where it recorded
   `build_not_found:<id>`. See [Build ids](./cli/apply.md#build-ids).
+- **`fluid validate` and `fluid plan` warn about an id the build phase refuses**
+  ([#813](https://github.com/Agenticstiger/forge-cli/pull/813)). For a contract with
+  `builds`, an `id` or `builds[].id` that starts with a digit or is longer than 128 characters is
+  a validate warning, so `fluid validate --strict` fails on it. `fluid plan` prints it and still
+  writes the plan. Rename the id: `fluid apply` in a build mode refuses it anyway. See
+  [An id the build phase refuses](./cli/validate.md#an-id-the-build-phase-refuses).
 - **`fluid doctor --strict` and a readable failed apply**
   ([#786](https://github.com/Agenticstiger/forge-cli/pull/786)). `fluid doctor --strict` exits `1`
   when the summary says "Action needed", copilot readiness included; the default exit code does not