Unify trial-start doc anchors

docs/release-control/v6/internal/subsystems/cloud-paid.md

@@ -601,7 +601,11 @@ That active-doc hygiene is guarded directly in
 trial-start reference across `docs/` and `tests/integration/`, requires the
 operator/pricing/upgrade/integration surfaces to keep the hosted-only /
 retry-burst story aligned, and rejects the obsolete 24-hour or automatic
-second-attempt phrasing anywhere in that tracked reference set.
+second-attempt phrasing anywhere in that tracked reference set. The integration
+README now carries the same `POST /api/license/trial/start`,
+`trial_signup_required`, and `trial_rate_limited` anchors as the other
+operator-facing docs so it stays inside the discovered set instead of relying
+on a special-case assertion path.
 Hosted tenant organization seeding and hosted handoff role mapping now belong
 to the same cloud-paid truth too. `internal/cloudcp/stripe/provisioner.go`
 must seed tenant org members from the shared account-role-to-organization-role

docs/release-control/v6/internal/subsystems/deployment-installability.md

@@ -458,7 +458,12 @@ local `/api/license/trial/start` requests as staying on the hosted-signup
 redirect contract until the configured retry burst is exhausted; they may only
 teach `429 trial_rate_limited` plus `Retry-After` backoff once the limiter
 actually engages, rather than claiming the second duplicate attempt is always
-rate limited.
+rate limited. The reused-instance browser-proof entry in
+`tests/integration/README.md` must carry those same canonical anchors by name:
+`POST /api/license/trial/start`, `409 trial_signup_required`, `429
+trial_rate_limited`, and `Retry-After`, so the shared trial-start docs guard
+can auto-discover that README alongside the rest of the governed trial-start
+surface instead of relying on README-only fallback checks.
 Playwright-driven public/commercial specs that support scenario-specific
 endpoint overrides such as `PULSE_CLOUD_BASE_URL` or
 `PULSE_COMMERCIAL_BASE_URL` must layer those values through that same shared

scripts/tests/test-hot-dev-bg.sh

@@ -718,6 +718,9 @@ test_integration_readme_documents_trial_retry_burst_contract() {
     ' "${INTEGRATION_README}"
   )"
 
+  assert_contains "integration readme names trial-start route" "${output}" "POST /api/license/trial/start"
+  assert_contains "integration readme names hosted-signup redirect code" "${output}" "409 trial_signup_required"
+  assert_contains "integration readme names rate-limited code" "${output}" "429 trial_rate_limited"
   assert_contains "integration readme documents hosted-signup retry burst" "${output}" "retry-burst"
   assert_contains "integration readme documents retry contract wording" "${output}" "contract:"
   assert_contains "integration readme keeps hosted-signup wording" "${output}" "hosted-signup"

scripts/tests/test-trial-signup-docs.sh

@@ -111,15 +111,15 @@ assert_forbidden_patterns_absent() {
 main() {
   local runbook_output pricing_output upgrade_output integration_output eval_task_output
   local source_of_truth_output migration_audit_output
+  local operator_doc
 
   discover_tracked_reference_docs
 
   assert_doc_discovered "source of truth is in tracked reference discovery" "${SOURCE_OF_TRUTH_DOC}"
   assert_doc_discovered "migration audit is in tracked reference discovery" "${MIGRATION_AUDIT_DOC}"
-  assert_doc_discovered "runbook is in tracked reference discovery" "${RUNBOOK}"
-  assert_doc_discovered "pricing doc is in tracked reference discovery" "${PRICING_DOC}"
-  assert_doc_discovered "upgrade guide is in tracked reference discovery" "${UPGRADE_DOC}"
-  assert_doc_discovered "trial eval task is in tracked reference discovery" "${EVAL_TASK_DOC}"
+  for operator_doc in "${OPERATOR_DOCS[@]}"; do
+    assert_doc_discovered "${operator_doc#${ROOT_DIR}/} is in tracked reference discovery" "${operator_doc}"
+  done
 
   runbook_output="$(
     awk '
@@ -165,6 +165,9 @@ main() {
   assert_contains "upgrade guide documents trial-rate-limited response" "${upgrade_output}" "\`429 trial_rate_limited\`"
   assert_contains "upgrade guide documents retry-after metadata" "${upgrade_output}" "\`Retry-After\`"
 
+  assert_contains "integration readme documents trial-start route" "${integration_output}" "POST /api/license/trial/start"
+  assert_contains "integration readme documents hosted-signup redirect code" "${integration_output}" "\`409 trial_signup_required\`"
+  assert_contains "integration readme documents canonical trial-rate-limited response" "${integration_output}" "\`429 trial_rate_limited\`"
   assert_contains "integration readme documents reused-instance retry-after branch" "${integration_output}" "Retry-After"
   assert_contains "integration readme documents hosted-signup retry burst" "${integration_output}" "hosted-signup retry-burst contract"
 

tests/integration/README.md

@@ -28,8 +28,8 @@ End-to-end Playwright tests that validate critical user flows against a running
   - Logged-out login page (full page + form card)
   - Authenticated Settings → Authentication page
 - `tests/07-trial-signup-return.spec.ts` — trial workflow contract:
-  - Start hosted Pro trial initiation via API and verify the reused-instance contract
-  - Verify the response either points to hosted `/start-pro-trial` or returns canonical `Retry-After` backoff when the local retry bucket is already exhausted
+  - Start hosted Pro trial initiation via `POST /api/license/trial/start` and verify the reused-instance contract
+  - Verify the response either returns `409 trial_signup_required` with hosted `/start-pro-trial` handoff or `429 trial_rate_limited` with canonical `Retry-After` backoff when the local retry bucket is already exhausted
   - Verify local entitlements remain unchanged until activation
   - Verify duplicate initiation stays on the hosted-signup retry-burst contract
 - `tests/08-cloud-hosting.spec.ts` — hosted cloud signup contract:
@@ -181,9 +181,12 @@ For hosted trial initiation validation against a fresh LXC each run:
 
 - Runbook: `docs/operations/TRIAL_E2E_LXC_SNAPSHOT_RUNBOOK.md`
 - Probe script: `tests/integration/scripts/trial-signup-contract.sh`
-  - Confirms repeated local trial starts stay on the hosted-signup retry-burst
-    contract: duplicate attempts keep returning hosted-signup redirects until
-    the retry burst is exhausted, then return `Retry-After` backoff metadata
+  - Exercises `POST /api/license/trial/start` from a clean snapshot and proves
+    the hosted-signup retry-burst contract: duplicate attempts keep returning
+    `409 trial_signup_required` with hosted redirects while the burst remains
+    open, then transition to `429 trial_rate_limited` plus `Retry-After`
+    backoff metadata once the retry burst is exhausted and the limiter
+    actually engages
 - Full sandbox orchestration (multi-tenant + trial + cloud, with per-scenario snapshot reset):
   - `tests/integration/scripts/run-lxc-sandbox-evals.sh`
   - Includes hosted trial initiation validation and cloud subscription cancellation lifecycle verification