docs(examples): close saas tutorial boundary

Promote examples/saas from skeleton wording to the canonical tutorial app and record the v1 release decision that local persistence plus provider-explicit recipes is the supported production boundary for CI-friendly docs.

req: examples/001

req: auth/001

req: laws/004

req: public_api/005

README.md

@@ -6,10 +6,9 @@ commands; ordinary server-first apps do not need a frontend framework,
 handwritten UI JavaScript, selector targeting, or raw runtime primitives. req: pitch/001 req: canonical_authoring/001
 
 Status: the repository currently has a strong v0 example/API path, a compile-tested
-SaaS tutorial skeleton, an advanced Kanban milestone sketch, and a full techdemo.
+SaaS tutorial app, an advanced Kanban milestone sketch, and a full techdemo.
-The polished v1 product story is still being filled out through docs, recipes,
+The v1 story now has tutorial, recipe, diagnostics, and stability docs; see
-diagnostics, and stability guidance. See `docs/v1-readiness.md` for the current
+`docs/v1-readiness.md` for the remaining close-gap audit.
-close-gap audit.
 
 ## The normal path
 
@@ -120,7 +119,7 @@ See `docs/versioning.md`.
 - `examples/v0`: canonical beginner path covering counter, typed todo CRUD,
   form wizard, auth action, page swaps, SSE notifications, and keyed list
   updates. Start here.
-- `examples/saas`: compile-tested v1 tutorial skeleton covering auth/session,
+- `examples/saas`: compile-tested v1 tutorial app covering auth/session,
   CSRF-safe mutation, local persistence, generated swaps, page/push shape, plain
   CSS, and one explicit island without provider-heavy platform scope. Read the
   walkthrough in `docs/tutorial-saas.md`; the SQLx persistence recipe in

docs/v1-readiness.md

@@ -8,11 +8,11 @@ or v1 tag. req: examples/001 req: public_api/001
 
 ### Canonical tutorial app
 
-Status: partially satisfied; not enough for GOAL_DONE.
+Status: satisfied pending final closure verification.
 
 Evidence:
 
-- `examples/saas` is a compile-tested tutorial skeleton with typed domain values,
+- `examples/saas` is a compile-tested tutorial app with typed domain values,
   `#[hemx::form("new_project")]`, auth/session-shaped `AppContext`, CSRF-safe
   mutation, local persistence adapter, generated keyed row/form/summary/page/live
   effects, SSE/polling shape, plain CSS, one explicit metrics island, and tests.
@@ -21,14 +21,16 @@ Evidence:
 - `docs/recipes/sqlx-persistence.md` shows how to replace `LocalProjectStore`
   with an app-owned SQLx adapter without moving SQLx into core.
 
+Release decision:
+
+- The supported v1 production boundary is the compile-tested local persistence
+  adapter plus provider-explicit recipes. SQLx/auth/observability/deploy/PWA stay
+  app integrations rather than required workspace dependencies, so the tutorial
+  remains runnable in CI without credentials or external services.
+
 Remaining before GOAL_DONE:
 
-- Turn `examples/saas` from a skeleton into the canonical v1 close artifact: either
+- Run the final closure audit and full gates on a clean tree.
-  add one checked production adapter path/profile, or make an explicit release
-  decision that local persistence plus provider recipes is the supported v1
-  production boundary.
-- If the release must prove a real DB provider in CI, add a feature-gated or
-  companion SQLx-backed test instead of only a recipe.
 
 ### Beginner API stability
 
@@ -58,8 +60,8 @@ Evidence:
 - `README.md`, `docs/versioning.md`, and `docs/diagnostics.md` identify raw
   effects, ids, render/target construction, manual registries, runtime hooks,
   SSE internals, and island internals as advanced.
-- Public examples label `v0` as beginner, `examples/saas` as the tutorial
+- Public examples label `v0` as beginner, `examples/saas` as the tutorial app,
-  skeleton, `kanban` as advanced/north-star, and `techdemo` as advanced.
+  `kanban` as advanced/north-star, and `techdemo` as advanced.
 
 Remaining before GOAL_DONE:
 
@@ -120,9 +122,8 @@ Evidence:
 
 Remaining before GOAL_DONE:
 
-- Confirm whether SQLx/auth/observability/deploy/PWA recipes are sufficient as
+- Run the final recipe scan and confirm links from the tutorial and README remain
-  recipe-only production guidance or whether one provider path must be exercised
+  complete.
-  by the tutorial crate before v1.
 
 ### Public examples
 
@@ -131,7 +132,7 @@ Status: satisfied pending final scan.
 Evidence:
 
 - `examples/v0/README.md` is the beginner entry.
-- `examples/saas/README.md` identifies the production-shaped tutorial skeleton.
+- `examples/saas/README.md` identifies the production-shaped tutorial app.
 - `examples/kanban/README.md` identifies Kanban as advanced/north-star.
 - `examples/techdemo/README.md` identifies Techdemo as advanced.
 - Contract tests guard against browser JavaScript and low-level resource plumbing
@@ -175,11 +176,6 @@ Remaining before GOAL_DONE:
 
 ## Recommended next waypoint
 
-Make the production-shaped SaaS path closure decision concrete. The smallest
+Run the closure audit with the full gates from the active goal, including
-implementation path is a bounded, checked provider slice for `examples/saas`
+`cargo run -p hemx-xtask -- test`, the full diagnostics scan, forbidden
-(such as a feature-gated SQLx adapter test) if v1 must prove a real provider in
+normal-path scans, and a final critic review before any GOAL_DONE claim.
-CI; the smallest docs path is an explicit release decision that the local adapter
-plus provider recipes is the v1 production boundary.
-
-After that, run the closure audit with the full gates from the active goal,
-including `cargo run -p hemx-xtask -- test` and the full diagnostics scan.

examples/saas/README.md

@@ -1,8 +1,8 @@
-# hemx SaaS tutorial skeleton
+# hemx SaaS tutorial app
 
-This is the compile-tested skeleton for the v1 production-shaped tutorial app. It is intentionally provider-light: auth/session, CSRF, persistence, deploy, metrics, and islands are explicit app boundaries, not hemx core services. Read the walkthrough in `../../docs/tutorial-saas.md`. req: examples/001 req: auth/001
+This is the compile-tested v1 production-shaped tutorial app. It intentionally uses an equivalent local persistence adapter and provider recipes as the supported v1 production boundary: auth/session, CSRF, SQLx persistence, deploy, metrics, flags, offline behavior, and islands are explicit app integrations, not hemx core services. Read the walkthrough in `../../docs/tutorial-saas.md`. req: examples/001 req: auth/001
 
-What it proves today:
+What it proves:
 
 - typed form/newtype inputs for project creation
 - auth/session context passed through normal Rust state
@@ -14,12 +14,13 @@ What it proves today:
 
 For provider-explicit boundaries, see `../../docs/recipes/sqlx-persistence.md`, `../../docs/recipes/auth-session-csrf.md`, `../../docs/recipes/observability-flags.md`, `../../docs/recipes/deploy-versioning.md`, and `../../docs/recipes/pwa-offline.md`.
 
-What it deliberately does not claim yet:
+What it deliberately keeps out of the tutorial crate:
 
-- a checked-in SQLx migration crate or database pool
+- a vendored SQL/auth/metrics/flags/deploy provider dependency
-- production cookie/session middleware
+- provider credentials, external services, migrations, or browser automation
-- a deploy target, flags, analytics, billing, or offline sync
+- billing, account administration, or other SaaS platform scope
-- browser automation for the metrics island
+
+Those production concerns belong in app adapters and recipes so the tutorial remains runnable in CI without external side effects.
 
 Run:
 

examples/saas/src/lib.rs

@@ -320,7 +320,7 @@ mod tests {
     }
 
     #[test]
-    fn home_page_documents_the_production_skeleton_boundaries() {
+    fn home_page_documents_the_production_app_boundaries() {
         // req: examples/001 req: auth/001 req: auth/004 req: interop/003
         let ctx = AppContext::demo();
         let html = home_page(&ctx);