docs(hemx): audit v1 readiness gaps

Add a v1 readiness audit against the active Close when, clarifying satisfied vs remaining gaps and naming the next concrete waypoint before any GOAL_DONE attempt.

req: examples/001

req: public_api/001

req: diagnostics/001

req: runtime/003

req: runtime/004

README.md

@@ -8,7 +8,8 @@ handwritten UI JavaScript, selector targeting, or raw runtime primitives. req: p
 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.
 The polished v1 product story is still being filled out through docs, recipes,
-diagnostics, and stability guidance.
+diagnostics, and stability guidance. See `docs/v1-readiness.md` for the current
+close-gap audit.
 
 ## The normal path
 

docs/v1-readiness.md

@@ -0,0 +1,187 @@
+# v1 readiness audit
+
+This audit tracks the current hemx v1 northstar against the active Close when.
+It is a checkpoint, not the release announcement: update it before any GOAL_DONE
+or v1 tag. req: examples/001 req: public_api/001
+
+## Close-when status
+
+### Canonical tutorial app
+
+Status: partially satisfied; not enough for GOAL_DONE.
+
+Evidence:
+
+- `examples/saas` is a compile-tested tutorial skeleton 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.
+- `docs/tutorial-saas.md` walks through the app from template to production
+  provider handoff.
+- `docs/recipes/sqlx-persistence.md` shows how to replace `LocalProjectStore`
+  with an app-owned SQLx adapter without moving SQLx into core.
+
+Remaining before GOAL_DONE:
+
+- Turn `examples/saas` from a skeleton into the canonical v1 close artifact: either
+  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
+
+Status: mostly satisfied; final release audit still required.
+
+Evidence:
+
+- Normal path is documented around `app`, `component`, `handler`, `form`,
+  `page`, generated helpers, tuple `IntoEffect`, and `Result<impl IntoEffect, E>`
+  mapping.
+- `docs/versioning.md` defines stable beginner API vs wire/runtime ABI vs
+  advanced escape hatches.
+- `examples/v0` and `examples/saas` exercise the normal path without manual
+  registries or raw ids in app authoring.
+
+Remaining before GOAL_DONE:
+
+- Run a final API surface audit before v1 and either accept current names or make
+  the last naming changes before declaring stability.
+
+### Advanced APIs isolated
+
+Status: satisfied for docs/examples; final scan required.
+
+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
+  skeleton, `kanban` as advanced/north-star, and `techdemo` as advanced.
+
+Remaining before GOAL_DONE:
+
+- Re-run the forbidden-normal-path scan over README, docs, and public examples;
+  review any hits in explicit island/runtime/deploy sections as intentional.
+
+### Docs explain the model in one sitting
+
+Status: mostly satisfied.
+
+Evidence:
+
+- `README.md` explains render → slot/key → effect → runtime, forms/errors,
+  pages/push, CSS/islands, production boundaries, escape hatches, and
+  deploy/version compatibility.
+- `docs/tutorial-saas.md` provides the product walkthrough.
+- Recipes cover SQLx, auth/session + CSRF, observability/flags/killswitches, and
+  deploy/versioning.
+- `docs/diagnostics.md` and `docs/versioning.md` cover failure and release
+  policy.
+
+Remaining before GOAL_DONE:
+
+- Add a small docs index or check the root README is enough as the single entry
+  point for all tutorial/recipe/versioning pages.
+
+### Diagnostics
+
+Status: documented and substantially tested; coverage audit still required.
+
+Evidence:
+
+- `docs/diagnostics.md` names common mistakes and desired fixes in author
+  language.
+- Existing gates cover build diagnostics, derive compile-fail diagnostics,
+  runtime root/fingerprint behavior, and example contract checks.
+
+Remaining before GOAL_DONE:
+
+- Run the full diagnostics gate and confirm each required mistake class has
+  either an actual test or an explicitly accepted compiler diagnostic: missing
+  handler/form/slot/key/param, invalid form field type, unknown hemx attribute,
+  unsafe HTML boundary, wrong component/slot target, missing root/fingerprint,
+  and bad result error type.
+
+### Production recipes
+
+Status: mostly satisfied; optional PWA/offline remains unresolved.
+
+Evidence:
+
+- SQLx: `docs/recipes/sqlx-persistence.md`
+- auth/session + CSRF: `docs/recipes/auth-session-csrf.md`
+- observability/metrics + feature flags/killswitches:
+  `docs/recipes/observability-flags.md`
+- deploy/versioning: `docs/recipes/deploy-versioning.md`
+
+Remaining before GOAL_DONE:
+
+- Add a bounded optional PWA/offline recipe, or explicitly scope it out of v1 if
+  optional adapters are not required for the release.
+- Confirm whether SQLx/auth/observability/deploy recipes are sufficient as
+  recipe-only production guidance or whether one provider path must be exercised
+  by the tutorial crate before v1.
+
+### Public examples
+
+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/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
+  in canonical examples.
+
+Remaining before GOAL_DONE:
+
+- Re-run example contract tests and forbidden-pattern scans on a clean tree.
+
+### Runtime remains tiny and selectorless
+
+Status: satisfied in core; final runtime gate required.
+
+Evidence:
+
+- `README.md`, `docs/versioning.md`, `docs/recipes/deploy-versioning.md`, and
+  `docs/recipes/observability-flags.md` keep runtime scope to checked effect
+  application and reject VDOM/hydration/client-store/selector-retargeting growth.
+- `examples/saas/templates/metrics.js` uses selectors only inside an explicit
+  leaf island, not for normal hemx targeting.
+
+Remaining before GOAL_DONE:
+
+- Run `cargo test -p hemx-js` and audit runtime diff before closure.
+
+### Versioning explicit
+
+Status: satisfied pending final release check.
+
+Evidence:
+
+- `docs/versioning.md` defines semver tiers, wire/runtime ABI policy, advanced
+  escape-hatch policy, upgrade-note template, and release checklist.
+- `docs/recipes/deploy-versioning.md` documents release units, asset caching,
+  rolling deploy behavior, fingerprint mismatch behavior, and rollback checks.
+
+Remaining before GOAL_DONE:
+
+- Run final verification and confirm upgrade/versioning docs still match the
+  current generated ABI/runtime behavior.
+
+## Recommended next waypoint
+
+Make the production-shaped SaaS path closure decision concrete. The smallest
+implementation path is a bounded, checked provider slice for `examples/saas`
+(such as a feature-gated SQLx adapter test) if v1 must prove a real provider in
+CI; the smallest docs path is an explicit release decision that the local adapter
+plus provider recipes is the v1 production boundary.
+
+After that, either add the optional PWA/offline recipe or explicitly scope it out
+of v1, then run the closure audit with the full gates from the active goal,
+including `cargo run -p hemx-xtask -- test` and the full diagnostics scan.