tmk241/hemx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(examples): close saas tutorial boundary

Browse Source 
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
This commit is contained in:
slhx agent
2026-06-05 10:06:46 +02:00
parent 78aff362ff
commit a428097e0e
4 changed files with 32 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/v1-readiness.md
+18 -22
View File
@@ -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
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.
- Run the final closure audit and full gates on a clean tree.
### 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
skeleton, `kanban` as advanced/north-star, and `techdemo` as advanced.
- Public examples label `v0` as beginner, `examples/saas` as the tutorial app,
`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
recipe-only production guidance or whether one provider path must be exercised
by the tutorial crate before v1.
- Run the final recipe scan and confirm links from the tutorial and README remain
complete.
### 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
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, run the closure audit with the full gates from the active goal,
including `cargo run -p hemx-xtask -- test` and the full diagnostics scan.
Run the closure audit with the full gates from the active goal, including
`cargo run -p hemx-xtask -- test`, the full diagnostics scan, forbidden
normal-path scans, and a final critic review before any GOAL_DONE claim.